diff --git a/.github/workflows/security-and-static-analysis.yml b/.github/workflows/security-and-static-analysis.yml
index d70a23a..cd91e21 100644
--- a/.github/workflows/security-and-static-analysis.yml
+++ b/.github/workflows/security-and-static-analysis.yml
@@ -2,9 +2,9 @@ name: Security & Static Analysis
on:
push:
- branches: [ "master", "develop" ]
+ branches: [ "master", "feature/*" ]
pull_request:
- branches: [ "master", "develop" ]
+ branches: [ "master", "feature/*" ]
schedule:
- cron: '30 1 * * 0' # 매주 일요일 01:30 정기검진
diff --git a/.idea/gradle.xml b/.idea/gradle.xml
index 0ead08a..2547228 100644
--- a/.idea/gradle.xml
+++ b/.idea/gradle.xml
@@ -9,6 +9,10 @@
diff --git a/README.md b/README.md
index 7b6cfb1..823687f 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,9 @@
-얽힘 라이브러리(EntanglementLib)는 양자 내성 암호(Post-Quantum Cryptography, PQC) 기술을 기반으로 설계된 고성능 보안 및 유틸리티 라이브러리입니다. 본 라이브러리는 진화하는 디지털 위협 환경에 대응하여 최고 수준의 보안과 시스템 안정성을 제공하는 것을 목표로 합니다.
+얽힘 라이브러리(EntanglementLib)는 모든 보안 연산을 안전하며, 빠르게 처리하도록 설계된 군사급 보안 라이브러리입니다. 고전 및 양자-내성 암호화(Post-Quantum Cryptography, PQC) 기술을 제공하며, 이를 사용한 미래지향적 TLS 프로토콜을 제공합니다.
+
+진화하는 디지털 위협 환경에 대응하여 최고 수준의 보안과 시스템 안정성을 제공하는 것을 목표로 합니다.
> [English README](README_EN.md)
@@ -14,125 +16,55 @@
얽힘 라이브러리의 모든 설계는 '군사적 보안', '금융 및 대규모 엔터프라이즈 환경에서의 안전한 인프라 확립'을 위한 보안성(security)을 최우선 원칙으로 합니다. 얽힘 라이브러리는 잠재적 보안 취약점을 원천적으로 방지하고, 데이터 무결성을 보장하도록 구현되었습니다. 두 번째 핵심 가치는 안정성(stability) 으로, 예측 가능하고 일관된 성능을 보장하기 위해 Rust 네이티브 연산을 적용하여 매우 안전하게 메모리 효율성을 극대화하고, 체계적인 오류(또는 예외) 처리 메커니즘을 갖추었습니다.
-## 강점
-
-얽힘 라이브러리는 다음의 강점을 보유하고 있습니다.
-
-1. 잔류 데이터 방지 (Anti-Data Remanence) 및 메모리 소거
- - 자바의 메모리 관리 모델인 가비지 컬렉터(Garbage Collection, GC)가 보안에 취약할 수 있다는 점을 정확히 파악하고 이를 기술적으로 극복하기 위한 기술이 탑재되었습니다.
- - 이 기술을 위해 [`entlib-native` 네이티브 라이브러리](https://github.com/Quant-Off/entlib-native)를 사용하여 안전하게 소거하도록 설계했습니다.
- - 모든 민감 정보를 안전하게 관리하기 위해 [데이터 컨테이너 기능](https://github.com/Quant-Off/entanglementlib/blob/master/src/main/java/space/qu4nt/entanglementlib/entlibnative/SensitiveDataContainer.java)을 제공합니다.
-2. 최신 PQC 표준 준수
- - FIPS 203, 204, 205에 따른 ML-KEM, ML-DSA, SLH-DSA 등의 NIST 표준화가 완료된 최신 알고리즘 및 AES, ARIA, ChaCha20과 같은 고전 알고리즘을 네이티브에서 처리하도록 하여 안전한 연산이 가능합니다.
-3. 아키텍처 및 디자인 패턴
- - 팩토리 패턴 및 인터페이스를 명확히 분리했습니다. [암호화 알고리즘은 전략적](https://github.com/Quant-Off/entanglementlib/tree/master/src/main/java/space/qu4nt/entanglementlib/security/crypto)으로 호출하여 사용할 수 있습니다.
-4. 예외 처리
- - 표준 예외를 그대로 던지지 않도록 했습니다. 얽힘 라이브러리만의 커스텀 예외 클래스로 래핑하여 명확한 문맥(context)을 제공했습니다.
- - 보안 측면에서 문제를 발견한 경우, 시스템이 해결 방법을 제시하고, 우려되는 공격(해킹)을 방어하도록 설계했습니다.
-
-## 주요 기능
-
-얽힘 라이브러리는 강력한 암호화 기능과 개발 생산성 향상을 위한 유틸리티를 포함합니다.
-
-| 모듈 | 기술 명세 |
-|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `security.crypto` | 양자 내성 암호(PQC) 및 현대 암호화 알고리즘을 제공합니다.
-
- space.qu4nt.entanglementlib
- entanglementlib
- 1.0.0
-
-
-```
+얽힘 라이브러리에서 FFM API를 사용하여 Rust 네이티브 함수를 호출할 떄 발생하는 나노세컨드 지연 등 다양한 연산에 대한 브릿지 벤치마킹을 수행하고 있습니다. 이러한 작업은 성능 및 보안성에 직결되며, 최적의 코드를 창출하기 위해 중요한 역할을 합니다.
-#### Gradle Project
+이 알파 버전에서 많은 벤치마킹 작업이 예정되어 있습니다. JMH(Java Microbenchmark Harness)를 통해 이 작업을 진행할 예정이며, 완료되는데로 새로운 문서에 정리하겠습니다.
-```kotlin
-repositories {
- mavenCentral()
-}
+## 기여
-dependencies {
- implementaion("space.qu4nt.entanglementlib:entanglementlib:1.0.0")
- // or Groovy
- // implementaion 'space.qu4nt.entanglementlib:entanglementlib:1.0.0'
-}
-```
+이 프로젝트는 현재 `Alpha` 버전이며, 아직 많이 부족합니다. 여러분의 피드백을 적극적으로 받을 준비가 이미 되어 있습니다. 얽힘 라이브러리는 단순히 PQC 알고리즘을 제공하는 것만이 아닌, 체계적으로 사용자 환경의 인프라 보안을 감시하고 사용자에게 해결책을 찾아주는 유능한 도구로써 사용되도록 개발됩니다. 최신 릴리즈부턴 이 신념에 강력한 초점을 맞출 것입니다.
## TODO
-이 프로젝트는 아직 많이 부족합니다. 얽힘 라이브러리는 미래에 금융 및 보안 인프라 프로덕션에서 사용할 수 있도록 다음의 TODO를 명확히 하고자 합니다.
+얽힘 라이브러리는 미래에 금융 및 보안 인프라 프로덕션에서 사용할 수 있도록 다음의 TODO를 명확히 하고자 합니다.
-- [ ] 공급자 유동화 및 팩토리 최적화
- - 사용자의 선택에 따라 Java의 기본 공급자를 사용할 수 있도록 수정해야 합니다. 그리고 `InternalFactory` 클래스를 포함한 대부분의 클래스에서 제공되는 팩토리를 최적화해야 합니다.
-- [ ] 전체 디자인 패턴 최적화
- - 현재 코드는 스파게티라고 해도 과언이 아닐 만큼 더러운 부분이 많이 보입니다. 제 방처럼 쾌적한 코드를 작성할 수 있도록 수정해야 합니다.
+- [ ] TLS 통신 로직 추가
+- [ ] 복합 검증 작업 준비 및 수행
+- [ ] 커스텀 예외 최적화
- [ ] JPMS 적용
- 안전한 캡슐화와 일관된 호출(또는 사용) 패턴이 완성되면 JPMS를 통해 캡슐화된 패키지를 모듈로서 관리하려고 합니다.
-- [ ] `BouncyCastle` 의존성 제거
- - 이제 `1.1.0` 릴리즈부턴 `BC` 의존성을 최소화하며, 끝내 제거하려고 합니다. 현재 AES, ARIA, ChaCha20 같은 고전 알고리즘은 여전히 `BC`에 의존하고 있습니다. 얽힘 라이브러리의 보안 철학을 확실히 하고자 모든 암호학적 연산은 `entlib-native`에서 수행하기로 결정했습니다.
+- [ ] 외부 의존성 최소화
+ - 이제 `1.1.0` 릴리즈부턴 `BouncyCastle` 의존성을 최소화하며, 끝내 제거하는 데 성공했습니다. 현재 코드 작성에 필요한 몇 가지 유용한 도구를 제공하는 의존성은 여전히 남아 있지만, 이들도 끝내 최소화될 예정입니다.
- [ ] `i18n` 업데이트
- 최신 릴리즈 개발을 수행하며 다국어 지원을 많이 누락했습니다. 구성 설정에 따라 각 언어별로 로깅을 지원할 수 있도록 수정해야 합니다.
@@ -151,18 +83,6 @@ dependencies {
- [X] 보안 기능에 대한 기술 명세 작성
- **해결**: 얽힘 라이브러리의 중요한 보안 관련 기능을 [별도의 문서](TECHNICAL.md)에 작성했습니다.
-## 기여
-
-초기 버전에서 얽힘 라이브러리는 'BouncyCastle 래퍼', '어중간한 데이터 소거', ... 와 같이 정말 애매모호한 목표를 가지고 있었습니다. 이 부분에 대해 꽤 많은 시간을 투자해 곰곰히 생각했으며, 얽힘 라이브러리만의 고유한 목표를 다시금 정립했습니다.
-
-이제 얽힘 라이브러리는 단순히 PQC 알고리즘을 제공하는 것만이 아닌, 체계적으로 사용자 환경의 인프라 보안을 감시하고 사용자에게 해결책을 찾아주는 유능한 도구로써 사용되도록 개발됩니다. 최신 릴리즈부턴 이 신념에 강력한 초점을 맞출 것입니다.
-
-그렇기 때문에... 얽힘 라이브러리의 궁극적 목표를 완성시키기 위해 여러 개발자분들의 힘이 필요합니다. 언제든 코드에 대한 피드백을 남겨주세요. 퀀트 팀에게 아주아주 큰 힘이 됩니다!
-
-## Alpha
-
-현재 얽힘 라이브러리는 뭉친 업데이트 내용을 재빨리 반영하기 위해 꽤 성급하게 `1.1.0-Alpha`를 공개한 상태입니다. 이 버전의 안정화 버전은 `1.1.0` 정식 릴리즈로 수정되서 반영될 예정입니다. 아무래도 1인 개발이다 보니 속도가 더뎌지는 문제가 있으나, 모든 수정까지 얼마 남지 않았습니다.
-
## 라이선스
본 프로젝트는 `PolyForm Noncommercial License 1.0.0`을 따릅니다. 이 프로젝트 내에서 `entlib-native`를 동시 관리하는 탓에 라이선스가 가끔 `MIT`로 잘못 반영될 때가 있지만, 여전히 `PolyForm` 라이선스를 따른다는 것을 참고해주세요. 이 라이선스에 관해 자세한 내용은 [LICENSE](LICENSE) 파일을 참고하세요.
diff --git a/README_EN.md b/README_EN.md
index 7ea589e..212c900 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -6,169 +6,89 @@
-EntanglementLib is a high-performance security and utility library designed based on Post-Quantum Cryptography (PQC) technology. This library aims to provide the highest level of security and system stability in response to the evolving digital threat landscape.
+EntanglementLib is a military-grade security library designed to process all security operations safely and quickly. It provides classical and Post-Quantum Cryptography (PQC) technologies, and offers a future-oriented TLS protocol using them.
+
+It aims to provide the highest level of security and system stability in response to the evolving digital threat environment.
> [Korean README](README.md)
## Core Philosophy
-All designs of EntanglementLib prioritize 'security' for 'military-grade security' and 'establishing secure infrastructure in financial and large-scale enterprise environments' as the foremost principle. EntanglementLib is implemented to fundamentally prevent potential security vulnerabilities and ensure data integrity. The second core value is 'stability'. To ensure predictable and consistent performance, Rust native operations are applied to maximize memory efficiency very safely, and a systematic error (or exception) handling mechanism is equipped.
-
-## Strengths
-
-EntanglementLib possesses the following strengths:
-
-1. **Anti-Data Remanence and Memory Erasure**
- - We accurately identified that Java's memory management model, the Garbage Collector (GC), can be vulnerable to security threats, and equipped technology to technically overcome this.
- - For this technology, we designed it to safely erase data using the [`entlib-native` native library](https://github.com/Quant-Off/entlib-native).
- - We provide a [Data Container feature](https://github.com/Quant-Off/entanglementlib/blob/master/src/main/java/space/qu4nt/entanglementlib/entlibnative/SensitiveDataContainer.java) to safely manage all sensitive information.
-2. **Compliance with Latest PQC Standards**
- - It supports the latest algorithms standardized by NIST such as ML-KEM, ML-DSA, and SLH-DSA according to FIPS 203, 204, and 205, as well as classical algorithms like AES, ARIA, and ChaCha20, processing them natively to enable secure operations.
-3. **Architecture and Design Patterns**
- - Factory patterns and interfaces are clearly separated. [Cryptographic algorithms can be called and used strategically](https://github.com/Quant-Off/entanglementlib/tree/master/src/main/java/space/qu4nt/entanglementlib/security/crypto).
-4. **Exception Handling**
- - We ensured that standard exceptions are not thrown as is. They are wrapped in EntanglementLib's custom exception classes to provide clear context.
- - If a problem is discovered from a security perspective, the system is designed to suggest a solution and defend against concerning attacks (hacking).
-
-## Key Features
-
-EntanglementLib includes powerful encryption features and utilities for improving development productivity.
-
-| Module | Technical Specification |
-| :--- | :--- |
-| `security.crypto` | Provides Post-Quantum Cryptography (PQC) and modern encryption algorithms.
-
- space.qu4nt.entanglementlib
- entanglementlib
- 1.0.0
-
-
-```
+We are performing bridge benchmarking for various operations such as nanosecond delays occurring when calling Rust native functions using FFM API in EntanglementLib. This work is directly related to performance and security, and plays an important role in creating optimal code.
-#### Gradle Project
+Many benchmarking tasks are scheduled in this alpha version. We plan to proceed with this work through JMH (Java Microbenchmark Harness), and we will organize it in a new document as soon as it is completed.
-```kotlin
-repositories {
- mavenCentral()
-}
+## Contribution
-dependencies {
- implementaion("space.qu4nt.entanglementlib:entanglementlib:1.0.0")
- // or Groovy
- // implementaion 'space.qu4nt.entanglementlib:entanglementlib:1.0.0'
-}
-```
+This project is currently `Alpha` version, and is still lacking a lot. We are already ready to actively receive your feedback. EntanglementLib is developed not only to provide PQC algorithms, but also to be used as a competent tool that systematically monitors infrastructure security in the user environment and finds solutions for users. From the latest release, we will focus strongly on this belief.
## TODO
-This project is still lacking in many areas. EntanglementLib aims to clarify the following TODOs so that it can be used in financial and security infrastructure production in the future.
+EntanglementLib wants to clarify the following TODOs so that it can be used in financial and security infrastructure production in the future.
-- [ ] **Provider Fluidity and Factory Optimization**
- - We need to modify it so that Java's default provider can be used according to the user's choice. And we need to optimize the factories provided in most classes, including the `InternalFactory` class.
-- [ ] **Overall Design Pattern Optimization**
- - The current code has many dirty parts, enough to be called spaghetti code. We need to modify it to write pleasant code like my room.
-- [ ] **JPMS Application**
- - Once secure encapsulation and consistent call (or usage) patterns are completed, we intend to manage encapsulated packages as modules through JPMS.
-- [ ] **Remove `BouncyCastle` Dependency**
- - From the `1.1.0` release onwards, we intend to minimize `BC` dependency and eventually remove it. Currently, classical algorithms like AES, ARIA, and ChaCha20 still depend on `BC`. To solidify EntanglementLib's security philosophy, we have decided to perform all cryptographic operations in `entlib-native`.
-- [ ] **`i18n` Update**
- - We missed a lot of multi-language support while developing the latest release. We need to modify it to support logging for each language according to configuration settings.
+- [ ] Add TLS communication logic
+- [ ] Prepare and perform complex verification tasks
+- [ ] Custom Exception Optimization
+- [ ] Apply JPMS
+ - Once secure encapsulation and consistent call (or usage) patterns are completed, we intend to manage encapsulated packages as modules through JPMS.
+- [ ] Minimize external dependencies
+ - Now, from the `1.1.0` release, we have minimized `BouncyCastle` dependencies and finally succeeded in removing them. Dependencies that provide some useful tools needed for current code writing still remain, but these will also be minimized eventually.
+- [ ] Update `i18n`
+ - While performing the latest release development, we missed a lot of multilingual support. We need to modify it to support logging for each language according to configuration settings.
### Resolved
-- [X] **Conflict between Java Module System (JPMS) and Reflection**
- - `KeyDestroyHelper` uses `Field.setAccessible(true)` to modify `private` fields in `BouncyCastle` internals or the Java standard library. Due to the strong encapsulation policy since Java 17, there is a very high probability that an `InaccessibleObjectException` will occur without the `--add-opens` JVM option at runtime.
+- [X] Conflict between Java Module System (JPMS) and Reflection
+ - In `KeyDestroyHelper`, `Field.setAccessible(true)` is used to modify `private` fields inside `BouncyCastle` or Java standard libraries. Due to the strong encapsulation policy since Java 17, there is a very high probability that `InaccessibleObjectException` will occur without the `--add-opens` JVM option at runtime.
- You can bypass JPMS security warnings by adding the JVM option `--add-opens java.base/java.security=ALL-UNNAMED`.
- - **Resolution**: We didn't worry too much about solving this problem. Because we decided to use the `BC Lightweight API` from the `1.1.0` release. The first goal was to avoid some constraints of the existing JCA/JCE with low-level access. In other words, access via reflection is still indispensable. It means we might not be able to respond flexibly when generating keys or calling internal encryption engines. To solve these complex problems, we introduced the `entlib-native` native library and intend to focus on minimizing EntanglementLib's `BC` dependency.
-- [X] **Performance vs. Security Trade-off**
- - We are performing defensive copies (deep copy) for all I/O. In server environments that process large data in gigabytes or require high throughput (Tick Per Second, TPS), frequent memory allocation and Garbage Collector load can cause performance degradation. Even looking at existing algorithm classes, binding data to instances is visible.
- - **Resolution**: We added the `entlib-native` native library and designed it so that all memory-related operations are handled on the `Rust` side. Now, on the `Java` side, we just need to erase sensitive data like byte arrays that are simply received. `Rust` will reliably handle memory operations in the background.
-- [X] **Random Number and Nonce Management**
- - `ChaCha20Poly1305` uses `InternalFactory.getSafeRandom()` to generate the nonce value `Nonce`. If the `Nonce` is reused with the same key, the security of `ChaCha20Poly1305` completely collapses.
- - **Resolution**: This problem was also solved with the `entlib-native` native library. Now, a `ChaCha20`-based `CSPRNG` is created on the `Rust` side and used only on the `Rust` side. In other words, all cryptographic operations are now performed only by `Rust`!
-- [X] **Writing Technical Specifications for Security Features**
- - **Resolution**: Important security-related features of EntanglementLib have been written in a [separate document](TECHNICAL.md).
-
-## Contribution
-
-In the early versions, EntanglementLib had really vague goals like 'BouncyCastle wrapper', 'half-hearted data erasure', etc. We spent quite a lot of time thinking deeply about this part and re-established EntanglementLib's unique goals.
-
-Now, EntanglementLib is developed not just to provide PQC algorithms, but to be used as a competent tool that systematically monitors infrastructure security in the user's environment and finds solutions for the user. From the latest release, we will focus strongly on this belief.
-
-Therefore... we need the power of many developers to complete the ultimate goal of EntanglementLib. Please leave feedback on the code at any time. It is a very, very big help to the Quant team!
-
-## Alpha
-
-Currently, EntanglementLib has released `1.1.0-Alpha` quite hastily to quickly reflect the accumulated updates. The stable version of this version is scheduled to be modified and reflected as the `1.1.0` official release. Since it is a one-person development, there is a problem that the speed is slow, but not much is left until all modifications.
+ - **Resolution**: We didn't worry too much to solve this problem. Because we decided to use `BC Lightweight API` from the `1.1.0` release. The first goal was to avoid some restrictions of existing JCA/JCE with low-level access. In other words, access through reflection is still inevitable. It means that we may not be able to respond flexibly when generating keys or calling internal encryption engines. To solve these complex problems, we introduced the `entlib-native` native library, and we intend to focus on minimizing `BC` dependencies of EntanglementLib.
+- [X] Performance vs Security Trade-off
+ - Defensive copy (deep copy) is performed for all inputs and outputs. In server environments that process large data in gigabytes or require high throughput (Tick Per Second, TPS), frequent memory allocation and garbage collector load can cause performance degradation. Just looking at existing algorithm classes, you can see data binding to instances.
+ - **Resolution**: By adding the `entlib-native` native library, we designed all memory-related operations to be processed on the `Rust` side. Now, on the `Java` side, we simply need to erase sensitive data such as byte arrays received purely. `Rust` will reliably take care of memory operations in the back.
+- [X] Random Number and Nonce Management
+ - In `ChaCha20Poly1305`, `InternalFactory.getSafeRandom()` is used to generate nonce value `Nonce`. If `Nonce` is reused with the same key, the security of `ChaCha20Poly1305` collapses completely.
+ - **Resolution**: This problem was also solved with the `entlib-native` native library. Now, `ChaCha20`-based `CSPRNG` is created on the `Rust` side, and used only on the `Rust` side. In other words, all cryptographic operations are now performed only by `Rust`!
+- [X] Writing Technical Specifications for Security Functions
+ - **Resolution**: Important security-related functions of EntanglementLib have been written in a [separate document](TECHNICAL.md).
## License
-This project follows the `PolyForm Noncommercial License 1.0.0`. Please note that due to the simultaneous management of `entlib-native` within this project, the license is sometimes incorrectly reflected as `MIT`, but it still follows the `PolyForm` license. For more details on this license, please refer to the [LICENSE](LICENSE) file.
+This project follows `PolyForm Noncommercial License 1.0.0`. Please note that although the license is sometimes incorrectly reflected as `MIT` due to simultaneous management of `entlib-native` within this project, it still follows the `PolyForm` license. For more details on this license, please refer to the [LICENSE](LICENSE) file.
---
-# Changelog
+# Changes
Changes can be found in the [CHANGE.md](CHANGE.md) document. This document will be added when the `1.1.0` release is published.
\ No newline at end of file
diff --git a/annotation-processor/build.gradle.kts b/annotation-processor/build.gradle.kts
new file mode 100644
index 0000000..48339bb
--- /dev/null
+++ b/annotation-processor/build.gradle.kts
@@ -0,0 +1,3 @@
+dependencies {
+ implementation(project(":annotations"))
+}
\ No newline at end of file
diff --git a/annotations/build.gradle.kts b/annotations/build.gradle.kts
new file mode 100644
index 0000000..0ce6a16
--- /dev/null
+++ b/annotations/build.gradle.kts
@@ -0,0 +1,3 @@
+dependencies {
+
+}
\ No newline at end of file
diff --git a/annotations/src/main/java/space/qu4nt/entanglementlib/annotations/CallerResponsibility.java b/annotations/src/main/java/space/qu4nt/entanglementlib/annotations/CallerResponsibility.java
new file mode 100644
index 0000000..3462f0a
--- /dev/null
+++ b/annotations/src/main/java/space/qu4nt/entanglementlib/annotations/CallerResponsibility.java
@@ -0,0 +1,29 @@
+package space.qu4nt.entanglementlib.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/// 보안적 책임은 호출자에게 있음을 알리는 어노테이션입니다. 호출자가 해당 어노테이션이
+/// 사용된 멤버 사용 시, 작업 종료 후 반드시 보안 작업이 필요함을 의미합니다.
+///
+/// 예를 들어, 이 어노테이션이 (복사본이 아닌) 원본 데이터를 반환하는 메소드에 사용되었고
+/// 해당 메소드를 사용하고자 하는 경우, 반환받은 데이터를 소거해야 함을 의미합니다.
+///
+/// 또는 이 어노테이션이 사용된 멤버는 네이티브 측의 "호출자 할당" 패턴을 사용한 경우로,
+/// 작업이 종료됨과 동시에 네이티브에 할당 해제 함수를 호출해야 함을 의미합니다.
+///
+/// @author Q. T. Felix
+/// @since 1.1.0
+@Documented
+@Target(ElementType.TYPE_USE)
+public @interface CallerResponsibility {
+
+ /**
+ * 책임 전가의 사유 또는 설명를 정의합니다.
+ *
+ * @return 책임 전가 사유 또는 설명
+ */
+ String value() default "";
+
+}
\ No newline at end of file
diff --git a/src/main/java/space/qu4nt/entanglementlib/ExternalPattern.java b/annotations/src/main/java/space/qu4nt/entanglementlib/annotations/ExternalPattern.java
similarity index 62%
rename from src/main/java/space/qu4nt/entanglementlib/ExternalPattern.java
rename to annotations/src/main/java/space/qu4nt/entanglementlib/annotations/ExternalPattern.java
index 804884f..423d64e 100644
--- a/src/main/java/space/qu4nt/entanglementlib/ExternalPattern.java
+++ b/annotations/src/main/java/space/qu4nt/entanglementlib/annotations/ExternalPattern.java
@@ -1,16 +1,11 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib;
+package space.qu4nt.entanglementlib.annotations;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;
/**
* 반드시 외부에서만 사용됨을 알리는 마커 어노테이션입니다.
- * {@link InternalFactory} 객체 부트스트랩 시, 내부(internal)에서 사용되는 멤버와
+ * 라이브러리 부트스트랩, 또는 기타 상황 속 내부(internal)에서 사용되는 멤버와
* 외부(external)에서 사용되는 멤버는 다르다는 것을 명확히 하기 위해 사용됩니다.
*
* 이 어노테이션은 타입 레벨에 사용하지 마세요. 혼동이 생길 수 있습니다.
@@ -19,6 +14,4 @@
* @since 1.1.0
*/
@Target(ElementType.TYPE_USE)
-public @interface ExternalPattern {
-
-}
+public @interface ExternalPattern { }
diff --git a/src/main/java/space/qu4nt/entanglementlib/Unsafe.java b/annotations/src/main/java/space/qu4nt/entanglementlib/annotations/Unsafe.java
similarity index 79%
rename from src/main/java/space/qu4nt/entanglementlib/Unsafe.java
rename to annotations/src/main/java/space/qu4nt/entanglementlib/annotations/Unsafe.java
index 50548da..1b417c1 100644
--- a/src/main/java/space/qu4nt/entanglementlib/Unsafe.java
+++ b/annotations/src/main/java/space/qu4nt/entanglementlib/annotations/Unsafe.java
@@ -1,12 +1,4 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib;
-
-import com.quant.quantregular.annotations.QuantTypeOwner;
-import com.quant.quantregular.annotations.Quanters;
+package space.qu4nt.entanglementlib.annotations;
import java.lang.annotation.Documented;
@@ -16,7 +8,7 @@
///
/// 이 어노테이션이 사용된 요소(멤버)가 본질적으로 안전하지 않으며 보안 위험을 초래할 수 있음을 나타내기 위한
/// 어노테이션입니다.
-///
+///
/// 구체적으로 이 어노테이션은 사용된 메소드, 필드 또는 타입 등의 멤버가 다음 이유 중 하나로 인해 안전하지
/// 않음을 나타냅니다.
///
@@ -26,22 +18,25 @@
/// - 보안 취약점 발견
///
/// 이 API를 사용하려면 기본 구현 및 잠재적인 부작용에 대한 깊은 이해가 필요합니다.
-///
+///
/// # Important
///
/// 이 요소를 부적절하게 사용하면 `메모리 손상`, `데이터 유출` 또는 **임의 코드 실행을 포함하되 이에 국한되지 않는
/// 심각한 보안 취약점이 발생**할 수 있습니다. 또한 정의되지 않은 동작이나 애플리케이션 불안정을 초래할 수도 있습니다.
-///
+///
/// 사용자는 절대적으로 필요한 경우에만 이 요소를 사용해야 하며, 위험을 완화하기 위해 적절한 보안 조치와
/// 검증 로직이 마련되어 있는지 확인해야 합니다.
///
/// # Note
///
-/// 이 어노테이션이 사용된 멤버는 `# Security` 헤더에 `Unsafe` 근거가 기록되어야 합니다.
+/// 이 어노테이션이 사용된 멤버는 `# Unsafe` 헤더에 근거가 기록되어야 합니다.
///
/// @author Q. T. Felix
/// @since 1.1.0
@Documented
-@QuantTypeOwner(Quanters.Q_T_FELIX)
public @interface Unsafe {
+
+ /// 명확한 `unsafe` 사유입니다.
+ /// @return 명확한 `unsafe` 사유
+ String value() default "";
}
diff --git a/build.gradle.kts b/build.gradle.kts
index 6ac1a06..ac994f7 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -4,9 +4,8 @@
*/
plugins {
- id("java")
+ java
id("com.vanniktech.maven.publish") version "0.28.0"
- id("me.champeau.jmh") version "0.7.3"
}
val commonGroupId = project.findProperty("commonGroupId") as? String ?: "space.qu4nt"
@@ -14,210 +13,144 @@ val quantPublicDir = project.findProperty("quantPublicDir") as? String
?: layout.buildDirectory.dir("dummy-resources").get().asFile.absolutePath
val lombokVersion = "org.projectlombok:lombok:1.18.42"
-val bouncyCastleVer = "1.83"
val entLibVersion = "1.1.2-Alpha3"
-group = commonGroupId
-version = entLibVersion
-
-sourceSets {
- main {
- java {
- srcDirs("src/main/java")
- }
- resources {
- srcDirs("src/main/resources")
-
- if (quantPublicDir.isNotEmpty()) {
- val extraResourceDir = File("${quantPublicDir}/entanglementlib")
- if (extraResourceDir.exists()) {
- srcDir(extraResourceDir)
- } else {
- logger.warn("Warning: External resource directory not found: $extraResourceDir. Skipping...")
- }
- }
- }
- }
+allprojects {
+ group = "{$commonGroupId}.entanglementlib"
+ version = entLibVersion
+}
- test {
- java {
- srcDirs("src/test/java")
- }
- resources {
- srcDirs("src/test/resources")
+subprojects {
+ apply(plugin = "java")
+ apply(plugin = "com.vanniktech.maven.publish")
- if (quantPublicDir.isNotEmpty()) {
- val extraTestResourceDir = File("${quantPublicDir}/entanglementlib-test")
- if (extraTestResourceDir.exists()) {
- srcDir(extraTestResourceDir)
- }
- }
+ java {
+ toolchain {
+ languageVersion.set(JavaLanguageVersion.of(25))
}
+ sourceCompatibility = JavaVersion.VERSION_25
+ targetCompatibility = JavaVersion.VERSION_25
}
- named("jmh") {
- java {
- srcDirs("src/benchmark/java")
- }
- resources {
- srcDirs("src/benchmark/resources")
- }
+ repositories {
+ mavenCentral()
}
-}
-java {
- toolchain {
- languageVersion.set(JavaLanguageVersion.of(25))
+ dependencies {
+ // JetBrains Annotations
+ // https://mvnrepository.com/artifact/org.jetbrains/annotations
+ implementation("org.jetbrains:annotations:26.0.2-1")
+
+ // Logging
+ // https://mvnrepository.com/artifact/org.slf4j/slf4j-api
+ implementation("org.slf4j:slf4j-api:2.0.17")
+ // bridger
+ // https://mvnrepository.com/artifact/org.slf4j/jul-to-slf4j
+ implementation("org.slf4j:jul-to-slf4j:2.0.17")
+ // Logging Provider (Logback)
+ // https://mvnrepository.com/artifact/ch.qos.logback/logback-classic
+ implementation("ch.qos.logback:logback-classic:1.5.26")
+
+ // Lombok
+ // https://mvnrepository.com/artifact/org.projectlombok/lombok
+ implementation(lombokVersion)
+ annotationProcessor(lombokVersion)
+
+ // Tests JUnit 5
+ testImplementation(platform("org.junit:junit-bom:5.10.0"))
+ testImplementation("org.junit.jupiter:junit-jupiter")
+ testImplementation("org.assertj:assertj-core:3.27.7")
+ testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+ testAnnotationProcessor(lombokVersion)
}
- sourceCompatibility = JavaVersion.VERSION_25
- targetCompatibility = JavaVersion.VERSION_25
-}
-repositories {
- mavenCentral()
-}
-
-dependencies {
- // Quant-regular
- implementation("space.qu4nt.quant-regular:annotations:1.0.0")
-
- // JetBrains Annotations
- // https://mvnrepository.com/artifact/org.jetbrains/annotations
- implementation("org.jetbrains:annotations:26.0.2-1")
-
- // Logging
- // https://mvnrepository.com/artifact/org.slf4j/slf4j-api
- implementation("org.slf4j:slf4j-api:2.0.17")
- // bridger
- // https://mvnrepository.com/artifact/org.slf4j/jul-to-slf4j
- implementation("org.slf4j:jul-to-slf4j:2.0.17")
- // Logging Provider (Logback)
- // https://mvnrepository.com/artifact/ch.qos.logback/logback-classic
- implementation("ch.qos.logback:logback-classic:1.5.26")
-
- // Lombok
- // https://mvnrepository.com/artifact/org.projectlombok/lombok
- implementation(lombokVersion)
- annotationProcessor(lombokVersion)
-
- // https://mvnrepository.com/artifact/org.yaml/snakeyaml
- implementation("org.yaml:snakeyaml:2.5")
-
- // Jackson
- // https://mvnrepository.com/artifact/tools.jackson.core/jackson-databind
- implementation("tools.jackson.core:jackson-databind:3.0.2")
- // https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-annotations
- implementation("com.fasterxml.jackson.core:jackson-annotations:3.0-rc5")
-
- // BouncyCastle
- implementation("org.bouncycastle:bcprov-jdk18on:${bouncyCastleVer}")
- implementation("org.bouncycastle:bcutil-jdk18on:${bouncyCastleVer}")
- implementation("org.bouncycastle:bcpkix-jdk18on:${bouncyCastleVer}")
- implementation("org.bouncycastle:bctls-jdk18on:${bouncyCastleVer}")
-
- // Tests JUnit 5
- testImplementation(platform("org.junit:junit-bom:5.10.0"))
- testImplementation("org.junit.jupiter:junit-jupiter")
- testImplementation("org.assertj:assertj-core:3.27.7")
- testRuntimeOnly("org.junit.platform:junit-platform-launcher")
- testAnnotationProcessor(lombokVersion)
-
- // JMH
- jmh("org.openjdk.jmh:jmh-core:1.37")
- jmh("org.openjdk.jmh:jmh-generator-annprocess:1.37")
- // Source: https://mvnrepository.com/artifact/org.openjdk.jmh/jmh-core
- testImplementation("org.openjdk.jmh:jmh-core:1.37")
- // Source: https://mvnrepository.com/artifact/org.openjdk.jmh/jmh-generator-annprocess
- testImplementation("org.openjdk.jmh:jmh-generator-annprocess:1.37")
- jmhAnnotationProcessor(lombokVersion)
-}
-
-tasks.test {
- useJUnitPlatform()
-}
+ sourceSets {
+ main {
+ java {
+ srcDirs("src/main/java")
+ }
+ resources {
+ srcDirs("src/main/resources")
+
+ if (quantPublicDir.isNotEmpty()) {
+ val extraResourceDir = File("${quantPublicDir}/entanglementlib")
+ if (extraResourceDir.exists()) {
+ srcDir(extraResourceDir)
+ } else {
+ logger.warn("Warning: External resource directory not found: $extraResourceDir. Skipping...")
+ }
+ }
+ }
+ }
-tasks.jar {
- from("entlib-native/dist") {
- into("native")
- include("linux/libentlib_native_aarch64.so", "linux/libentlib_native_x86_64.so",
- "macos/libentlib_native_aarch64.dylib", "macos/libentlib_native_universal.dylib", "macos/libentlib_native_x86_64.dylib",
- "windows/entlib_native_x86_64.dll")
+ test {
+ java {
+ srcDirs("src/test/java")
+ }
+ resources {
+ srcDirs("src/test/resources")
+
+ if (quantPublicDir.isNotEmpty()) {
+ val extraTestResourceDir = File("${quantPublicDir}/entanglementlib-test")
+ if (extraTestResourceDir.exists()) {
+ srcDir(extraTestResourceDir)
+ }
+ }
+ }
+ }
}
-}
-tasks.withType {
- duplicatesStrategy = DuplicatesStrategy.INCLUDE
-}
+ mavenPublishing {
+ signAllPublications()
-mavenPublishing {
- signAllPublications()
+ coordinates("${commonGroupId}.${project.name}", project.name, entLibVersion)
- coordinates("${commonGroupId}.${project.name}", project.name, entLibVersion)
+ pom {
+ name = project.name
+ description = "Quant EntanglementLib"
+ inceptionYear = "2025"
+ url = "https://github.com/Quant-Off/entanglementlib"
- pom {
- name = project.name
- description = "Quant EntanglementLib"
- inceptionYear = "2025"
- url = "https://github.com/Quant-Off/entanglementlib"
+ licenses {
+ license {
+ name = "PolyForm Noncommercial License 1.0.0"
+ url = "https://polyformproject.org/licenses/noncommercial/1.0.0/"
+ }
+ }
- licenses {
- license {
- name = "PolyForm Noncommercial License 1.0.0"
- url = "https://polyformproject.org/licenses/noncommercial/1.0.0/"
+ developers {
+ developer {
+ id = "qtfelix"
+ name = "Q. T. Felix"
+ url = "https://github.com/Quant-TheodoreFelix"
+ }
}
- }
- developers {
- developer {
- id = "qtfelix"
- name = "Q. T. Felix"
- url = "https://github.com/Quant-TheodoreFelix"
+ scm {
+ url = "https://github.com/Quant-Off/entanglementlib"
+ connection = "scm:git:git://github.com/Quant-Off/entanglementlib.git"
+ developerConnection = "scm:git:ssh://git@github.com/Quant-Off/entanglementlib.git"
}
}
- scm {
- url = "https://github.com/Quant-Off/entanglementlib"
- connection = "scm:git:git://github.com/Quant-Off/entanglementlib.git"
- developerConnection = "scm:git:ssh://git@github.com/Quant-Off/entanglementlib.git"
- }
+ configure(
+ com.vanniktech.maven.publish.JavaLibrary(
+ sourcesJar = true,
+ javadocJar = com.vanniktech.maven.publish.JavadocJar.Javadoc()
+ )
+ )
}
- configure(
- com.vanniktech.maven.publish.JavaLibrary(
- sourcesJar = true,
- javadocJar = com.vanniktech.maven.publish.JavadocJar.Javadoc()
- )
- )
-}
+ tasks.test {
+ useJUnitPlatform()
+ }
-//
-// JMH - start
-//
-jmh {
- jmhVersion.set("1.37")
-
- // 테스트 벤치마킹 클래스 등록
- includeTests.set(true)
- includes.set(listOf(".*_JMHBenchmark"))
-
- // 벤치마크 실행 시 필요한 jvm 인자 중앙 제어
- jvmArgs.set(listOf(
- "--enable-native-access=ALL-UNNAMED",
- "--enable-preview",
- "-Djava.library.path=${projectDir}/native-benchmark/target/debug",
- "-Xms2g", "-Xmx2g" // gc 간섭 최소화
- ))
- fork.set(1)
-
- // 결과 출력 포맷
- resultFormat.set("JSON")
-
- // 벤치마크 수행 옵션 (프로세스 및 반복 횟수)
- fork.set(1)
- warmupIterations.set(3)
- iterations.set(5)
-}
-//
-// JMH - end
-//
\ No newline at end of file
+ tasks.withType {
+ duplicatesStrategy = DuplicatesStrategy.INCLUDE
+ }
+
+ tasks.named("sourcesJar") {
+ duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+ }
+}
\ No newline at end of file
diff --git a/core/build.gradle.kts b/core/build.gradle.kts
new file mode 100644
index 0000000..195d444
--- /dev/null
+++ b/core/build.gradle.kts
@@ -0,0 +1,12 @@
+dependencies {
+ implementation(project(":annotations"))
+
+ // Jackson
+ // https://mvnrepository.com/artifact/tools.jackson.core/jackson-databind
+ implementation("tools.jackson.core:jackson-databind:3.0.2")
+ // https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-annotations
+ implementation("com.fasterxml.jackson.core:jackson-annotations:3.0-rc5")
+
+ // https://mvnrepository.com/artifact/org.yaml/snakeyaml
+ implementation("org.yaml:snakeyaml:2.5")
+}
\ No newline at end of file
diff --git a/core/src/main/java/space/qu4nt/entanglementlib/core/EntanglementLibCoreContext.java b/core/src/main/java/space/qu4nt/entanglementlib/core/EntanglementLibCoreContext.java
new file mode 100644
index 0000000..ce1c30c
--- /dev/null
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/EntanglementLibCoreContext.java
@@ -0,0 +1,27 @@
+package space.qu4nt.entanglementlib.core;
+
+import lombok.Getter;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import space.qu4nt.entanglementlib.core.exception.core.ELIBCoreIllegalArgumentException;
+import space.qu4nt.entanglementlib.core.i18n.EntanglementLibCoreI18n;
+
+import java.util.Locale;
+
+public final class EntanglementLibCoreContext {
+
+ @Getter
+ private static volatile boolean initialized = false;
+
+ private EntanglementLibCoreContext() {
+ throw new UnsupportedOperationException("cannot access");
+ }
+
+ public static synchronized void initialize(final @NotNull Locale locale, @Nullable String userResourceBasename)
+ throws ELIBCoreIllegalArgumentException {
+ if (!initialized) {
+ EntanglementLibCoreI18n.initialize(locale, userResourceBasename);
+ initialized = true;
+ }
+ }
+}
diff --git a/core/src/main/java/space/qu4nt/entanglementlib/core/exception/ELIBException.java b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/ELIBException.java
new file mode 100644
index 0000000..04fb805
--- /dev/null
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/ELIBException.java
@@ -0,0 +1,55 @@
+/*
+ * Copyright © 2025-2026 Quant.
+ * Under License "PolyForm Noncommercial License 1.0.0".
+ */
+
+package space.qu4nt.entanglementlib.core.exception;
+
+import java.io.Serial;
+
+/// 얽힘 라이브러리 전반에서 사용되는 기본 예외 클래스입니다.
+///
+/// 이 클래스는 [Exception]을 상속받으며, 기본적으로 `Checked Exception`입니다.
+/// 확장하여 다양한 상황에 대해 예외 처리가 가능합니다.
+///
+/// @author Q. T. Felix
+/// @since 1.1.0
+public class ELIBException extends Exception {
+
+ @Serial
+ private static final long serialVersionUID = 2378593800480779310L;
+
+ /**
+ * 새로운 {@link ELIBException} 인스턴스를 생성하는 기본 생성자 메소드입니다.
+ */
+ public ELIBException() {
+ super();
+ }
+
+ /**
+ * 다국어 처리가 필요하지 않은 경우 이 인스턴스를 사용할 수 있습니다.
+ *
+ * @param message 메시지
+ */
+ public ELIBException(String message) {
+ super(message);
+ }
+
+ /**
+ * 발생한 예외만 넘기기 위해 이 인스턴스를 사용할 수 있습니다.
+ *
+ * @param cause 발생 예외
+ */
+ public ELIBException(Throwable cause) {
+ super(cause);
+ }
+
+ /// 다국어 처리가 필요하지 않으며, 발생한 예외를 넘기기 위해 이
+ /// 인스턴스를 사용할 수 있습니다.
+ ///
+ /// @param message 메시지
+ /// @param cause 발생 예외
+ public ELIBException(String message, Throwable cause) {
+ super(message, cause);
+ }
+}
diff --git a/core/src/main/java/space/qu4nt/entanglementlib/core/exception/ELIBUncheckedException.java b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/ELIBUncheckedException.java
new file mode 100644
index 0000000..374eb99
--- /dev/null
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/ELIBUncheckedException.java
@@ -0,0 +1,44 @@
+/*
+ * Copyright © 2025-2026 Quant.
+ * Under License "PolyForm Noncommercial License 1.0.0".
+ */
+
+package space.qu4nt.entanglementlib.core.exception;
+
+import java.io.Serial;
+
+/// 얽힘 라이브러리 전반에서 사용되는 기본 예외 클래스입니다.
+///
+/// 이 클래스는 [Exception]을 상속받으며, `Unchecked Exception`입니다.
+///
+/// @author Q. T. Felix
+/// @since 1.1.0
+public class ELIBUncheckedException extends RuntimeException {
+
+ @Serial
+ private static final long serialVersionUID = 2378593800480779310L;
+
+ /**
+ * 새로운 {@link ELIBUncheckedException} 인스턴스를 생성하는 기본 생성자 메소드입니다.
+ */
+ public ELIBUncheckedException() {
+ }
+
+ /**
+ * 다국어 처리가 필요하지 않은 경우 이 인스턴스를 사용할 수 있습니다.
+ *
+ * @param message 메시지
+ */
+ public ELIBUncheckedException(String message) {
+ super(message);
+ }
+
+ /**
+ * 발생한 예외만 넘기기 위해 이 인스턴스를 사용할 수 있습니다.
+ *
+ * @param cause 발생 예외
+ */
+ public ELIBUncheckedException(Throwable cause) {
+ super(cause);
+ }
+}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/ExceptionLogger.java b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/ExceptionLogger.java
similarity index 96%
rename from src/main/java/space/qu4nt/entanglementlib/exception/ExceptionLogger.java
rename to core/src/main/java/space/qu4nt/entanglementlib/core/exception/ExceptionLogger.java
index 033b9e0..b0e4f89 100644
--- a/src/main/java/space/qu4nt/entanglementlib/exception/ExceptionLogger.java
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/ExceptionLogger.java
@@ -3,7 +3,7 @@
* Under License "PolyForm Noncommercial License 1.0.0".
*/
-package space.qu4nt.entanglementlib.exception;
+package space.qu4nt.entanglementlib.core.exception;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
diff --git a/core/src/main/java/space/qu4nt/entanglementlib/core/exception/core/ELIBCoreException.java b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/core/ELIBCoreException.java
new file mode 100644
index 0000000..3e64b0d
--- /dev/null
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/core/ELIBCoreException.java
@@ -0,0 +1,28 @@
+package space.qu4nt.entanglementlib.core.exception.core;
+
+import java.io.Serial;
+
+public class ELIBCoreException extends Exception {
+
+ @Serial
+ private static final long serialVersionUID = -8478889423877054012L;
+
+ public ELIBCoreException() {
+ }
+
+ public ELIBCoreException(String message) {
+ super(message);
+ }
+
+ public ELIBCoreException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ public ELIBCoreException(Throwable cause) {
+ super(cause);
+ }
+
+ public ELIBCoreException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
+ super(message, cause, enableSuppression, writableStackTrace);
+ }
+}
diff --git a/core/src/main/java/space/qu4nt/entanglementlib/core/exception/core/ELIBCoreIllegalArgumentException.java b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/core/ELIBCoreIllegalArgumentException.java
new file mode 100644
index 0000000..5fcddd0
--- /dev/null
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/core/ELIBCoreIllegalArgumentException.java
@@ -0,0 +1,28 @@
+package space.qu4nt.entanglementlib.core.exception.core;
+
+import java.io.Serial;
+
+public class ELIBCoreIllegalArgumentException extends ELIBCoreException {
+
+ @Serial
+ private static final long serialVersionUID = 8726329909869726228L;
+
+ public ELIBCoreIllegalArgumentException() {
+ }
+
+ public ELIBCoreIllegalArgumentException(String message) {
+ super(message);
+ }
+
+ public ELIBCoreIllegalArgumentException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ public ELIBCoreIllegalArgumentException(Throwable cause) {
+ super(cause);
+ }
+
+ public ELIBCoreIllegalArgumentException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
+ super(message, cause, enableSuppression, writableStackTrace);
+ }
+}
diff --git a/core/src/main/java/space/qu4nt/entanglementlib/core/exception/core/ELIBCoreUtilityException.java b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/core/ELIBCoreUtilityException.java
new file mode 100644
index 0000000..f1ff035
--- /dev/null
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/core/ELIBCoreUtilityException.java
@@ -0,0 +1,28 @@
+package space.qu4nt.entanglementlib.core.exception.core;
+
+import java.io.Serial;
+
+public class ELIBCoreUtilityException extends RuntimeException {
+
+ @Serial
+ private static final long serialVersionUID = -3902892852757530511L;
+
+ public ELIBCoreUtilityException() {
+ }
+
+ public ELIBCoreUtilityException(String message) {
+ super(message);
+ }
+
+ public ELIBCoreUtilityException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ public ELIBCoreUtilityException(Throwable cause) {
+ super(cause);
+ }
+
+ public ELIBCoreUtilityException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
+ super(message, cause, enableSuppression, writableStackTrace);
+ }
+}
diff --git a/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/checked/ELIBSecurityException.java b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/checked/ELIBSecurityException.java
new file mode 100644
index 0000000..044f33d
--- /dev/null
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/checked/ELIBSecurityException.java
@@ -0,0 +1,28 @@
+package space.qu4nt.entanglementlib.core.exception.security.checked;
+
+import java.io.Serial;
+
+public class ELIBSecurityException extends Exception {
+
+ @Serial
+ private static final long serialVersionUID = 7009027800432974319L;
+
+ public ELIBSecurityException() {
+ }
+
+ public ELIBSecurityException(String message) {
+ super(message);
+ }
+
+ public ELIBSecurityException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ public ELIBSecurityException(Throwable cause) {
+ super(cause);
+ }
+
+ public ELIBSecurityException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
+ super(message, cause, enableSuppression, writableStackTrace);
+ }
+}
diff --git a/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/checked/ELIBSecurityIOException.java b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/checked/ELIBSecurityIOException.java
new file mode 100644
index 0000000..9010216
--- /dev/null
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/checked/ELIBSecurityIOException.java
@@ -0,0 +1,28 @@
+package space.qu4nt.entanglementlib.core.exception.security.checked;
+
+import java.io.Serial;
+
+public class ELIBSecurityIOException extends ELIBSecurityException {
+
+ @Serial
+ private static final long serialVersionUID = -5611460691131894020L;
+
+ public ELIBSecurityIOException() {
+ }
+
+ public ELIBSecurityIOException(String message) {
+ super(message);
+ }
+
+ public ELIBSecurityIOException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ public ELIBSecurityIOException(Throwable cause) {
+ super(cause);
+ }
+
+ public ELIBSecurityIOException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
+ super(message, cause, enableSuppression, writableStackTrace);
+ }
+}
diff --git a/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/checked/ELIBSecurityIllegalStateException.java b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/checked/ELIBSecurityIllegalStateException.java
new file mode 100644
index 0000000..8d6fc35
--- /dev/null
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/checked/ELIBSecurityIllegalStateException.java
@@ -0,0 +1,28 @@
+package space.qu4nt.entanglementlib.core.exception.security.checked;
+
+import java.io.Serial;
+
+public class ELIBSecurityIllegalStateException extends ELIBSecurityException {
+
+ @Serial
+ private static final long serialVersionUID = -2918719188402645982L;
+
+ public ELIBSecurityIllegalStateException() {
+ }
+
+ public ELIBSecurityIllegalStateException(String message) {
+ super(message);
+ }
+
+ public ELIBSecurityIllegalStateException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ public ELIBSecurityIllegalStateException(Throwable cause) {
+ super(cause);
+ }
+
+ public ELIBSecurityIllegalStateException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
+ super(message, cause, enableSuppression, writableStackTrace);
+ }
+}
diff --git a/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/checked/ELIBSecurityProcessException.java b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/checked/ELIBSecurityProcessException.java
new file mode 100644
index 0000000..638704c
--- /dev/null
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/checked/ELIBSecurityProcessException.java
@@ -0,0 +1,28 @@
+package space.qu4nt.entanglementlib.core.exception.security.checked;
+
+import java.io.Serial;
+
+public class ELIBSecurityProcessException extends ELIBSecurityException {
+
+ @Serial
+ private static final long serialVersionUID = -4547118937218025817L;
+
+ public ELIBSecurityProcessException() {
+ }
+
+ public ELIBSecurityProcessException(String message) {
+ super(message);
+ }
+
+ public ELIBSecurityProcessException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ public ELIBSecurityProcessException(Throwable cause) {
+ super(cause);
+ }
+
+ public ELIBSecurityProcessException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
+ super(message, cause, enableSuppression, writableStackTrace);
+ }
+}
diff --git a/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/critical/ELIBSecurityCritical.java b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/critical/ELIBSecurityCritical.java
new file mode 100644
index 0000000..4140a89
--- /dev/null
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/critical/ELIBSecurityCritical.java
@@ -0,0 +1,28 @@
+package space.qu4nt.entanglementlib.core.exception.security.critical;
+
+import java.io.Serial;
+
+public class ELIBSecurityCritical extends Error {
+
+ @Serial
+ private static final long serialVersionUID = -6905370663633314089L;
+
+ public ELIBSecurityCritical() {
+ }
+
+ public ELIBSecurityCritical(String message) {
+ super(message);
+ }
+
+ public ELIBSecurityCritical(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ public ELIBSecurityCritical(Throwable cause) {
+ super(cause);
+ }
+
+ public ELIBSecurityCritical(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
+ super(message, cause, enableSuppression, writableStackTrace);
+ }
+}
diff --git a/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/critical/ELIBSecurityNativeCritical.java b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/critical/ELIBSecurityNativeCritical.java
new file mode 100644
index 0000000..9f62306
--- /dev/null
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/critical/ELIBSecurityNativeCritical.java
@@ -0,0 +1,28 @@
+package space.qu4nt.entanglementlib.core.exception.security.critical;
+
+import java.io.Serial;
+
+public class ELIBSecurityNativeCritical extends ELIBSecurityCritical {
+
+ @Serial
+ private static final long serialVersionUID = -7557337159377165891L;
+
+ public ELIBSecurityNativeCritical() {
+ }
+
+ public ELIBSecurityNativeCritical(String message) {
+ super(message);
+ }
+
+ public ELIBSecurityNativeCritical(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ public ELIBSecurityNativeCritical(Throwable cause) {
+ super(cause);
+ }
+
+ public ELIBSecurityNativeCritical(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
+ super(message, cause, enableSuppression, writableStackTrace);
+ }
+}
diff --git a/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/unchecked/ELIBSecurityIllegalArgumentException.java b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/unchecked/ELIBSecurityIllegalArgumentException.java
new file mode 100644
index 0000000..1dd7663
--- /dev/null
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/exception/security/unchecked/ELIBSecurityIllegalArgumentException.java
@@ -0,0 +1,28 @@
+package space.qu4nt.entanglementlib.core.exception.security.unchecked;
+
+import java.io.Serial;
+
+public class ELIBSecurityIllegalArgumentException extends RuntimeException {
+
+ @Serial
+ private static final long serialVersionUID = 3401738922121497475L;
+
+ public ELIBSecurityIllegalArgumentException() {
+ }
+
+ public ELIBSecurityIllegalArgumentException(String message) {
+ super(message);
+ }
+
+ public ELIBSecurityIllegalArgumentException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ public ELIBSecurityIllegalArgumentException(Throwable cause) {
+ super(cause);
+ }
+
+ public ELIBSecurityIllegalArgumentException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
+ super(message, cause, enableSuppression, writableStackTrace);
+ }
+}
diff --git a/core/src/main/java/space/qu4nt/entanglementlib/core/i18n/EntanglementLibCoreI18n.java b/core/src/main/java/space/qu4nt/entanglementlib/core/i18n/EntanglementLibCoreI18n.java
new file mode 100644
index 0000000..36f16f2
--- /dev/null
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/i18n/EntanglementLibCoreI18n.java
@@ -0,0 +1,42 @@
+package space.qu4nt.entanglementlib.core.i18n;
+
+import lombok.Getter;
+import org.jetbrains.annotations.Nullable;
+import space.qu4nt.entanglementlib.core.exception.core.ELIBCoreIllegalArgumentException;
+
+import java.util.Locale;
+import java.util.MissingResourceException;
+import java.util.Objects;
+import java.util.ResourceBundle;
+
+public class EntanglementLibCoreI18n {
+
+ private static final String SYSTEM_DEFAULT_BASENAME = "entanglementlib-messages";
+
+ @Getter
+ private static Locale locale;
+ @Getter
+ private static ResourceBundle coreDefaultResourceBundle;
+ @Getter
+ private static @Nullable ResourceBundle userResourceBundle;
+
+ public static synchronized void initialize(final Locale locale, @Nullable String userResourceBasename) throws ELIBCoreIllegalArgumentException {
+ EntanglementLibCoreI18n.locale = Objects.requireNonNull(locale, "locale is null");
+ // getLanguage() => ISO 639 alpha2
+ try {
+ coreDefaultResourceBundle = ResourceBundle.getBundle(SYSTEM_DEFAULT_BASENAME, locale);
+ } catch (MissingResourceException e) { // 시스템 기본 국제화 파일을 찾을 수 없음
+ throw new ELIBCoreIllegalArgumentException("Could not find 'system default' i18n(" + locale.getLanguage() + ") file");
+ }
+
+ // 사용자 지정된 베이스네임 있으면 사용
+ if (userResourceBasename != null && !userResourceBasename.isBlank()) {
+ try {
+ userResourceBundle = ResourceBundle.getBundle(userResourceBasename, locale);
+ } catch (MissingResourceException e) { // 사용자 지정 국제화 파일을 찾을 수 없음
+ throw new ELIBCoreIllegalArgumentException("Could not find custom i18n(" + locale.getLanguage() + ") file '" + userResourceBasename + "'");
+ }
+ }
+ }
+
+}
diff --git a/src/main/java/space/qu4nt/entanglementlib/util/Async.java b/core/src/main/java/space/qu4nt/entanglementlib/core/util/Async.java
similarity index 94%
rename from src/main/java/space/qu4nt/entanglementlib/util/Async.java
rename to core/src/main/java/space/qu4nt/entanglementlib/core/util/Async.java
index 4a3ed2f..deb2a7e 100644
--- a/src/main/java/space/qu4nt/entanglementlib/util/Async.java
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/util/Async.java
@@ -3,9 +3,9 @@
* Under License "PolyForm Noncommercial License 1.0.0".
*/
-package space.qu4nt.entanglementlib.util;
+package space.qu4nt.entanglementlib.core.util;
-import space.qu4nt.entanglementlib.exception.util.EntLibUtilityException;
+import space.qu4nt.entanglementlib.core.exception.core.ELIBCoreUtilityException;
import java.util.List;
import java.util.concurrent.*;
@@ -67,7 +67,7 @@ public static CompletableFuture> runAsyncTaskList(List>
return future.join();
} catch (CompletionException e) {
// 개별 작업에서 발생한 예외를 감싸서 재처리
- throw new EntLibUtilityException(Async.class, "future-join-in-exc", e);
+ throw new ELIBCoreUtilityException("비동기 작업 중 예외가 발생했습니다!");
}
}).collect(Collectors.toList())
);
diff --git a/src/main/java/space/qu4nt/entanglementlib/util/Nill.java b/core/src/main/java/space/qu4nt/entanglementlib/core/util/Nill.java
similarity index 94%
rename from src/main/java/space/qu4nt/entanglementlib/util/Nill.java
rename to core/src/main/java/space/qu4nt/entanglementlib/core/util/Nill.java
index 5937ebb..29d70ee 100644
--- a/src/main/java/space/qu4nt/entanglementlib/util/Nill.java
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/util/Nill.java
@@ -3,7 +3,9 @@
* Under License "PolyForm Noncommercial License 1.0.0".
*/
-package space.qu4nt.entanglementlib.util;
+package space.qu4nt.entanglementlib.core.util;
+
+import org.jetbrains.annotations.NotNull;
import java.util.function.Supplier;
@@ -86,7 +88,7 @@ public static void ifSo(final T obj, final Runnable runnable) {
* @param 타입 파라미터
* @return 결과
*/
- public static T nullDef(final T obj, final Supplier supplier) {
+ public static @NotNull T nullDef(final T obj, final @NotNull Supplier supplier) {
if (isNull(obj))
return supplier.get();
return obj;
diff --git a/src/main/java/space/qu4nt/entanglementlib/util/StringUtil.java b/core/src/main/java/space/qu4nt/entanglementlib/core/util/StringUtil.java
similarity index 97%
rename from src/main/java/space/qu4nt/entanglementlib/util/StringUtil.java
rename to core/src/main/java/space/qu4nt/entanglementlib/core/util/StringUtil.java
index 93e9e6d..739cd2c 100644
--- a/src/main/java/space/qu4nt/entanglementlib/util/StringUtil.java
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/util/StringUtil.java
@@ -3,9 +3,10 @@
* Under License "PolyForm Noncommercial License 1.0.0".
*/
-package space.qu4nt.entanglementlib.util;
+package space.qu4nt.entanglementlib.core.util;
-import space.qu4nt.entanglementlib.exception.util.EntLibUtilityIllegalArgumentException;
+import space.qu4nt.entanglementlib.core.exception.core.ELIBCoreIllegalArgumentException;
+import space.qu4nt.entanglementlib.core.exception.core.ELIBCoreUtilityException;
import java.util.Objects;
import java.util.UUID;
@@ -61,7 +62,7 @@ public static String replace(String source, String... rep) {
if (source == null)
return null;
if (rep.length % 2 != 0)
- throw new EntLibUtilityIllegalArgumentException(StringUtil.class, "replace-arg-not-even-exc");
+ throw new ELIBCoreUtilityException("replace-arg-not-even-exc");
for (int i = 0; i < rep.length; i += 2)
source = replace(source, rep[i], rep[i + 1]);
return source;
@@ -242,7 +243,7 @@ public static String truncateMiddle(String input, int maxLength, int prefixLengt
return "";
}
if (maxLength <= 0 || prefixLength < 0 || suffixLength < 0)
- throw new EntLibUtilityIllegalArgumentException(StringUtil.class, "truncate-length-exc");
+ throw new ELIBCoreUtilityException("truncate-length-exc");
int inputLength = input.length();
if (inputLength <= maxLength) {
diff --git a/src/main/java/space/qu4nt/entanglementlib/util/chunk/ByteArrayChunkProcessor.java b/core/src/main/java/space/qu4nt/entanglementlib/core/util/chunk/ByteArrayChunkProcessor.java
similarity index 98%
rename from src/main/java/space/qu4nt/entanglementlib/util/chunk/ByteArrayChunkProcessor.java
rename to core/src/main/java/space/qu4nt/entanglementlib/core/util/chunk/ByteArrayChunkProcessor.java
index 7185232..9c6f7d7 100644
--- a/src/main/java/space/qu4nt/entanglementlib/util/chunk/ByteArrayChunkProcessor.java
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/util/chunk/ByteArrayChunkProcessor.java
@@ -3,7 +3,7 @@
* Under License "PolyForm Noncommercial License 1.0.0".
*/
-package space.qu4nt.entanglementlib.util.chunk;
+package space.qu4nt.entanglementlib.core.util.chunk;
import lombok.extern.slf4j.Slf4j;
diff --git a/src/main/java/space/qu4nt/entanglementlib/util/chunk/ChunkProcessor.java b/core/src/main/java/space/qu4nt/entanglementlib/core/util/chunk/ChunkProcessor.java
similarity index 93%
rename from src/main/java/space/qu4nt/entanglementlib/util/chunk/ChunkProcessor.java
rename to core/src/main/java/space/qu4nt/entanglementlib/core/util/chunk/ChunkProcessor.java
index 6db0c3d..5209acf 100644
--- a/src/main/java/space/qu4nt/entanglementlib/util/chunk/ChunkProcessor.java
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/util/chunk/ChunkProcessor.java
@@ -3,7 +3,7 @@
* Under License "PolyForm Noncommercial License 1.0.0".
*/
-package space.qu4nt.entanglementlib.util.chunk;
+package space.qu4nt.entanglementlib.core.util.chunk;
/**
* 대용량 데이터를 청크 단위로 처리할 때 사용되는 함수형 인터페이스입니다.
diff --git a/src/main/java/space/qu4nt/entanglementlib/util/chunk/FileChunkProcessor.java b/core/src/main/java/space/qu4nt/entanglementlib/core/util/chunk/FileChunkProcessor.java
similarity index 99%
rename from src/main/java/space/qu4nt/entanglementlib/util/chunk/FileChunkProcessor.java
rename to core/src/main/java/space/qu4nt/entanglementlib/core/util/chunk/FileChunkProcessor.java
index d434337..e666ab5 100644
--- a/src/main/java/space/qu4nt/entanglementlib/util/chunk/FileChunkProcessor.java
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/util/chunk/FileChunkProcessor.java
@@ -3,7 +3,7 @@
* Under License "PolyForm Noncommercial License 1.0.0".
*/
-package space.qu4nt.entanglementlib.util.chunk;
+package space.qu4nt.entanglementlib.core.util.chunk;
import lombok.extern.slf4j.Slf4j;
diff --git a/src/main/java/space/qu4nt/entanglementlib/util/chunk/StringChunkProcessor.java b/core/src/main/java/space/qu4nt/entanglementlib/core/util/chunk/StringChunkProcessor.java
similarity index 98%
rename from src/main/java/space/qu4nt/entanglementlib/util/chunk/StringChunkProcessor.java
rename to core/src/main/java/space/qu4nt/entanglementlib/core/util/chunk/StringChunkProcessor.java
index afdaf1e..9ea1c64 100644
--- a/src/main/java/space/qu4nt/entanglementlib/util/chunk/StringChunkProcessor.java
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/util/chunk/StringChunkProcessor.java
@@ -3,7 +3,7 @@
* Under License "PolyForm Noncommercial License 1.0.0".
*/
-package space.qu4nt.entanglementlib.util.chunk;
+package space.qu4nt.entanglementlib.core.util.chunk;
import java.util.Objects;
import java.util.stream.IntStream;
diff --git a/src/main/java/space/qu4nt/entanglementlib/util/collection/SafeList.java b/core/src/main/java/space/qu4nt/entanglementlib/core/util/collection/SafeList.java
similarity index 85%
rename from src/main/java/space/qu4nt/entanglementlib/util/collection/SafeList.java
rename to core/src/main/java/space/qu4nt/entanglementlib/core/util/collection/SafeList.java
index d7d7672..9698eaa 100644
--- a/src/main/java/space/qu4nt/entanglementlib/util/collection/SafeList.java
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/util/collection/SafeList.java
@@ -3,10 +3,9 @@
* Under License "PolyForm Noncommercial License 1.0.0".
*/
-package space.qu4nt.entanglementlib.util.collection;
+package space.qu4nt.entanglementlib.core.util.collection;
import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.resource.language.LanguageInstanceBased;
import java.util.ArrayList;
import java.util.Iterator;
@@ -24,9 +23,6 @@
*/
public class SafeList implements Iterable {
- @SuppressWarnings({"rawtypes"})
- private static final LanguageInstanceBased lang = LanguageInstanceBased.create(SafeList.class);
-
private final ArrayList list = new ArrayList<>();
/**
@@ -56,7 +52,7 @@ public synchronized void add(int index, T item) {
public synchronized T remove(int index) {
if (index < 0 || index >= list.size())
- throw new IndexOutOfBoundsException(lang.argsNonTopKey("index-out-of-bounds-exc", index, list.size()));
+ throw new IndexOutOfBoundsException("index-out-of-bounds-exc");
return list.remove(index);
}
@@ -66,13 +62,13 @@ public synchronized boolean remove(T item) {
public synchronized T get(int index) {
if (index < 0 || index >= list.size())
- throw new IndexOutOfBoundsException(lang.argsNonTopKey("index-out-of-bounds-exc", index, list.size()));
+ throw new IndexOutOfBoundsException("index-out-of-bounds-exc");
return list.get(index);
}
public synchronized T set(int index, T item) {
if (index < 0 || index >= list.size())
- throw new IndexOutOfBoundsException(lang.argsNonTopKey("index-out-of-bounds-exc", index, list.size()));
+ throw new IndexOutOfBoundsException("index-out-of-bounds-exc");
return list.set(index, item);
}
diff --git a/src/main/java/space/qu4nt/entanglementlib/util/wrapper/Arrays.java b/core/src/main/java/space/qu4nt/entanglementlib/core/util/wrapper/Arrays.java
similarity index 98%
rename from src/main/java/space/qu4nt/entanglementlib/util/wrapper/Arrays.java
rename to core/src/main/java/space/qu4nt/entanglementlib/core/util/wrapper/Arrays.java
index 8589f12..f7ff7f3 100644
--- a/src/main/java/space/qu4nt/entanglementlib/util/wrapper/Arrays.java
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/util/wrapper/Arrays.java
@@ -3,7 +3,7 @@
* Under License "PolyForm Noncommercial License 1.0.0".
*/
-package space.qu4nt.entanglementlib.util.wrapper;
+package space.qu4nt.entanglementlib.core.util.wrapper;
import java.math.BigInteger;
diff --git a/src/main/java/space/qu4nt/entanglementlib/util/wrapper/Hex.java b/core/src/main/java/space/qu4nt/entanglementlib/core/util/wrapper/Hex.java
similarity index 84%
rename from src/main/java/space/qu4nt/entanglementlib/util/wrapper/Hex.java
rename to core/src/main/java/space/qu4nt/entanglementlib/core/util/wrapper/Hex.java
index fd1dde6..c106848 100644
--- a/src/main/java/space/qu4nt/entanglementlib/util/wrapper/Hex.java
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/util/wrapper/Hex.java
@@ -3,7 +3,7 @@
* Under License "PolyForm Noncommercial License 1.0.0".
*/
-package space.qu4nt.entanglementlib.util.wrapper;
+package space.qu4nt.entanglementlib.core.util.wrapper;
/**
* {@code BouncyCastle} 라이브러리의 {@code Hex} 클래스의 몇 가지
@@ -22,7 +22,7 @@ public final class Hex {
* @return 바이트 배열의 Hex 문자열 표현
*/
public static String toHexString(byte[] bytes) {
- return org.bouncycastle.util.encoders.Hex.toHexString(bytes);
+ return null; // Q. T. Felix TODO: native
}
}
diff --git a/src/main/java/space/qu4nt/entanglementlib/util/wrapper/Pair.java b/core/src/main/java/space/qu4nt/entanglementlib/core/util/wrapper/Pair.java
similarity index 91%
rename from src/main/java/space/qu4nt/entanglementlib/util/wrapper/Pair.java
rename to core/src/main/java/space/qu4nt/entanglementlib/core/util/wrapper/Pair.java
index cbd8c89..9286511 100644
--- a/src/main/java/space/qu4nt/entanglementlib/util/wrapper/Pair.java
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/util/wrapper/Pair.java
@@ -3,7 +3,7 @@
* Under License "PolyForm Noncommercial License 1.0.0".
*/
-package space.qu4nt.entanglementlib.util.wrapper;
+package space.qu4nt.entanglementlib.core.util.wrapper;
import lombok.AllArgsConstructor;
import lombok.Getter;
diff --git a/src/main/java/space/qu4nt/entanglementlib/util/wrapper/Tuple.java b/core/src/main/java/space/qu4nt/entanglementlib/core/util/wrapper/Tuple.java
similarity index 92%
rename from src/main/java/space/qu4nt/entanglementlib/util/wrapper/Tuple.java
rename to core/src/main/java/space/qu4nt/entanglementlib/core/util/wrapper/Tuple.java
index 7bb71a0..e1288b3 100644
--- a/src/main/java/space/qu4nt/entanglementlib/util/wrapper/Tuple.java
+++ b/core/src/main/java/space/qu4nt/entanglementlib/core/util/wrapper/Tuple.java
@@ -3,7 +3,7 @@
* Under License "PolyForm Noncommercial License 1.0.0".
*/
-package space.qu4nt.entanglementlib.util.wrapper;
+package space.qu4nt.entanglementlib.core.util.wrapper;
import lombok.AllArgsConstructor;
import lombok.Getter;
diff --git a/security/build.gradle.kts b/security/build.gradle.kts
new file mode 100644
index 0000000..2208733
--- /dev/null
+++ b/security/build.gradle.kts
@@ -0,0 +1,73 @@
+plugins {
+ id("me.champeau.jmh") version "0.7.3"
+}
+
+dependencies {
+ implementation(project(":core"))
+ implementation(project(":annotations"))
+
+ // JMH
+ jmh("org.openjdk.jmh:jmh-core:1.37")
+ jmh("org.openjdk.jmh:jmh-generator-annprocess:1.37")
+ // Source: https://mvnrepository.com/artifact/org.openjdk.jmh/jmh-core
+ testImplementation("org.openjdk.jmh:jmh-core:1.37")
+ // Source: https://mvnrepository.com/artifact/org.openjdk.jmh/jmh-generator-annprocess
+ testImplementation("org.openjdk.jmh:jmh-generator-annprocess:1.37")
+ jmhAnnotationProcessor("org.projectlombok:lombok:1.18.42")
+}
+
+sourceSets {
+ named("jmh") {
+ java {
+ srcDirs("src/benchmark/java")
+ }
+ resources {
+ srcDirs("src/benchmark/resources")
+ }
+ }
+}
+
+tasks.jar {
+ from("../entlib-native/dist") {
+ into("native")
+ include(
+ "linux/libentlib_native_aarch64.so",
+ "linux/libentlib_native_x86_64.so",
+ "macos/libentlib_native_aarch64.dylib",
+ "macos/libentlib_native_universal.dylib",
+ "macos/libentlib_native_x86_64.dylib",
+ "windows/entlib_native_x86_64.dll"
+ )
+ }
+}
+
+//
+// JMH - start
+//
+jmh {
+ jmhVersion.set("1.37")
+
+ // 테스트 벤치마킹 클래스 등록
+ includeTests.set(true)
+ includes.set(listOf(".*_JMHBenchmark"))
+
+ // 벤치마크 실행 시 필요한 jvm 인자 중앙 제어
+ jvmArgs.set(listOf(
+ "--enable-native-access=ALL-UNNAMED",
+ "--enable-preview",
+ "-Djava.library.path=${rootDir}/native-benchmark/target/debug",
+ "-Xms2g", "-Xmx2g" // gc 간섭 최소화
+ ))
+ fork.set(1)
+
+ // 결과 출력 포맷
+ resultFormat.set("JSON")
+
+ // 벤치마크 수행 옵션 (프로세스 및 반복 횟수)
+ fork.set(1)
+ warmupIterations.set(3)
+ iterations.set(5)
+}
+//
+// JMH - end
+//
\ No newline at end of file
diff --git a/src/benchmark/java/space/qu4nt/entanglementlib/benchmark/NativeAVXCall_JMHBenchmark.java b/security/src/benchmark/java/space/qu4nt/entanglementlib/benchmark/NativeAVXCall_JMHBenchmark.java
similarity index 98%
rename from src/benchmark/java/space/qu4nt/entanglementlib/benchmark/NativeAVXCall_JMHBenchmark.java
rename to security/src/benchmark/java/space/qu4nt/entanglementlib/benchmark/NativeAVXCall_JMHBenchmark.java
index 6a0bab6..13d93a0 100644
--- a/src/benchmark/java/space/qu4nt/entanglementlib/benchmark/NativeAVXCall_JMHBenchmark.java
+++ b/security/src/benchmark/java/space/qu4nt/entanglementlib/benchmark/NativeAVXCall_JMHBenchmark.java
@@ -1,7 +1,8 @@
-package space.qu4nt.entanglementlib.benchmark;/*
+/*
* Copyright © 2025-2026 Quant.
* Under License "PolyForm Noncommercial License 1.0.0".
*/
+package space.qu4nt.entanglementlib.benchmark;
import org.openjdk.jmh.annotations.*;
diff --git a/src/benchmark/java/space/qu4nt/entanglementlib/benchmark/NativeCall_JMHBenchmark.java b/security/src/benchmark/java/space/qu4nt/entanglementlib/benchmark/NativeCall_JMHBenchmark.java
similarity index 99%
rename from src/benchmark/java/space/qu4nt/entanglementlib/benchmark/NativeCall_JMHBenchmark.java
rename to security/src/benchmark/java/space/qu4nt/entanglementlib/benchmark/NativeCall_JMHBenchmark.java
index 82f5979..8e83dd0 100644
--- a/src/benchmark/java/space/qu4nt/entanglementlib/benchmark/NativeCall_JMHBenchmark.java
+++ b/security/src/benchmark/java/space/qu4nt/entanglementlib/benchmark/NativeCall_JMHBenchmark.java
@@ -1,7 +1,8 @@
-package space.qu4nt.entanglementlib.benchmark;/*
+/*
* Copyright © 2025-2026 Quant.
* Under License "PolyForm Noncommercial License 1.0.0".
*/
+package space.qu4nt.entanglementlib.benchmark;
import org.openjdk.jmh.annotations.*;
@@ -59,7 +60,6 @@ public class NativeCall_JMHBenchmark {
);
-
// 보안 벡터 처리 함수
FFM_SECURE_VECTOR_HANDLE = LINKER.downcallHandle(
lookup.find("process_secure_vector").orElseThrow(),
@@ -74,7 +74,6 @@ public class NativeCall_JMHBenchmark {
);
-
// 다항식 모듈러 가산 함수
FFM_POLY_MODULAR_ADD = LINKER.downcallHandle(
lookup.find("poly_modular_add").orElseThrow(),
diff --git a/src/benchmark/resources/logback.xml b/security/src/benchmark/resources/logback.xml
similarity index 100%
rename from src/benchmark/resources/logback.xml
rename to security/src/benchmark/resources/logback.xml
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/EntanglementLibSecurityConfig.java b/security/src/main/java/space/qu4nt/entanglementlib/security/EntanglementLibSecurityConfig.java
new file mode 100644
index 0000000..1b9db53
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/EntanglementLibSecurityConfig.java
@@ -0,0 +1,32 @@
+package space.qu4nt.entanglementlib.security;
+
+import lombok.Getter;
+import lombok.Setter;
+import org.jetbrains.annotations.Nullable;
+import space.qu4nt.entanglementlib.core.util.Nill;
+import space.qu4nt.entanglementlib.security.data.HeuristicArenaFactory;
+import space.qu4nt.entanglementlib.security.entlibnative.NativeSpecContext;
+
+@Getter
+@Setter
+public class EntanglementLibSecurityConfig {
+
+ private NativeSpecContext nativeContext;
+ private HeuristicArenaFactory.ArenaMode arenaMode;
+
+ private EntanglementLibSecurityConfig(final NativeSpecContext nativeContext,
+ final @Nullable HeuristicArenaFactory.ArenaMode arenaMode) {
+ this.nativeContext = nativeContext;
+ this.arenaMode = arenaMode;
+ }
+
+ public static EntanglementLibSecurityConfig create(
+ final NativeSpecContext nativeContext,
+ final @Nullable HeuristicArenaFactory.ArenaMode arenaMode
+ ) {
+ return new EntanglementLibSecurityConfig(
+ Nill.nullDef(nativeContext, NativeSpecContext::defaults),
+ Nill.nullDef(arenaMode, () -> HeuristicArenaFactory.ArenaMode.AUTO)
+ );
+ }
+}
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/EntanglementLibSecurityFacade.java b/security/src/main/java/space/qu4nt/entanglementlib/security/EntanglementLibSecurityFacade.java
new file mode 100644
index 0000000..66eb4ab
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/EntanglementLibSecurityFacade.java
@@ -0,0 +1,17 @@
+package space.qu4nt.entanglementlib.security;
+
+import org.jetbrains.annotations.NotNull;
+import space.qu4nt.entanglementlib.security.data.HeuristicArenaFactory;
+import space.qu4nt.entanglementlib.security.entlibnative.NativeLoader;
+
+public final class EntanglementLibSecurityFacade {
+
+ private EntanglementLibSecurityFacade() {
+ throw new UnsupportedOperationException("cannot access");
+ }
+
+ public static void initialize(@NotNull EntanglementLibSecurityConfig config) {
+ NativeLoader.loadNativeLibrary(config);
+ HeuristicArenaFactory.setGlobalArenaMode(config.getArenaMode());
+ }
+}
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/crypto/ChaCha20.java b/security/src/main/java/space/qu4nt/entanglementlib/security/crypto/ChaCha20.java
new file mode 100644
index 0000000..4882862
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/crypto/ChaCha20.java
@@ -0,0 +1,109 @@
+package space.qu4nt.entanglementlib.security.crypto;
+
+import lombok.extern.slf4j.Slf4j;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import space.qu4nt.entanglementlib.core.exception.security.checked.ELIBSecurityProcessException;
+import space.qu4nt.entanglementlib.security.data.InternalNativeBridge;
+import space.qu4nt.entanglementlib.security.data.SDCScopeContext;
+import space.qu4nt.entanglementlib.security.data.SensitiveDataContainer;
+import space.qu4nt.entanglementlib.security.entlibnative.EntLibNativeManager;
+import space.qu4nt.entanglementlib.security.entlibnative.Function;
+
+import java.lang.foreign.MemorySegment;
+
+@Slf4j
+public final class ChaCha20 {
+
+ private ChaCha20() {
+ throw new UnsupportedOperationException("cannot access");
+ }
+
+ /// ChaCha20-Poly1305 암호화를 수행합니다.
+ ///
+ /// @param context 메모리 소거 생명주기를 관리하는 컨텍스트
+ /// @param key 32바이트 대칭키 (호출 즉시 네이티브로 이전 후 소거됨)
+ /// @param nonce 12바이트 Nonce (호출 즉시 네이티브로 이전 후 소거됨)
+ /// @param aad 추가 인증 데이터 (선택 사항)
+ /// @param plaintext 암호화할 평문 데이터 (호출 즉시 네이티브로 이전 후 소거됨)
+ /// @return 암호화된 사이퍼텍스트(MAC 태그 포함)를 담은 SDC 객체
+ public static @NotNull SensitiveDataContainer encrypt(
+ final @NotNull SDCScopeContext context,
+ final @NotNull SensitiveDataContainer key,
+ final @NotNull SensitiveDataContainer nonce,
+ final @Nullable SensitiveDataContainer aad,
+ final @NotNull SensitiveDataContainer plaintext) throws ELIBSecurityProcessException {
+
+ try {
+ // 입력 데이터를 SDC에 할당하여 네이티브 메모리로 이전 (forceWipe = true로 힙 메모리 즉시 소거)
+ MemorySegment aadSegment = MemorySegment.NULL;
+ long aadLen = 0;
+ if (aad != null) {
+ aadSegment = InternalNativeBridge.unwrapMemorySegment(aad);
+ aadLen = InternalNativeBridge.unwrapMemorySegment(aad).byteSize();
+ }
+
+ // Rust FFI 호출 (Callee-allocated Opaque Pointer 반환)
+ MemorySegment rustBufferPtr = (MemorySegment) EntLibNativeManager
+ .call(Function.ChaCha20_Poly1305_Encrypt)
+ .invokeExact(
+ InternalNativeBridge.unwrapMemorySegment(key), (long) InternalNativeBridge.unwrapMemorySegment(key).byteSize(),
+ InternalNativeBridge.unwrapMemorySegment(nonce), (long) InternalNativeBridge.unwrapMemorySegment(nonce).byteSize(),
+ aadSegment, aadLen,
+ InternalNativeBridge.unwrapMemorySegment(plaintext), (long) InternalNativeBridge.unwrapMemorySegment(plaintext).byteSize()
+ );
+
+ if (rustBufferPtr.equals(MemorySegment.NULL)) {
+ throw new ELIBSecurityProcessException("ChaCha20 암호화 실패: 유효하지 않은 입력 길이");
+ }
+
+ return EntLibNativeManager.transferNativeBufferBindToContext(
+ context, rustBufferPtr
+ );
+ } catch (Throwable t) {
+ log.error("ChaCha20 암호화 중 치명적 보안 예외 발생", t);
+ throw new ELIBSecurityProcessException("암호화 프로세스 실패", t);
+ }
+ }
+
+ /// ChaCha20-Poly1305 복호화를 수행합니다.
+ ///
+ /// @return 복호화된 평문 데이터를 담은 SDC 객체
+ public static @NotNull SensitiveDataContainer decrypt(
+ final @NotNull SDCScopeContext context,
+ final @NotNull SensitiveDataContainer key,
+ final @NotNull SensitiveDataContainer nonce,
+ final @Nullable SensitiveDataContainer aad,
+ final @NotNull SensitiveDataContainer ciphertext) throws ELIBSecurityProcessException {
+
+ try {
+ MemorySegment aadSegment = MemorySegment.NULL;
+ long aadLen = 0;
+ if (aad != null) {
+ aadSegment = InternalNativeBridge.unwrapMemorySegment(aad);
+ aadLen = InternalNativeBridge.unwrapMemorySegment(aad).byteSize();
+ }
+
+ MemorySegment rustBufferPtr = (MemorySegment) EntLibNativeManager
+ .call(Function.ChaCha20_Poly1305_Decrypt)
+ .invokeExact(
+ InternalNativeBridge.unwrapMemorySegment(key), (long) InternalNativeBridge.unwrapMemorySegment(key).byteSize(),
+ InternalNativeBridge.unwrapMemorySegment(nonce), (long) InternalNativeBridge.unwrapMemorySegment(nonce).byteSize(),
+ aadSegment, aadLen,
+ InternalNativeBridge.unwrapMemorySegment(ciphertext), (long) InternalNativeBridge.unwrapMemorySegment(ciphertext).byteSize()
+ );
+
+ // Authentication Failed 또는 입력 오류
+ if (rustBufferPtr.equals(MemorySegment.NULL)) {
+ throw new ELIBSecurityProcessException("ChaCha20 복호화 실패: 무결성 검증(MAC) 실패 또는 유효하지 않은 입력");
+ }
+
+ return EntLibNativeManager.transferNativeBufferBindToContext(
+ context, rustBufferPtr
+ );
+ } catch (Throwable t) {
+ log.error("ChaCha20 복호화 중 치명적 보안 예외 발생", t);
+ throw new ELIBSecurityProcessException("복호화 프로세스 실패", t);
+ }
+ }
+}
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/crypto/encode/Base64.java b/security/src/main/java/space/qu4nt/entanglementlib/security/crypto/encode/Base64.java
new file mode 100644
index 0000000..72d0eb7
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/crypto/encode/Base64.java
@@ -0,0 +1,107 @@
+package space.qu4nt.entanglementlib.security.crypto.encode;
+
+import space.qu4nt.entanglementlib.security.data.InternalNativeBridge;
+import space.qu4nt.entanglementlib.security.data.SensitiveDataContainer;
+import space.qu4nt.entanglementlib.security.entlibnative.EntLibNativeManager;
+import space.qu4nt.entanglementlib.security.entlibnative.Function;
+
+import java.lang.foreign.MemorySegment;
+
+/**
+ * 네이티브 메모리(native memory) 기반의 안전한 Base64 인코딩 및 디코딩 유틸리티입니다.
+ * 모든 입출력은 {@link SensitiveDataContainer}를 통해 소유권(ownership)이 통제되며,
+ * 가비지 컬렉터(garbage collector)가 관리하는 자바 힙(java heap) 메모리에 민감 데이터를 노출하지 않습니다.
+ */
+public final class Base64 {
+
+ private Base64() {
+ throw new AssertionError("유틸리티 클래스는 인스턴스화할 수 없습니다.");
+ }
+
+ /**
+ * 제공된 보안 컨테이너의 데이터를 Base64로 인코딩합니다.
+ * 반환된 새 컨테이너는 호출자(caller)가 소유권을 가지며, 세션 종료 시 명시적으로 소거해야 합니다.
+ *
+ * @param input 원본 데이터가 담긴 보안 컨테이너
+ * @return Base64 인코딩 결과가 담긴 새로운 보안 컨테이너
+ */
+ public static SensitiveDataContainer encode(final SensitiveDataContainer input) {
+ if (input == null || !InternalNativeBridge.unwrapArena(input).scope().isAlive()) {
+ throw new IllegalArgumentException("유효하지 않거나 이미 소거된 입력 컨테이너입니다.");
+ }
+
+ final long inputLen = InternalNativeBridge.unwrapMemorySegment(input).byteSize();
+ final int required = (int) (((inputLen + 2) / 3) * 4);
+
+ SensitiveDataContainer output = new SensitiveDataContainer(required);
+
+ try {
+ long result = (long) EntLibNativeManager.call(Function.Base64_encode).invokeExact(
+ InternalNativeBridge.unwrapMemorySegment(input),
+ inputLen,
+ InternalNativeBridge.unwrapMemorySegment(output),
+ (long) required
+ );
+
+ if (result < 0) {
+ output.close();
+ throw new RuntimeException("인코딩 중 네이티브 오류 발생 (error code): " + result);
+ }
+
+ return output;
+ } catch (Throwable t) {
+ output.close();
+ throw new RuntimeException("FFM API 인코딩 호출 실패", t);
+ }
+ }
+
+ /**
+ * 제공된 보안 컨테이너의 Base64 데이터를 디코딩합니다.
+ * 반환된 새 컨테이너는 호출자(caller)가 소유권을 가지며, 세션 종료 시 명시적으로 소거해야 합니다.
+ *
+ * @param input Base64 인코딩 데이터가 담긴 보안 컨테이너
+ * @return 디코딩된 원본 데이터가 담긴 새로운 보안 컨테이너
+ */
+ public static SensitiveDataContainer decode(final SensitiveDataContainer input) {
+ if (input == null || !InternalNativeBridge.unwrapArena(input).scope().isAlive()) {
+ throw new IllegalArgumentException("유효하지 않거나 이미 소거된 입력 컨테이너입니다.");
+ }
+
+ final long inputLen = InternalNativeBridge.unwrapMemorySegment(input).byteSize();
+ final int maxRequired = (int) ((inputLen / 4 + 1) * 3);
+
+ // 임시 컨테이너 생성 (try-with-resources로 자동 소거 보장)
+ try (SensitiveDataContainer tempOutput = new SensitiveDataContainer(maxRequired)) {
+
+ long result = (long) EntLibNativeManager.call(Function.Base64_decode).invokeExact(
+ InternalNativeBridge.unwrapMemorySegment(input),
+ inputLen,
+ InternalNativeBridge.unwrapMemorySegment(tempOutput),
+ (long) maxRequired
+ );
+
+ if (result < 0) {
+ throw new RuntimeException("디코딩 중 네이티브 오류 발생 (error code): " + result);
+ }
+
+ // 실제 크기에 맞는 반환용 컨테이너 생성 (소유권 이전용)
+ // result(실제 길이)만큼만 할당
+ SensitiveDataContainer exactOutput = new SensitiveDataContainer((int) result);
+
+ try {
+ // 데이터 복사
+ MemorySegment src = InternalNativeBridge.unwrapMemorySegment(tempOutput);
+ MemorySegment dst = InternalNativeBridge.unwrapMemorySegment(exactOutput);
+ MemorySegment.copy(src, 0, dst, 0, result);
+ return exactOutput;
+ } catch (Exception e) {
+ exactOutput.close(); // 복사 중 예외 시 반환용 컨테이너도 닫음
+ throw e;
+ }
+ // 메소드 종료 시 tempOutput.close()가 자동 호출
+
+ } catch (Throwable t) {
+ throw new RuntimeException("FFM API 디코딩 호출 실패", t);
+ }
+ }
+}
\ No newline at end of file
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/crypto/hash/Hash.java b/security/src/main/java/space/qu4nt/entanglementlib/security/crypto/hash/Hash.java
new file mode 100644
index 0000000..46f024a
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/crypto/hash/Hash.java
@@ -0,0 +1,218 @@
+package space.qu4nt.entanglementlib.security.crypto.hash;
+
+import org.jetbrains.annotations.NotNull;
+import space.qu4nt.entanglementlib.core.exception.security.checked.ELIBSecurityProcessException;
+import space.qu4nt.entanglementlib.security.data.InternalNativeBridge;
+import space.qu4nt.entanglementlib.security.data.SDCScopeContext;
+import space.qu4nt.entanglementlib.security.data.SensitiveDataContainer;
+import space.qu4nt.entanglementlib.security.entlibnative.EntLibNativeManager;
+import space.qu4nt.entanglementlib.security.entlibnative.Function;
+
+import java.lang.foreign.MemorySegment;
+import java.lang.invoke.MethodHandle;
+import java.util.stream.IntStream;
+
+public final class Hash {
+
+ public static SensitiveDataContainer sha2(
+ final int length,
+ @NotNull SDCScopeContext scope,
+ @NotNull SensitiveDataContainer input
+ ) throws Throwable {
+ final int[] ableLens = {224, 256, 384, 512};
+ if (IntStream.of(ableLens).noneMatch(l -> l == length))
+ return null;
+
+ // 길이에 맞는 함수 등록
+ Function newContextFunc, updateFunc, finalizeFunc, freeFunc;
+ switch (length) {
+ case 224 -> {
+ newContextFunc = Function.SHA2_224_New;
+ updateFunc = Function.SHA2_224_Update;
+ finalizeFunc = Function.SHA2_224_Finalize;
+ freeFunc = Function.SHA2_224_Free;
+ }
+ case 256 -> {
+ newContextFunc = Function.SHA2_256_New;
+ updateFunc = Function.SHA2_256_Update;
+ finalizeFunc = Function.SHA2_256_Finalize;
+ freeFunc = Function.SHA2_256_Free;
+ }
+ case 384 -> {
+ newContextFunc = Function.SHA2_384_New;
+ updateFunc = Function.SHA2_384_Update;
+ finalizeFunc = Function.SHA2_384_Finalize;
+ freeFunc = Function.SHA2_384_Free;
+ }
+ case 512 -> {
+ newContextFunc = Function.SHA2_512_New;
+ updateFunc = Function.SHA2_512_Update;
+ finalizeFunc = Function.SHA2_512_Finalize;
+ freeFunc = Function.SHA2_512_Free;
+ }
+ default -> throw new ELIBSecurityProcessException("불가능한 길이");
+ }
+
+ // 컨텍스트 생성
+ MemorySegment ctx = (MemorySegment) EntLibNativeManager.call(newContextFunc).invokeExact();
+ boolean isCtxConsumed = false; // double-free 방지를 위한 상태 플래그
+
+ try {
+ // 데이터 업데이트
+ MethodHandle updateMH = EntLibNativeManager.call(updateFunc);
+ MemorySegment dataSeg = InternalNativeBridge.unwrapMemorySegment(input);
+ int status = (int) updateMH.invokeExact(ctx, dataSeg, dataSeg.byteSize());
+ if (status != 0) {
+ throw new ELIBSecurityProcessException("업데이트 실패, 상태 코드: " + status);
+ }
+
+ // 연산 수행 -> SecureBuffer* 반환 (ctx 소유권 소비됨)
+ MemorySegment secureBufferPtr = (MemorySegment) EntLibNativeManager.call(finalizeFunc)
+ .invokeExact(ctx);
+ isCtxConsumed = true; // 성공적으로 finalize 되었으므로 플래그 전환
+
+ if (secureBufferPtr.equals(MemorySegment.NULL))
+ throw new ELIBSecurityProcessException("해시 연산 결과가 null입니다!");
+
+ return EntLibNativeManager.transferNativeBufferBindToContext(
+ scope, secureBufferPtr
+ ); // 이 작업 내에서 버퍼 소거가 진행됨
+ } finally {
+ // 예외 발생 등으로 인해 finalize가 호출되지 않은 경우에만 early free
+ if (!isCtxConsumed && ctx != null && !ctx.equals(MemorySegment.NULL)) {
+ EntLibNativeManager.call(freeFunc).invokeExact(ctx);
+ }
+ }
+ }
+
+ public static SensitiveDataContainer sha3(
+ final int length,
+ @NotNull SDCScopeContext scope,
+ @NotNull SensitiveDataContainer input
+ ) throws Throwable {
+ final int[] ableLens = {224, 256, 384, 512};
+ if (IntStream.of(ableLens).noneMatch(l -> l == length))
+ return null;
+
+ // 길이에 맞는 함수 등록
+ Function newContextFunc, updateFunc, finalizeFunc, freeFunc;
+ switch (length) {
+ case 224 -> {
+ newContextFunc = Function.SHA3_224_New;
+ updateFunc = Function.SHA3_224_Update;
+ finalizeFunc = Function.SHA3_224_Finalize;
+ freeFunc = Function.SHA3_224_Free;
+ }
+ case 256 -> {
+ newContextFunc = Function.SHA3_256_New;
+ updateFunc = Function.SHA3_256_Update;
+ finalizeFunc = Function.SHA3_256_Finalize;
+ freeFunc = Function.SHA3_256_Free;
+ }
+ case 384 -> {
+ newContextFunc = Function.SHA3_384_New;
+ updateFunc = Function.SHA3_384_Update;
+ finalizeFunc = Function.SHA3_384_Finalize;
+ freeFunc = Function.SHA3_384_Free;
+ }
+ case 512 -> {
+ newContextFunc = Function.SHA3_512_New;
+ updateFunc = Function.SHA3_512_Update;
+ finalizeFunc = Function.SHA3_512_Finalize;
+ freeFunc = Function.SHA3_512_Free;
+ }
+ default -> throw new ELIBSecurityProcessException("불가능한 길이");
+ }
+
+ // 컨텍스트 생성
+ MemorySegment ctx = (MemorySegment) EntLibNativeManager.call(newContextFunc).invokeExact();
+ boolean isCtxConsumed = false; // double-free 방지를 위한 상태 플래그
+
+ try {
+ // 데이터 업데이트
+ MethodHandle updateMH = EntLibNativeManager.call(updateFunc);
+ MemorySegment dataSeg = InternalNativeBridge.unwrapMemorySegment(input);
+ int status = (int) updateMH.invokeExact(ctx, dataSeg, dataSeg.byteSize());
+ if (status != 0) {
+ throw new ELIBSecurityProcessException("업데이트 실패, 상태 코드: " + status);
+ }
+
+ // 연산 수행 -> SecureBuffer* 반환 (ctx 소유권 소비됨)
+ MemorySegment secureBufferPtr = (MemorySegment) EntLibNativeManager.call(finalizeFunc)
+ .invokeExact(ctx);
+ isCtxConsumed = true; // 성공적으로 finalize 되었으므로 플래그 전환
+
+ if (secureBufferPtr.equals(MemorySegment.NULL))
+ throw new ELIBSecurityProcessException("해시 연산 결과가 null입니다!");
+
+ return EntLibNativeManager.transferNativeBufferBindToContext(
+ scope, secureBufferPtr
+ ); // 이 작업 내에서 버퍼 소거가 진행됨
+ } finally {
+ // 예외 발생 등으로 인해 finalize가 호출되지 않은 경우에만 early free
+ if (!isCtxConsumed && ctx != null && !ctx.equals(MemorySegment.NULL)) {
+ EntLibNativeManager.call(freeFunc).invokeExact(ctx);
+ }
+ }
+ }
+
+ public static SensitiveDataContainer sha3Shake(
+ final int length,
+ final long byteOutLen,
+ @NotNull SDCScopeContext scope,
+ @NotNull SensitiveDataContainer input
+ ) throws Throwable {
+ final int[] ableLens = {128, 256};
+ if (IntStream.of(ableLens).noneMatch(l -> l == length))
+ return null;
+
+ // 길이에 맞는 함수 등록
+ Function newContextFunc, updateFunc, finalizeFunc, freeFunc;
+ switch (length) {
+ case 128 -> {
+ newContextFunc = Function.SHA3_SHAKE128_New;
+ updateFunc = Function.SHA3_SHAKE128_Update;
+ finalizeFunc = Function.SHA3_SHAKE128_Finalize;
+ freeFunc = Function.SHA3_SHAKE128_Free;
+ }
+ case 256 -> {
+ newContextFunc = Function.SHA3_SHAKE256_New;
+ updateFunc = Function.SHA3_SHAKE256_Update;
+ finalizeFunc = Function.SHA3_SHAKE256_Finalize;
+ freeFunc = Function.SHA3_SHAKE256_Free;
+ }
+ default -> throw new ELIBSecurityProcessException("불가능한 길이");
+ }
+
+ // 컨텍스트 생성
+ MemorySegment ctx = (MemorySegment) EntLibNativeManager.call(newContextFunc).invokeExact();
+ boolean isCtxConsumed = false; // double-free 방지를 위한 상태 플래그
+
+ try {
+ // 데이터 업데이트
+ MethodHandle updateMH = EntLibNativeManager.call(updateFunc);
+ MemorySegment dataSeg = InternalNativeBridge.unwrapMemorySegment(input);
+ int status = (int) updateMH.invokeExact(ctx, dataSeg, dataSeg.byteSize());
+ if (status != 0) {
+ throw new ELIBSecurityProcessException("업데이트 실패, 상태 코드: " + status);
+ }
+
+ // 연산 수행 -> SecureBuffer* 반환 (ctx 소유권 소비됨)
+ MemorySegment secureBufferPtr = (MemorySegment) EntLibNativeManager.call(finalizeFunc)
+ .invokeExact(ctx, byteOutLen);
+ isCtxConsumed = true; // 성공적으로 finalize 되었으므로 플래그 전환
+
+ if (secureBufferPtr.equals(MemorySegment.NULL))
+ throw new ELIBSecurityProcessException("해시 연산 결과가 null입니다.");
+
+ return EntLibNativeManager.transferNativeBufferBindToContext(
+ scope, secureBufferPtr
+ ); // 이 작업 내에서 버퍼 소거가 진행됨
+ } finally {
+ // 예외 발생 등으로 인해 finalize가 호출되지 않은 경우에만 early free
+ if (!isCtxConsumed && ctx != null && !ctx.equals(MemorySegment.NULL)) {
+ EntLibNativeManager.call(freeFunc).invokeExact(ctx);
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/crypto/rng/RNG.java b/security/src/main/java/space/qu4nt/entanglementlib/security/crypto/rng/RNG.java
new file mode 100644
index 0000000..e5e9473
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/crypto/rng/RNG.java
@@ -0,0 +1,90 @@
+package space.qu4nt.entanglementlib.security.crypto.rng;
+
+import org.jetbrains.annotations.NotNull;
+import space.qu4nt.entanglementlib.core.exception.security.checked.ELIBSecurityProcessException;
+import space.qu4nt.entanglementlib.core.exception.security.critical.ELIBSecurityNativeCritical;
+import space.qu4nt.entanglementlib.security.data.InternalNativeBridge;
+import space.qu4nt.entanglementlib.security.data.SDCScopeContext;
+import space.qu4nt.entanglementlib.security.data.SensitiveDataContainer;
+import space.qu4nt.entanglementlib.security.entlibnative.EntLibNativeManager;
+import space.qu4nt.entanglementlib.security.entlibnative.Function;
+
+import java.lang.foreign.Arena;
+import java.lang.foreign.MemorySegment;
+import java.lang.foreign.ValueLayout;
+
+/// 하드웨어 진난수 및 양자 난수(quantum random number) 생성 인터페이스입니다.
+/// 모든 반환 데이터는 네이티브 스코프 내에서 완벽한 데이터 소거(zeroize)가 보장됩니다.
+///
+/// @author Q. T. Felix
+public final class RNG {
+
+ public static final byte LOCAL_HARDWARE = (byte) 0;
+ public static final byte QUANTUM_NETWORK = (byte) 1;
+
+ /// 지정된 엔트로피 전략(entropy strategy)에 따라 난수를 생성하고 컨테이너에 바인딩합니다.
+ ///
+ /// @param entropyStrategy 난수 생성 전략 (로컬 하드웨어 또는 양자 네트워크)
+ /// @param scope 보안 데이터 생명주기를 관리하는 컨텍스트(context)
+ /// @param length 생성할 난수의 바이트 길이
+ /// @return `heap` 오염 없이 난수 데이터를 소유하는 민감 데이터 컨테이너
+ /// @throws ELIBSecurityProcessException 난수 생성 또는 복사 중 에러 발생 시
+ public static SensitiveDataContainer generateRNG(final byte entropyStrategy,
+ final @NotNull SDCScopeContext scope,
+ final long length) throws ELIBSecurityProcessException {
+
+ // FFI 호출에 필요한 파라미터 및 포인터를 임시 관리하기 위한 로컬 아레나(arena)
+ try (Arena localArena = Arena.ofConfined()) {
+ MemorySegment errFlag = localArena.allocate(ValueLayout.JAVA_BYTE);
+
+ // 혼합 난수 생성기(mixed rng) 인스턴스 초기화
+ MemorySegment rngPtr = (MemorySegment) EntLibNativeManager.call(Function.RNG_MIXED_New_With_Strategy)
+ .invokeExact(entropyStrategy, errFlag);
+ checkError(errFlag.get(ValueLayout.JAVA_BYTE, 0));
+
+ MemorySegment secureBufPtr = null;
+ try {
+ // 난수 버퍼 생성
+ secureBufPtr = (MemorySegment) EntLibNativeManager.call(Function.RNG_MIXED_Generate)
+ .invokeExact(rngPtr, length, errFlag);
+ checkError(errFlag.get(ValueLayout.JAVA_BYTE, 0));
+
+ // 러스트 영역의 보안 버퍼(secure buffer)에서 실제 데이터 포인터 추출
+ MemorySegment dataPtr = (MemorySegment) EntLibNativeManager.call(Function.Callee_Secure_Buffer_Data)
+ .invokeExact(secureBufPtr);
+ MemorySegment nativeDataSegment = dataPtr.reinterpret(length);
+
+ // 컨텍스트를 통한 SDC 할당
+ SensitiveDataContainer sdc = scope.allocate((int) length);
+
+ // heap 배열을 거치지 않고 네이티브 대 네이티브로 직접 메모리 복사 수행
+ MemorySegment.copy(nativeDataSegment, 0, InternalNativeBridge.unwrapMemorySegment(sdc), 0, length);
+
+ return sdc;
+ } finally {
+ // 러스트 힙에 할당된 포인터의 강제 해제 및 소거 유도
+ if (secureBufPtr != null && !secureBufPtr.equals(MemorySegment.NULL)) {
+ EntLibNativeManager.call(Function.Callee_Secure_Buffer_Free).invokeExact(secureBufPtr);
+ }
+ if (rngPtr != null && !rngPtr.equals(MemorySegment.NULL)) {
+ EntLibNativeManager.call(Function.RNG_MIXED_Free).invokeExact(rngPtr);
+ }
+ }
+ } catch (Throwable e) {
+ throw new ELIBSecurityProcessException("네이티브 브릿지를 통한 난수 생성에 실패했습니다.", e);
+ }
+ }
+
+ private static void checkError(byte errorCode) {
+ if (errorCode == 0) return;
+ throw switch (errorCode) {
+ case 1 -> new ELIBSecurityNativeCritical("지원하지 않는 하드웨어(hardware) 환경입니다!");
+ case 2 -> new ELIBSecurityNativeCritical("엔트로피(entropy)가 고갈되었습니다!");
+ case 3 -> new ELIBSecurityNativeCritical("잘못된 메모리 포인터(pointer) 참조입니다!");
+ case 4 -> new ELIBSecurityNativeCritical("양자 난수 생성기 네트워크(network) 통신에 실패했습니다!");
+ case 5 -> new ELIBSecurityNativeCritical("양자 난수 데이터 파싱(parsing) 에러가 발생했습니다!");
+ case 6 -> new ELIBSecurityNativeCritical("잘못된 파라미터(parameter)가 전달되었습니다!");
+ default -> new ELIBSecurityNativeCritical("알 수 없는 네이티브(native) 에러 코드: " + errorCode);
+ };
+ }
+}
\ No newline at end of file
diff --git a/src/main/java/space/qu4nt/entanglementlib/HeuristicArenaFactory.java b/security/src/main/java/space/qu4nt/entanglementlib/security/data/HeuristicArenaFactory.java
similarity index 98%
rename from src/main/java/space/qu4nt/entanglementlib/HeuristicArenaFactory.java
rename to security/src/main/java/space/qu4nt/entanglementlib/security/data/HeuristicArenaFactory.java
index 1dc2662..37bd509 100644
--- a/src/main/java/space/qu4nt/entanglementlib/HeuristicArenaFactory.java
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/data/HeuristicArenaFactory.java
@@ -3,7 +3,7 @@
* Under License "PolyForm Noncommercial License 1.0.0".
*/
-package space.qu4nt.entanglementlib;
+package space.qu4nt.entanglementlib.security.data;
import lombok.extern.slf4j.Slf4j;
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/data/InternalNativeBridge.java b/security/src/main/java/space/qu4nt/entanglementlib/security/data/InternalNativeBridge.java
new file mode 100644
index 0000000..0285cd4
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/data/InternalNativeBridge.java
@@ -0,0 +1,24 @@
+package space.qu4nt.entanglementlib.security.data;
+
+import org.jetbrains.annotations.NotNull;
+import space.qu4nt.entanglementlib.annotations.Unsafe;
+
+import java.lang.foreign.Arena;
+import java.lang.foreign.MemorySegment;
+import java.util.Objects;
+
+public final class InternalNativeBridge {
+
+ private InternalNativeBridge() {
+ }
+
+ @Unsafe("사용자가 직접 Arena를 조작하는 것은 권장되지 않음")
+ public static @NotNull Arena unwrapArena(final @NotNull SensitiveDataContainer container) {
+ return Objects.requireNonNull(container, "container").getArena();
+ }
+
+ @Unsafe("MemorySegment는 내부적으로 heap에 데이터가 운반될 수 있는 기능을 포함")
+ public static @NotNull MemorySegment unwrapMemorySegment(final @NotNull SensitiveDataContainer container) {
+ return Objects.requireNonNull(container, "container").getMemorySegment();
+ }
+}
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/data/SDCConsumer.java b/security/src/main/java/space/qu4nt/entanglementlib/security/data/SDCConsumer.java
new file mode 100644
index 0000000..27b03ee
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/data/SDCConsumer.java
@@ -0,0 +1,9 @@
+package space.qu4nt.entanglementlib.security.data;
+
+import space.qu4nt.entanglementlib.core.exception.security.checked.ELIBSecurityProcessException;
+
+@FunctionalInterface
+public interface SDCConsumer {
+
+ void accept(SensitiveDataContainer container) throws ELIBSecurityProcessException;
+}
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/data/SDCFunction.java b/security/src/main/java/space/qu4nt/entanglementlib/security/data/SDCFunction.java
new file mode 100644
index 0000000..3149e0a
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/data/SDCFunction.java
@@ -0,0 +1,9 @@
+package space.qu4nt.entanglementlib.security.data;
+
+import space.qu4nt.entanglementlib.core.exception.security.checked.ELIBSecurityProcessException;
+
+@FunctionalInterface
+public interface SDCFunction {
+
+ R apply(SensitiveDataContainer container) throws ELIBSecurityProcessException;
+}
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/data/SDCScopeContext.java b/security/src/main/java/space/qu4nt/entanglementlib/security/data/SDCScopeContext.java
new file mode 100644
index 0000000..c08aa8d
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/data/SDCScopeContext.java
@@ -0,0 +1,61 @@
+package space.qu4nt.entanglementlib.security.data;
+
+import lombok.extern.slf4j.Slf4j;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/// 보안 작업 흐름 내에서 생성되는 모든 민감 데이터 컨테이너를 추적하고,
+/// 스코프 종료 시 일괄 소거(zeroize)를 보장하는 컨텍스트 클래스입니다.
+///
+/// @author Q. T. Felix
+/// @since 1.1.1
+@Slf4j
+public final class SDCScopeContext implements AutoCloseable {
+
+ private final List<@NotNull SensitiveDataContainer> trackedContainers = Collections.synchronizedList(new ArrayList<>());
+ private volatile boolean isAlive = true;
+
+ /// 스코프 내에서 새로운 [SensitiveDataContainer]를 할당하는 메소드입니다.
+ /// 생성된 컨테이너는 자동으로 현재 스코프에 바인딩됩니다.
+ public SensitiveDataContainer allocate(int size) {
+ checkAlive();
+ SensitiveDataContainer container = new SensitiveDataContainer(size);
+ trackedContainers.add(container);
+ return container;
+ }
+
+ /// 기존 바이트 배열로부터 데이터 소유권을 이전받는 컨테이너를 생성하는 메소드입니다.
+ public SensitiveDataContainer allocate(byte[] from, boolean forceWipe) {
+ checkAlive();
+ SensitiveDataContainer container = new SensitiveDataContainer(from, forceWipe);
+ trackedContainers.add(container);
+ return container;
+ }
+
+ private void checkAlive() {
+ if (!isAlive)
+ throw new IllegalStateException("이미 소거 완료된 보안 스코프입니다!");
+ }
+
+ @Override
+ public void close() {
+ if (!isAlive) return;
+ isAlive = false;
+
+ // 스냅샷 소거
+ synchronized (trackedContainers) {
+ for (int i = trackedContainers.size() - 1; i >= 0; i--) {
+ SensitiveDataContainer sdc = trackedContainers.get(i);
+ try {
+ sdc.close();
+ } catch (Exception e) {
+ log.error("컨텍스트 내부 컨테이너 소거 중 오류 발생", e);
+ }
+ }
+ trackedContainers.clear();
+ }
+ }
+}
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/data/SensitiveDataContainer.java b/security/src/main/java/space/qu4nt/entanglementlib/security/data/SensitiveDataContainer.java
new file mode 100644
index 0000000..459f5f7
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/data/SensitiveDataContainer.java
@@ -0,0 +1,224 @@
+/*
+ * Copyright © 2025-2026 Quant.
+ * Under License "PolyForm Noncommercial License 1.0.0".
+ */
+
+package space.qu4nt.entanglementlib.security.data;
+
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.extern.slf4j.Slf4j;
+import org.jetbrains.annotations.NotNull;
+import space.qu4nt.entanglementlib.annotations.CallerResponsibility;
+import space.qu4nt.entanglementlib.core.exception.security.checked.ELIBSecurityProcessException;
+import space.qu4nt.entanglementlib.security.entlibnative.EntLibNativeManager;
+import space.qu4nt.entanglementlib.security.entlibnative.Function;
+
+import java.io.IOException;
+import java.lang.foreign.Arena;
+import java.lang.foreign.MemorySegment;
+import java.lang.foreign.ValueLayout;
+import java.nio.ByteBuffer;
+import java.nio.channels.WritableByteChannel;
+import java.util.Arrays;
+import java.util.Objects;
+
+/// `Rust`의 소유권(ownership) 개념처럼 이 클래스도 전달받은 민감 정보에 대한 소유권을 가집니다.
+/// 이 클래스에 저장된 데이터는 진행중인 세션에 종속되고, 세션이 종료됨에 따라 모든 데이터가 완벽하게
+/// 소거됩니다. 데이터 소거는 `entlib-native`에서 진행됩니다.
+///
+/// 이 객체를 통해 네이티브 함수에 필요한 데이터를 전달하거나, 함수 실행 결과를 받을 수 있습니다.
+/// 이 경우 **"호출자 패턴"이 사용되며, 해당 데이터의 소거는 보장되지만 할당 해제 권한이 이 객체에
+/// 부여**되어 반드시 지정된 데이터에 대한 할당 해제 함수를 호출해야 합니다.
+///
+/// 하지만 이 객체는 [AutoCloseable] 인터페이스를 구현함으로서 [#close()] 수행 시 호출자 측
+/// 메모리 해제 함수를 자동으로 호출해줍니다.
+///
+/// ---
+///
+/// [#SensitiveDataContainer(byte\[\], boolean)] 생성자를 사용하여 전달받은 바이트 배열
+/// 데이터에 대한 `heap` 소거 진행 여부를 지정할 수 있습니다. 논리 값이 `true`일 경우 데이터는
+/// Java `heap` 메모리에서 즉시 소거됩니다.
+///
+/// # Usage
+/// 이전엔 일일이 컨테이너를 연결해주어야 했습니다. 이 과정을 축약하기 위해 [SDCScopeContext]
+/// 개념을 도입했습니다. 이 객체를 통해 스코프를 생성하고 내부의 전체 컨테이너에 대해 작업
+/// 완료 시 안전하게 소거 및 할당 해제 작업을 자동으로 수행하도록 할 수 있습니다.
+/// ```java
+/// // 보안 세션 시작
+/// try (SecureScopeContext scope = new SecureScopeContext()) {
+///
+/// // allocate raw key data
+/// SensitiveDataContainer rawKey = scope.allocate(32);
+///
+/// // generate PQC key pair
+/// SensitiveDataContainer pqcCiphertext = PQC.encapsulate(scope, rawKey);
+///
+/// // encode to Base64 for transmission
+/// SensitiveDataContainer b64Data = Base64.encode(scope, pqcCiphertext);
+///
+/// // ...network transmission 또는 별도의 로직...
+///
+/// } // 스코프가 닫히는 순간 rawKey, pqcCiphertext, b64Data가 역순으로 완벽하게 소거
+/// // 네이티브에 FFI로 넘어온 할당 해제 함수를 자동으로 호출하여 지정된 객체에 대해 모두 수행
+/// ```
+/// 위와 같은 사용은 통신 체계에서 매우 유용하게 사용될 수 있습니다.
+///
+/// 작업량이 스코프 작업에 어울리지 않을 수도 있습니다. 예를 들어, 보안 난수 생성 및 세션 내에서
+/// 구조화된 경량 통신 체계를 구축할 때는 다음과 같이 사용될 수 있습니다.
+/// ```java
+/// SensitiveDataContainer.runScope(256, container -> {
+/// // ...Secure stuff...
+/// }); // 소비 패턴
+///
+/// int resultSize = SensitiveDataContainer.callScope(1024, container -> {
+/// // ...Secure stuff...
+/// return container.getMemorySegment().byteSize();
+/// }); // 반환 패턴
+/// ```
+/// 각 메소드의 모든 작업은 `try-with-resources` 블럭 내에서 사용됩니다.
+///
+/// # Safety
+/// 이 객체의 인스턴스를 직접 생성해야 하는 경우 다음과 같이 네이티브에 메모리 할당 해제 함수를
+/// 호출하여 사용해야 합니다.
+/// ```java
+/// SensitiveDataContainer sdc = ...;
+/// final MemorySegment ms = sdc.getMemorySegment();
+/// // ...Secure stuff...
+/// EntLibNativeManager.call(Function.Caller_Secure_Buffer_Wipe)
+/// .invokeExact(ms, ms.byteSize());
+/// ```
+/// 이 객체를 상속받아 사용되는 경우도 일관된 사용법을 따를 수 있습니다.
+///
+/// @author Q. T. Felix
+/// @see HeuristicArenaFactory Arena 자동 할당을 수행하는 클래스
+/// @see SDCScopeContext
+/// @since 1.1.0
+@Slf4j
+public class SensitiveDataContainer implements AutoCloseable {
+
+ @Getter(AccessLevel.PACKAGE)
+ private final Arena arena;
+ @Getter(AccessLevel.PACKAGE)
+ private final MemorySegment memorySegment;
+
+ /// 네이티브 메모리에 전달받은 정수 값(바이트 크기) 만큼의 메모리 세그먼트를
+ /// 생성하여 이 인스턴스를 생성합니다.
+ ///
+ /// # Safety
+ /// 이 생성자를 통해 인스턴스를 생성하면 호출자가 부담하는 보안 책임이 발생합니다.
+ /// 특별한 경우가 아닌 이상 이 방식을 통한 생성은 권장하지 않습니다.
+ ///
+ /// 또한, 이 생성자는 제거 예정은 없으나 권장되는 사용이 아닙니다. [SDCScopeContext]를
+ /// 통해 세션식 보안 작업을 수행하세요.
+ ///
+ /// @param allocateSIze 바이트 크기
+ /// @see #runScope(int, SDCConsumer) 스코프 작업 종료 시 자원 소거를 보장하는 정적 메소드
+ /// @see #callScope(int, SDCFunction) 스코프 작업 종료 후 자원을 소거하고 가공된 결과를 반환하는 정적 메소드
+ @CallerResponsibility("try-with-resource 사용 또는 close 메소드 직접 호출 필수")
+ public SensitiveDataContainer(final int allocateSIze) {
+ this.arena = HeuristicArenaFactory.intelligenceCreateArena();
+ this.memorySegment = Objects.requireNonNull(arena.allocate(allocateSIze));
+ }
+
+ /// 원본 바이트 배열을 전달받고 네이티브 메모리에 바인딩하여 이 인스턴스를 생성합니다.
+ ///
+ /// 생성 시점에 전달받은 원본 바이트 배열 데이터에 대한 소유권을 이 인스턴스에 넘길지 결정할 수
+ /// 있습니다. 논리 값이 `true`일 경우 데이터는 즉시 소거되고, 이는 이 인스턴스가 소유권을
+ /// 가질 필요가 없다는 것을 의미합니다.
+ ///
+ /// # Safety
+ /// 이 생성자를 통해 인스턴스를 생성하면 호출자가 부담하는 보안 책임이 발생합니다.
+ /// 특별한 경우가 아닌 이상 이 방식을 통한 생성은 권장하지 않습니다. 또한, 결국
+ /// `heap` 메모리에 데이터를 노출하는 것은 위험합니다.
+ ///
+ /// 또한, 이 생성자는 제거 예정은 없으나 권장되는 사용이 아닙니다. [SDCScopeContext]를
+ /// 통해 세션식 보안 작업을 수행하세요.
+ ///
+ /// @param from 네이티브 메모리에 바인딩할 원본 바이트 배열
+ /// @param forceWipe 인스턴스에 소유권 이전 여부
+ /// @see #runScope(int, SDCConsumer) 스코프 작업 종료 시 자원 소거를 보장하는 정적 메소드
+ /// @see #callScope(int, SDCFunction) 스코프 작업 종료 후 자원을 소거하고 가공된 결과를 반환하는 정적 메소드
+ @CallerResponsibility("try-with-resource 사용 또는 close 메소드 직접 호출 필수")
+ public SensitiveDataContainer(final byte @NotNull [] from, boolean forceWipe) {
+ this.arena = HeuristicArenaFactory.intelligenceCreateArena();
+ this.memorySegment = Objects.requireNonNull(arena.allocateFrom(ValueLayout.JAVA_BYTE, from));
+ if (forceWipe)
+ Arrays.fill(from, (byte) 0);
+ }
+
+ /**
+ * 보안 컨테이너의 생명주기를 자동으로 관리하는 실행 메소드입니다.
+ * Execute-Around-Pattern이 적용되어 작업 완료 즉시 메모리가 소거됨을 보장합니다.
+ *
+ * @param allocateSize 할당할 버퍼 크기
+ * @param action 컨테이너를 사용하여 수행할 보안 로직
+ */
+ public static void runScope(int allocateSize, SDCConsumer action) throws ELIBSecurityProcessException {
+ try (SensitiveDataContainer sdc = new SensitiveDataContainer(allocateSize)) {
+ action.accept(sdc);
+ }
+ }
+
+ /// 보안 컨테이너를 사용하여 값을 계산하고 반환하는 실행 메소드입니다.
+ /// 반환값은 민감한 데이터(`byte[]`)가 아닌, 가공된 결과물(암호화 성공 여부, 상태 코드 등)이어야 합니다.
+ ///
+ /// @param allocateSize 할당할 버퍼 크기
+ /// @param action 컨테이너를 사용하여 수행할 계산 로직
+ /// @return 계산 결과
+ public static R callScope(int allocateSize, SDCFunction action) throws ELIBSecurityProcessException {
+ try (SensitiveDataContainer sdc = new SensitiveDataContainer(allocateSize)) {
+ return action.apply(sdc);
+ }
+ }
+
+ public static void transmitZeroCopy(SensitiveDataContainer sdc, WritableByteChannel channel) throws ELIBSecurityProcessException {
+ if (!sdc.getArena().scope().isAlive()) {
+ throw new IllegalStateException("이미 소거 완료되었거나 유효하지 않은 컨테이너입니다!");
+ }
+
+ // 메소드 내부에서만 생존하는 임시 Direct ByteBuffer 뷰 생성
+ // 이 객체는 절대 외부로 반환되거나 다른 스레드로 전달되어서는 안 됨
+ ByteBuffer transientView = sdc.getMemorySegment().asByteBuffer();
+
+ // WritableByteChannel (SocketChannel 등)에 기록
+ // 채널이 Direct ByteBuffer를 인식하면 Java Heap으로 데이터를 복사하지 않고
+ // JNI를 통해 OS의 write() 또는 send() 시스템 콜로 메모리 주소를 직접 넘김
+ while (transientView.hasRemaining()) {
+ try {
+ channel.write(transientView);
+ } catch (IOException e) {
+ throw new ELIBSecurityProcessException(e);
+ }
+ }
+
+ // gc hint
+ transientView = null;
+ }
+
+ @Override
+ public void close() {
+ // 더 이상 하위 바인딩(bindings)을 관리하지 않아 로직 수정 //
+ // 스레드 안전성과 다중 호출 시의 멱등성을 보장하기 위해 인스턴스 락 사용
+ synchronized (this) {
+ // 이미 닫힌 경우 early-return
+ if (this.arena == null || !this.arena.scope().isAlive()) {
+ log.debug("이미 소거 완료되었거나 유효하지 않은 컨테이너입니다.");
+ return;
+ }
+
+ try {
+ // 호출자 측 네이티브 메모리 완벽 소거 & 할당 해제
+ EntLibNativeManager
+ .call(Function.Caller_Secure_Buffer_Wipe)
+ .invokeExact(this.memorySegment, this.memorySegment.byteSize());
+ } catch (Throwable e) {
+ // 네이티브 소거 실패는 치명적 보안 이벤트이기 떄문에 에러 출력
+ log.error("치명적 보안 예외가 발생했습니다!", e);
+ } finally {
+ // 예외 발생 여부와 상관없이 접근 채널은 반드시 닫음
+ this.arena.close();
+ }
+ }
+ }
+}
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/EntLibNativeManager.java b/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/EntLibNativeManager.java
new file mode 100644
index 0000000..91763ef
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/EntLibNativeManager.java
@@ -0,0 +1,123 @@
+package space.qu4nt.entanglementlib.security.entlibnative;
+
+import org.jetbrains.annotations.NotNull;
+import space.qu4nt.entanglementlib.core.exception.security.checked.ELIBSecurityProcessException;
+import space.qu4nt.entanglementlib.core.exception.security.critical.ELIBSecurityCritical;
+import space.qu4nt.entanglementlib.core.exception.security.critical.ELIBSecurityNativeCritical;
+import space.qu4nt.entanglementlib.security.data.InternalNativeBridge;
+import space.qu4nt.entanglementlib.security.data.SDCScopeContext;
+import space.qu4nt.entanglementlib.security.data.SensitiveDataContainer;
+
+import java.lang.foreign.Linker;
+import java.lang.foreign.MemorySegment;
+import java.lang.foreign.SymbolLookup;
+import java.lang.invoke.MethodHandle;
+import java.util.HashMap;
+import java.util.Map;
+
+/// 해당 클래스를 통해 네이티브 함수를 호출하는 경우, 반드시 [NativeLoader]에 의해
+/// 타겟 네이티브 라이브러리가 시스템에 등록(선행)되어 있어야 합니다.
+///
+/// @author Q. T. Felix
+/// @since 1.1.1
+public final class EntLibNativeManager {
+
+ private static final SymbolLookup lookup;
+ private static final Linker linker = Linker.nativeLinker();
+
+ // 동시성 문제 및 런타임 조작을 원천 차단하기 위한 불변 맵(Immutable Map)
+ private static Map methodHandles;
+
+ // 핫 패스(Hot Path) 최적화를 위한 핵심 MethodHandle 정적 캐시
+ @SuppressWarnings({"FieldCanBeLocal", "unused"})
+ private static MethodHandle MH_CALLEE_SECURE_BUFFER_DATA;
+ private static MethodHandle MH_CALLEE_SECURE_BUFFER_LEN;
+ private static MethodHandle MH_CALLEE_SECURE_BUFFER_FREE;
+ private static MethodHandle MH_CALLEE_SECURE_BUFFER_COPY_AND_FREE;
+
+ static {
+ lookup = SymbolLookup.loaderLookup();
+ }
+
+ private EntLibNativeManager() {
+ throw new AssertionError("cannot access");
+ }
+
+ static synchronized void setup() {
+ if (methodHandles != null) return; // 중복 호출 방지
+
+ Map tempMap = new HashMap<>();
+ for (Function function : Function.LOADED)
+ tempMap.put(function, linkExact(function));
+
+ // 맵을 불변 상태로 봉인
+ methodHandles = Map.copyOf(tempMap);
+
+ // 핵심 기능은 O(1)의 Map 탐색 비용조차 없애기 위해 정적 필드에 다이렉트 바인딩
+ MH_CALLEE_SECURE_BUFFER_DATA = methodHandles.get(Function.Callee_Secure_Buffer_Data);
+ MH_CALLEE_SECURE_BUFFER_LEN = methodHandles.get(Function.Callee_Secure_Buffer_Len);
+ MH_CALLEE_SECURE_BUFFER_FREE = methodHandles.get(Function.Callee_Secure_Buffer_Free);
+ MH_CALLEE_SECURE_BUFFER_COPY_AND_FREE = methodHandles.get(Function.SecureBuffer_CopyAndFree);
+ }
+
+ private static MethodHandle linkExact(final @NotNull Function function) {
+ return linker.downcallHandle(
+ lookup.find(function.getFunctionName()).orElseThrow(() ->
+ new ELIBSecurityNativeCritical("네이티브에서 함수 '" + function.getFunctionName() + "'을(를) 찾을 수 없습니다.")),
+ function.getDescriptor()
+ );
+ }
+
+ public static MethodHandle call(final @NotNull Function function) {
+ MethodHandle handle = methodHandles.get(function);
+ if (handle == null)
+ throw new ELIBSecurityNativeCritical("네이티브에서 함수 '" + function.getFunctionName() + "'이(가) 등록되지 않았습니다.");
+ return handle;
+ }
+
+ public static @NotNull SensitiveDataContainer transferNativeBufferBindToContext(
+ final @NotNull SDCScopeContext context,
+ final @NotNull MemorySegment data
+ ) throws ELIBSecurityProcessException {
+ // Rust 측에서 메모리 해제가 완료되었는지 추적하여 Double-Free를 방지하기 위한 플래그
+ boolean isFreedByNative = false;
+
+ try {
+ long len = (long) MH_CALLEE_SECURE_BUFFER_LEN.invokeExact(data);
+
+ // Off-heap 메모리 할당 (OutOfMemoryError 등 예외 발생 가능 구간)
+ SensitiveDataContainer result = context.allocate((int) len);
+
+ // 네이티브에서 직접 복사 및 원본 즉시 소거 (단 1회의 FFI 호출로 압축)
+ long copied = (long) MH_CALLEE_SECURE_BUFFER_COPY_AND_FREE.invokeExact(
+ data,
+ InternalNativeBridge.unwrapMemorySegment(result),
+ len
+ );
+
+ // invokeExact가 예외 없이 통과했다면 Rust의 Box::from_raw에 의해 무조건 소멸
+ isFreedByNative = true;
+
+ // 용량 불일치 등 논리적 오류 검증
+ if (copied != len)
+ throw new ELIBSecurityCritical("네이티브 버퍼 복사 중 크기 불일치 또는 오류가 발생했습니다.");
+
+ return result;
+ } catch (Throwable e) {
+ // context.allocate() 실패 등 Rust로 제어권이 넘어가기 전에 예외가 발생한 경우 메모리 누수 방지
+ if (!isFreedByNative) {
+ try {
+ MH_CALLEE_SECURE_BUFFER_FREE.invokeExact(data);
+ } catch (Throwable ex) {
+ // 원본 예외 유실을 막기 위해 억제된 예외로 병합
+ e.addSuppressed(ex);
+ throw new ELIBSecurityCritical("네이티브 데이터를 소거하는 중 치명적 오류가 발생했습니다!", e);
+ }
+ }
+
+ // 이미 Critical 예외인 경우 그대로 던짐
+ if (e instanceof ELIBSecurityCritical) throw (ELIBSecurityCritical) e;
+ throw new ELIBSecurityProcessException("네이티브 버퍼 획득 및 전송 중 예외가 발생했습니다!", e);
+ }
+ }
+}
\ No newline at end of file
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/Function.java b/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/Function.java
new file mode 100644
index 0000000..430dfa5
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/Function.java
@@ -0,0 +1,266 @@
+package space.qu4nt.entanglementlib.security.entlibnative;
+
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import org.jetbrains.annotations.NotNull;
+
+import java.lang.foreign.FunctionDescriptor;
+import java.lang.foreign.MemoryLayout;
+import java.lang.foreign.ValueLayout;
+import java.util.ArrayList;
+import java.util.List;
+
+/// NOTE: 사용자는 확장되거나 구체화된 entlib-native 바이너리를 제공했을 수 있음. 따라서 이 클래스 형식은 유효
+@Getter
+@AllArgsConstructor(access = AccessLevel.PRIVATE)
+public class Function {
+
+ protected static final List LOADED = new ArrayList<>();
+
+ // 보안 버퍼 엔드포인트
+ // 피호출자 할당
+ public static final Function Callee_Secure_Buffer_Data = Function.of("entlib_secure_buffer_data", ValueLayout.ADDRESS, ValueLayout.ADDRESS);
+ public static final Function Callee_Secure_Buffer_Len = Function.of("entlib_secure_buffer_len", ValueLayout.JAVA_LONG, ValueLayout.ADDRESS);
+ public static final Function Callee_Secure_Buffer_Free = Function.ofVoid("entlib_secure_buffer_free", ValueLayout.ADDRESS); // 보안 작업에서는 공통적으로 사용
+ // 호출자 할당
+ public static final Function Caller_Secure_Buffer_Wipe = Function.ofVoid("entanglement_secure_wipe", ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
+
+ // 데이터 상호 작용을 위한 엔드포인트
+ public static final Function SecureBuffer_Data = Function.of("entlib_secure_buffer_data", ValueLayout.ADDRESS, ValueLayout.ADDRESS);
+ public static final Function SecureBuffer_Len = Function.of("entlib_secure_buffer_len", ValueLayout.JAVA_LONG, ValueLayout.ADDRESS);
+ public static final Function SecureBuffer_Free = Function.ofVoid("entlib_secure_buffer_free", ValueLayout.ADDRESS);
+ public static final Function SecureBuffer_View = Function.of("entlib_secure_buffer_view",
+ MemoryLayout.structLayout(
+ ValueLayout.ADDRESS.withName("data"),
+ ValueLayout.JAVA_LONG.withName("len")
+ ),
+ ValueLayout.ADDRESS
+ );
+ public static final Function SecureBuffer_CopyAndFree = Function.of("entlib_secure_buffer_copy_and_free", ValueLayout.JAVA_LONG,
+ ValueLayout.ADDRESS,
+ ValueLayout.ADDRESS,
+ ValueLayout.JAVA_LONG
+ );
+
+ // Base64 엔드포인트
+ public static final Function Base64_encode = Function.of("entlib_b64_encode_caller_alloc", ValueLayout.JAVA_LONG, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
+ public static final Function Base64_decode = Function.of("entlib_b64_decode_caller_alloc", ValueLayout.JAVA_LONG, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG); // todo; err_flag 파라미터 추가 확인 필요
+
+ // Hash 엔드포인트
+ // SHA2
+ public static final Function SHA2_224_New = Function.of("entlib_sha224_new", ValueLayout.ADDRESS);
+ public static final Function SHA2_224_Update = Function.of("entlib_sha224_update", ValueLayout.JAVA_INT, ValueLayout.ADDRESS, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
+ public static final Function SHA2_224_Finalize = Function.of("entlib_sha224_finalize", ValueLayout.ADDRESS, ValueLayout.ADDRESS);
+ public static final Function SHA2_224_Free = Function.ofVoid("entlib_sha224_free", ValueLayout.ADDRESS);
+
+ public static final Function SHA2_256_New = Function.of("entlib_sha256_new", ValueLayout.ADDRESS);
+ public static final Function SHA2_256_Update = Function.of("entlib_sha256_update", ValueLayout.JAVA_INT, ValueLayout.ADDRESS, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
+ public static final Function SHA2_256_Finalize = Function.of("entlib_sha256_finalize", ValueLayout.ADDRESS, ValueLayout.ADDRESS);
+ public static final Function SHA2_256_Free = Function.ofVoid("entlib_sha256_free", ValueLayout.ADDRESS);
+
+ public static final Function SHA2_384_New = Function.of("entlib_sha384_new", ValueLayout.ADDRESS);
+ public static final Function SHA2_384_Update = Function.of("entlib_sha384_update", ValueLayout.JAVA_INT, ValueLayout.ADDRESS, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
+ public static final Function SHA2_384_Finalize = Function.of("entlib_sha384_finalize", ValueLayout.ADDRESS, ValueLayout.ADDRESS);
+ public static final Function SHA2_384_Free = Function.ofVoid("entlib_sha384_free", ValueLayout.ADDRESS);
+
+ public static final Function SHA2_512_New = Function.of("entlib_sha512_new", ValueLayout.ADDRESS);
+ public static final Function SHA2_512_Update = Function.of("entlib_sha512_update", ValueLayout.JAVA_INT, ValueLayout.ADDRESS, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
+ public static final Function SHA2_512_Finalize = Function.of("entlib_sha512_finalize", ValueLayout.ADDRESS, ValueLayout.ADDRESS);
+ public static final Function SHA2_512_Free = Function.ofVoid("entlib_sha512_free", ValueLayout.ADDRESS);
+
+ // SHA3
+ public static final Function SHA3_224_New = Function.of("entlib_sha3_224_new", ValueLayout.ADDRESS);
+ public static final Function SHA3_224_Update = Function.of("entlib_sha3_224_update", ValueLayout.JAVA_INT, ValueLayout.ADDRESS, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
+ public static final Function SHA3_224_Finalize = Function.of("entlib_sha3_224_finalize", ValueLayout.ADDRESS, ValueLayout.ADDRESS);
+ public static final Function SHA3_224_Free = Function.ofVoid("entlib_sha3_224_free", ValueLayout.ADDRESS);
+
+ public static final Function SHA3_256_New = Function.of("entlib_sha3_256_new", ValueLayout.ADDRESS);
+ public static final Function SHA3_256_Update = Function.of("entlib_sha3_256_update", ValueLayout.JAVA_INT, ValueLayout.ADDRESS, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
+ public static final Function SHA3_256_Finalize = Function.of("entlib_sha3_256_finalize", ValueLayout.ADDRESS, ValueLayout.ADDRESS);
+ public static final Function SHA3_256_Free = Function.ofVoid("entlib_sha3_256_free", ValueLayout.ADDRESS);
+
+ public static final Function SHA3_384_New = Function.of("entlib_sha3_384_new", ValueLayout.ADDRESS);
+ public static final Function SHA3_384_Update = Function.of("entlib_sha3_384_update", ValueLayout.JAVA_INT, ValueLayout.ADDRESS, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
+ public static final Function SHA3_384_Finalize = Function.of("entlib_sha3_384_finalize", ValueLayout.ADDRESS, ValueLayout.ADDRESS);
+ public static final Function SHA3_384_Free = Function.ofVoid("entlib_sha3_384_free", ValueLayout.ADDRESS);
+
+ public static final Function SHA3_512_New = Function.of("entlib_sha3_512_new", ValueLayout.ADDRESS);
+ public static final Function SHA3_512_Update = Function.of("entlib_sha3_512_update", ValueLayout.JAVA_INT, ValueLayout.ADDRESS, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
+ public static final Function SHA3_512_Finalize = Function.of("entlib_sha3_512_finalize", ValueLayout.ADDRESS, ValueLayout.ADDRESS);
+ public static final Function SHA3_512_Free = Function.ofVoid("entlib_sha3_512_free", ValueLayout.ADDRESS);
+
+ public static final Function SHA3_SHAKE128_New = Function.of("entlib_sha3_shake128_new", ValueLayout.ADDRESS);
+ public static final Function SHA3_SHAKE128_Update = Function.of("entlib_sha3_shake128_update", ValueLayout.JAVA_INT, ValueLayout.ADDRESS, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
+ public static final Function SHA3_SHAKE128_Finalize = Function.of("entlib_sha3_shake128_finalize", ValueLayout.ADDRESS, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
+ public static final Function SHA3_SHAKE128_Free = Function.ofVoid("entlib_sha3_shake128_free", ValueLayout.ADDRESS);
+
+ public static final Function SHA3_SHAKE256_New = Function.of("entlib_sha3_shake256_new", ValueLayout.ADDRESS);
+ public static final Function SHA3_SHAKE256_Update = Function.of("entlib_sha3_shake256_update", ValueLayout.JAVA_INT, ValueLayout.ADDRESS, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
+ public static final Function SHA3_SHAKE256_Finalize = Function.of("entlib_sha3_shake256_finalize", ValueLayout.ADDRESS, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
+ public static final Function SHA3_SHAKE256_Free = Function.ofVoid("entlib_sha3_shake256_free", ValueLayout.ADDRESS);
+
+ // RNG 엔드포인트
+ public static final Function RNG_HW_Generate = Function.of("entlib_rng_hw_generate", ValueLayout.ADDRESS, ValueLayout.JAVA_LONG, ValueLayout.ADDRESS);
+ public static final Function RNG_HW_Next_Generate = Function.of("entlib_rng_hw_next_generate", ValueLayout.JAVA_BYTE, ValueLayout.ADDRESS);
+ public static final Function RNG_ANU_Generate = Function.of("entlib_rng_anu_generate", ValueLayout.ADDRESS, ValueLayout.JAVA_LONG, ValueLayout.ADDRESS);
+ public static final Function RNG_MIXED_New_With_Strategy = Function.of("entlib_rng_mixed_new_with_strategy", ValueLayout.ADDRESS, ValueLayout.JAVA_BYTE, ValueLayout.ADDRESS);
+ public static final Function RNG_MIXED_New = Function.of("entlib_rng_mixed_new", ValueLayout.ADDRESS, ValueLayout.ADDRESS);
+ public static final Function RNG_MIXED_Generate = Function.of("entlib_rng_mixed_generate", ValueLayout.ADDRESS, ValueLayout.ADDRESS, ValueLayout.JAVA_LONG, ValueLayout.ADDRESS);
+ public static final Function RNG_MIXED_Free = Function.ofVoid("entlib_rng_mixed_free", ValueLayout.ADDRESS);
+
+ // ChaCha20 엔드포인트
+ public static final Function ChaCha20_Process = Function.of("process_chacha20_ffi", ValueLayout.ADDRESS,
+ ValueLayout.ADDRESS,
+ ValueLayout.JAVA_LONG,
+ ValueLayout.ADDRESS,
+ ValueLayout.JAVA_LONG,
+ ValueLayout.JAVA_INT,
+ ValueLayout.ADDRESS,
+ ValueLayout.JAVA_LONG);
+ public static final Function ChaCha20_Poly1305_MAC_Generate = Function.of("generate_poly1305_ffi", ValueLayout.ADDRESS,
+ ValueLayout.ADDRESS,
+ ValueLayout.JAVA_LONG,
+ ValueLayout.ADDRESS,
+ ValueLayout.JAVA_LONG);
+ public static final Function ChaCha20_Poly1305_Encrypt = Function.of("chacha20_poly1305_encrypt_ffi", ValueLayout.ADDRESS,
+ ValueLayout.ADDRESS,
+ ValueLayout.JAVA_LONG,
+ ValueLayout.ADDRESS,
+ ValueLayout.JAVA_LONG,
+ ValueLayout.ADDRESS,
+ ValueLayout.JAVA_LONG,
+ ValueLayout.ADDRESS,
+ ValueLayout.JAVA_LONG);
+ public static final Function ChaCha20_Poly1305_Decrypt = Function.of("chacha20_poly1305_decrypt_ffi", ValueLayout.ADDRESS,
+ ValueLayout.ADDRESS,
+ ValueLayout.JAVA_LONG,
+ ValueLayout.ADDRESS,
+ ValueLayout.JAVA_LONG,
+ ValueLayout.ADDRESS,
+ ValueLayout.JAVA_LONG,
+ ValueLayout.ADDRESS,
+ ValueLayout.JAVA_LONG);
+
+ private final @NotNull String functionName;
+ private final FunctionDescriptor descriptor;
+
+ public static Function of(final @NotNull String functionName, MemoryLayout returnType, MemoryLayout... args) {
+ Function r = new Function(functionName, FunctionDescriptor.of(returnType, args));
+ LOADED.add(r);
+ return r;
+ }
+
+ public static Function ofVoid(final @NotNull String functionName, MemoryLayout... args) {
+ Function r = new Function(functionName, FunctionDescriptor.ofVoid(args));
+ LOADED.add(r);
+ return r;
+ }
+
+ public static Function[] chain(Function[] source, Function[]... additional) {
+ int size = source.length;
+ for (Function[] specs : additional) {
+ size += specs.length;
+ }
+
+ Function[] result = new Function[size];
+
+ System.arraycopy(source, 0, result, 0, source.length);
+ int currentPosition = source.length;
+
+ for (Function[] specs : additional) {
+ System.arraycopy(specs, 0, result, currentPosition, specs.length);
+ currentPosition += specs.length;
+ }
+
+ return result;
+ }
+
+ public static Function[] withCallerSecureBuffer() {
+ return new Function[]{
+ Callee_Secure_Buffer_Data,
+ Callee_Secure_Buffer_Len,
+ Callee_Secure_Buffer_Free,
+ Caller_Secure_Buffer_Wipe
+ };
+ }
+
+ public static Function[] withCalleeSecureBuffer() {
+ return new Function[]{
+ SecureBuffer_Data,
+ SecureBuffer_Len,
+ SecureBuffer_Free,
+ SecureBuffer_View,
+ SecureBuffer_CopyAndFree
+ };
+ }
+
+ public static Function[] withRNG() {
+ return new Function[]{
+ RNG_HW_Generate,
+ RNG_HW_Next_Generate,
+ RNG_ANU_Generate,
+ RNG_MIXED_New_With_Strategy,
+ RNG_MIXED_New,
+ RNG_MIXED_Generate,
+ RNG_MIXED_Free
+ };
+ }
+
+ public static Function[] withHash(boolean sha2) {
+ if (sha2)
+ return new Function[]{
+ SHA2_224_New,
+ SHA2_224_Update,
+ SHA2_224_Finalize,
+ SHA2_224_Free,
+ SHA2_256_New,
+ SHA2_256_Update,
+ SHA2_256_Finalize,
+ SHA2_256_Free,
+ SHA2_384_New,
+ SHA2_384_Update,
+ SHA2_384_Finalize,
+ SHA2_384_Free,
+ SHA2_512_New,
+ SHA2_512_Update,
+ SHA2_512_Finalize,
+ SHA2_512_Free
+ };
+ return new Function[] {
+ SHA3_224_New,
+ SHA3_224_Update,
+ SHA3_224_Finalize,
+ SHA3_224_Free,
+ SHA3_256_New,
+ SHA3_256_Update,
+ SHA3_256_Finalize,
+ SHA3_256_Free,
+ SHA3_384_New,
+ SHA3_384_Update,
+ SHA3_384_Finalize,
+ SHA3_384_Free,
+ SHA3_512_New,
+ SHA3_512_Update,
+ SHA3_512_Finalize,
+ SHA3_512_Free,
+ SHA3_SHAKE128_New,
+ SHA3_SHAKE128_Update,
+ SHA3_SHAKE128_Finalize,
+ SHA3_SHAKE128_Free,
+ SHA3_SHAKE256_New,
+ SHA3_SHAKE256_Update,
+ SHA3_SHAKE256_Finalize,
+ SHA3_SHAKE256_Free
+ };
+ }
+
+ public static Function[] withChaCha20() {
+ return new Function[]{
+ ChaCha20_Process,
+ ChaCha20_Poly1305_MAC_Generate,
+ ChaCha20_Poly1305_Encrypt,
+ ChaCha20_Poly1305_Decrypt
+ };
+ }
+}
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/NativeLoader.java b/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/NativeLoader.java
new file mode 100644
index 0000000..c30d2fa
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/NativeLoader.java
@@ -0,0 +1,142 @@
+package space.qu4nt.entanglementlib.security.entlibnative;
+
+import lombok.extern.slf4j.Slf4j;
+import org.jetbrains.annotations.NotNull;
+import space.qu4nt.entanglementlib.core.exception.security.checked.ELIBSecurityIOException;
+import space.qu4nt.entanglementlib.core.exception.security.critical.ELIBSecurityNativeCritical;
+import space.qu4nt.entanglementlib.security.EntanglementLibSecurityConfig;
+
+import java.io.File;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.file.FileSystems;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.nio.file.attribute.PosixFilePermission;
+import java.nio.file.attribute.PosixFilePermissions;
+import java.util.Set;
+
+// todo 이 클래스 호출 시점에 국제화 파일 로드돼잇을거임
+@Slf4j
+public final class NativeLoader {
+
+ private static volatile boolean loaded = false;
+
+ private NativeLoader() {
+ throw new UnsupportedOperationException("cannot access");
+ }
+
+ private static synchronized void loadSuccess() {
+ loaded = true;
+ EntLibNativeManager.setup();
+ }
+
+ public static synchronized void loadNativeLibrary(final @NotNull EntanglementLibSecurityConfig config) {
+ if (loaded) return;
+
+ try {
+ NativePlatform os = NativePlatform.detectOs();
+ if (os == NativePlatform.UNKNOWN)
+ throw new ELIBSecurityNativeCritical("지원하지 않는 운영체제입니다!");
+
+ String fileName = os.buildFileName(config.getNativeContext().getNativeFilename());
+
+ // 사용자 할당 시 외부 절대 경로 탐색
+ final String dirName = config.getNativeContext().getNativeDirName();
+ Path externalPath = Path.of(dirName);
+ Path exactExternalFile = externalPath.resolve(fileName);
+
+ log.info(exactExternalFile.toString());
+
+ // 사용자가 파일명까지 포함한 절대 경로를 입력했거나, 디렉터리 경로를 입력한 경우 모두 처리
+ if (Files.exists(externalPath) && !Files.isDirectory(externalPath)) {
+ System.load(externalPath.toAbsolutePath().toString());
+ loadSuccess();
+ return;
+ } else if (Files.exists(exactExternalFile)) {
+ System.load(exactExternalFile.toAbsolutePath().toString());
+ loadSuccess();
+ return;
+ }
+
+ // jar 내부 자원 로드
+ String architecture = NativePlatform.detectArchitecture();
+ String resourcePath = dirName + "/" + os.name().toLowerCase() + "/" + architecture + "/" + fileName;
+
+ extractAndLoadFromJar(resourcePath, fileName);
+ loadSuccess();
+ } catch (UnsatisfiedLinkError e) {
+ throw new ELIBSecurityNativeCritical(
+ "파일명이 절대 경로명이 아니거나, " +
+ "네이티브 라이브러리가 VM과 정적으로 연결되지 않거나, " +
+ "호스트 시스템에서 라이브러리를 네이티브 라이브러리 이미지에 매핑할 수 없습니다!");
+ } catch (IllegalCallerException e) {
+ throw new ELIBSecurityNativeCritical("현재 모듈은 네이티브 액세스 권한이 없습니다!");
+ } catch (ELIBSecurityIOException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ private static void extractAndLoadFromJar(String resourcePath, String fileName) throws ELIBSecurityIOException {
+ try (InputStream is = NativeLoader.class.getResourceAsStream(resourcePath)) {
+ if (is == null)
+ throw new ELIBSecurityNativeCritical("jar 내부 '" + resourcePath + "' 경로에서 네이티브 라이브러리를 찾을 수 없습니다!");
+
+ Path tempFile = createSecureTempFile(fileName);
+ tempFile.toFile().deleteOnExit();
+
+ Files.copy(is, tempFile, StandardCopyOption.REPLACE_EXISTING);
+ System.load(tempFile.toAbsolutePath().toString());
+
+ } catch (IOException e) {
+ throw new ELIBSecurityIOException("임시 파일 생성 및 복사(덮어쓰기)에 실패했습니다!", e);
+ }
+ }
+
+ private static Path createSecureTempFile(String fileName) throws IOException {
+ int dotIndex = fileName.lastIndexOf('.');
+ String prefix = fileName.substring(0, dotIndex) + "-";
+ String suffix = fileName.substring(dotIndex);
+
+ boolean isPosix = FileSystems.getDefault().supportedFileAttributeViews().contains("posix");
+
+ if (isPosix) {
+ // POSIX 호환 시스템 (Linux, macOS)
+ Set perms = PosixFilePermissions.fromString("rwx------");
+ return Files.createTempFile(prefix, suffix, PosixFilePermissions.asFileAttribute(perms));
+ } else {
+ // Windows 등 non-POSIX 시스템
+ Path tempPath = Files.createTempFile(prefix, suffix);
+ File tempFile = tempPath.toFile();
+
+ // 실행 권한 설정 (실패 시 즉시 중단)
+ if (!tempFile.setExecutable(true, true)) {
+ tryDelete(tempPath);
+ throw new IOException("임시 파일의 실행 권한(Owner Only)을 설정할 수 없습니다: " + tempPath);
+ }
+
+ // 읽기 권한 설정
+ if (!tempFile.setReadable(true, true)) {
+ tryDelete(tempPath);
+ throw new IOException("임시 파일의 읽기 권한(Owner Only)을 설정할 수 없습니다: " + tempPath);
+ }
+
+ // 쓰기 권한 설정
+ if (!tempFile.setWritable(true, true)) {
+ tryDelete(tempPath);
+ throw new IOException("임시 파일의 쓰기 권한(Owner Only)을 설정할 수 없습니다: " + tempPath);
+ }
+
+ return tempPath;
+ }
+ }
+
+ private static void tryDelete(Path path) {
+ try {
+ Files.deleteIfExists(path);
+ } catch (IOException e) {
+ log.error("임시 파일 제거 중 예외가 발생했습니다!", e);
+ }
+ }
+}
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/NativePlatform.java b/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/NativePlatform.java
new file mode 100644
index 0000000..acd33e5
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/NativePlatform.java
@@ -0,0 +1,38 @@
+package space.qu4nt.entanglementlib.security.entlibnative;
+
+import java.util.Locale;
+
+public enum NativePlatform {
+
+ WINDOWS("", ".dll"),
+ LINUX("lib", ".so"),
+ MACOS("lib", ".dylib"),
+ UNKNOWN("", "");
+
+ private final String prefix;
+ private final String extension;
+
+ NativePlatform(String prefix, String extension) {
+ this.prefix = prefix;
+ this.extension = extension;
+ }
+
+ public static NativePlatform detectOs() {
+ String osName = System.getProperty("os.name").toLowerCase(Locale.ENGLISH);
+ if (osName.contains("win")) return WINDOWS;
+ if (osName.contains("mac") || osName.contains("darwin")) return MACOS;
+ if (osName.contains("nix") || osName.contains("nux") || osName.contains("aix")) return LINUX;
+ return UNKNOWN;
+ }
+
+ public static String detectArchitecture() {
+ String arch = System.getProperty("os.arch").toLowerCase(Locale.ENGLISH);
+ if (arch.contains("amd64") || arch.contains("x86_64")) return "x86_64";
+ if (arch.contains("aarch64") || arch.contains("arm64")) return "aarch64";
+ return arch; // 기타 아키텍처 (필요시 확장)
+ }
+
+ public String buildFileName(String baseName) {
+ return this.prefix + baseName + this.extension;
+ }
+}
\ No newline at end of file
diff --git a/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/NativeSpecContext.java b/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/NativeSpecContext.java
new file mode 100644
index 0000000..8765f1a
--- /dev/null
+++ b/security/src/main/java/space/qu4nt/entanglementlib/security/entlibnative/NativeSpecContext.java
@@ -0,0 +1,96 @@
+package space.qu4nt.entanglementlib.security.entlibnative;
+
+import lombok.Getter;
+import lombok.Setter;
+
+import java.util.Set;
+
+import static space.qu4nt.entanglementlib.security.entlibnative.Function.*;
+
+@Getter
+@Setter
+public class NativeSpecContext {
+
+ private String nativeDirName;
+ private String nativeFilename;
+ private Set functions;
+
+ public NativeSpecContext(String nativeDirName, String nativeFilename, Set functions) {
+ this.nativeDirName = nativeDirName;
+ this.nativeFilename = nativeFilename;
+ this.functions = functions;
+ }
+
+ public NativeSpecContext(String nativeDirName, String nativeFilename, Function... functions) {
+ this.nativeDirName = nativeDirName;
+ this.nativeFilename = nativeFilename;
+ this.functions = Set.of(functions);
+ }
+
+ public static NativeSpecContext defaults() {
+ return new NativeSpecContext("/native", "entlib_native_ffi", Set.of(
+ Callee_Secure_Buffer_Data,
+ Callee_Secure_Buffer_Len,
+ Callee_Secure_Buffer_Free,
+ Caller_Secure_Buffer_Wipe,
+ SecureBuffer_Data,
+ SecureBuffer_Len,
+ SecureBuffer_Free,
+ SecureBuffer_View,
+ SecureBuffer_CopyAndFree,
+ Base64_encode,
+ Base64_decode,
+ SHA2_224_New,
+ SHA2_224_Update,
+ SHA2_224_Finalize,
+ SHA2_224_Free,
+ SHA2_256_New,
+ SHA2_256_Update,
+ SHA2_256_Finalize,
+ SHA2_256_Free,
+ SHA2_384_New,
+ SHA2_384_Update,
+ SHA2_384_Finalize,
+ SHA2_384_Free,
+ SHA2_512_New,
+ SHA2_512_Update,
+ SHA2_512_Finalize,
+ SHA2_512_Free,
+ SHA3_224_New,
+ SHA3_224_Update,
+ SHA3_224_Finalize,
+ SHA3_224_Free,
+ SHA3_256_New,
+ SHA3_256_Update,
+ SHA3_256_Finalize,
+ SHA3_256_Free,
+ SHA3_384_New,
+ SHA3_384_Update,
+ SHA3_384_Finalize,
+ SHA3_384_Free,
+ SHA3_512_New,
+ SHA3_512_Update,
+ SHA3_512_Finalize,
+ SHA3_512_Free,
+ SHA3_SHAKE128_New,
+ SHA3_SHAKE128_Update,
+ SHA3_SHAKE128_Finalize,
+ SHA3_SHAKE128_Free,
+ SHA3_SHAKE256_New,
+ SHA3_SHAKE256_Update,
+ SHA3_SHAKE256_Finalize,
+ SHA3_SHAKE256_Free,
+ RNG_HW_Generate,
+ RNG_HW_Next_Generate,
+ RNG_ANU_Generate,
+ RNG_MIXED_New_With_Strategy,
+ RNG_MIXED_New,
+ RNG_MIXED_Generate,
+ RNG_MIXED_Free,
+ ChaCha20_Process,
+ ChaCha20_Poly1305_MAC_Generate,
+ ChaCha20_Poly1305_Encrypt,
+ ChaCha20_Poly1305_Decrypt
+ ));
+ }
+}
diff --git a/src/main/resources/logback.xml b/security/src/main/resources/logback.xml
similarity index 100%
rename from src/main/resources/logback.xml
rename to security/src/main/resources/logback.xml
diff --git a/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/Base64Test.java b/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/Base64Test.java
new file mode 100644
index 0000000..d37e76c
--- /dev/null
+++ b/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/Base64Test.java
@@ -0,0 +1,60 @@
+package space.qu4nt.entanglementlib.security.crypto;
+
+import lombok.extern.slf4j.Slf4j;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import space.qu4nt.entanglementlib.security.EntanglementLibSecurityConfig;
+import space.qu4nt.entanglementlib.security.EntanglementLibSecurityFacade;
+import space.qu4nt.entanglementlib.security.crypto.encode.Base64;
+import space.qu4nt.entanglementlib.security.data.HeuristicArenaFactory;
+import space.qu4nt.entanglementlib.security.data.InternalNativeBridge;
+import space.qu4nt.entanglementlib.security.data.SDCScopeContext;
+import space.qu4nt.entanglementlib.security.data.SensitiveDataContainer;
+import space.qu4nt.entanglementlib.security.entlibnative.Function;
+import space.qu4nt.entanglementlib.security.entlibnative.NativeSpecContext;
+
+import java.lang.foreign.MemorySegment;
+import java.lang.foreign.ValueLayout;
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+
+@Slf4j
+class Base64Test {
+
+ @Test
+ @DisplayName("Base64 En/Decode")
+ void test() {
+ EntanglementLibSecurityFacade.initialize(
+ EntanglementLibSecurityConfig.create(
+ new NativeSpecContext(System.getenv("ENTLIB_NATIVE_BIN"), "entlib_native_ffi",
+ Function.Callee_Secure_Buffer_Data,
+ Function.Callee_Secure_Buffer_Len,
+ Function.Callee_Secure_Buffer_Free,
+ Function.Caller_Secure_Buffer_Wipe,
+ Function.Base64_encode,
+ Function.Base64_decode),
+ HeuristicArenaFactory.ArenaMode.CONFINED)
+ );
+
+ final byte[] plaintext = "Hello, World!".getBytes(StandardCharsets.UTF_8);
+ try (SDCScopeContext scope = new SDCScopeContext()) {
+ SensitiveDataContainer input = scope.allocate(plaintext, true);
+ SensitiveDataContainer result = Base64.encode(input);
+ final MemorySegment rms = InternalNativeBridge.unwrapMemorySegment(result);
+
+ byte[] actualCipherBytes = rms.toArray(ValueLayout.JAVA_BYTE); // 프로덕션에서 사용 권장 X
+ byte[] newACBytes = new byte[actualCipherBytes.length];
+ System.arraycopy(actualCipherBytes, 0, newACBytes, 0, actualCipherBytes.length);
+ log.info("Encoded: {}", new String(newACBytes, StandardCharsets.UTF_8));
+
+ SensitiveDataContainer decoded = Base64.decode(result);
+ MemorySegment decResultOpt = InternalNativeBridge.unwrapMemorySegment(decoded);
+ byte[] actualDecBytes = decResultOpt.toArray(ValueLayout.JAVA_BYTE); // 프로덕션에서 사용 권장 X
+ byte[] newADCBytes = new byte[actualDecBytes.length];
+ System.arraycopy(actualDecBytes, 0, newADCBytes, 0, actualDecBytes.length);
+ log.info("Decoded: {}", new String(newADCBytes, StandardCharsets.UTF_8));
+ }
+ }
+}
\ No newline at end of file
diff --git a/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/ChaCha20Test.java b/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/ChaCha20Test.java
new file mode 100644
index 0000000..518dfcc
--- /dev/null
+++ b/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/ChaCha20Test.java
@@ -0,0 +1,123 @@
+package space.qu4nt.entanglementlib.security.crypto;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import space.qu4nt.entanglementlib.core.util.wrapper.Hex;
+import space.qu4nt.entanglementlib.security.EntanglementLibSecurityConfig;
+import space.qu4nt.entanglementlib.security.EntanglementLibSecurityFacade;
+import space.qu4nt.entanglementlib.security.data.HeuristicArenaFactory;
+import space.qu4nt.entanglementlib.security.data.InternalNativeBridge;
+import space.qu4nt.entanglementlib.security.data.SDCScopeContext;
+import space.qu4nt.entanglementlib.security.data.SensitiveDataContainer;
+import space.qu4nt.entanglementlib.security.entlibnative.Function;
+import space.qu4nt.entanglementlib.security.entlibnative.NativeSpecContext;
+
+import java.lang.foreign.MemorySegment;
+import java.lang.foreign.ValueLayout;
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class ChaCha20Test {
+
+ @BeforeAll
+ static void setUp() {
+ // 테스트 클래스 로드 시 1회만 네이티브 라이브러리를 초기화하여 성능 최적화
+ EntanglementLibSecurityFacade.initialize(
+ EntanglementLibSecurityConfig.create(
+ new NativeSpecContext(System.getenv("ENTLIB_NATIVE_BIN"), "entlib_native_ffi",
+ Function.Callee_Secure_Buffer_Data,
+ Function.Callee_Secure_Buffer_Len,
+ Function.Callee_Secure_Buffer_Free,
+ Function.Caller_Secure_Buffer_Wipe,
+ Function.ChaCha20_Poly1305_Encrypt,
+ Function.ChaCha20_Poly1305_Decrypt),
+ HeuristicArenaFactory.ArenaMode.CONFINED)
+ );
+ }
+
+ @Test
+ @DisplayName("ChaCha20 known answer test & 메모리 안전성 검증")
+ void chacha20Test() throws Throwable {
+ // 테스트 벡터
+ final String inputText = "Ladies and Gentlemen of the class of '99: If I could offer you only one tip for the future, sunscreen would be it.";
+ // 기댓값
+ final byte[] expected = new byte[]{
+ (byte) 0xd3, 0x1a, (byte) 0x8d, 0x34, 0x64, (byte) 0x8e, 0x60, (byte) 0xdb, 0x7b, (byte) 0x86,
+ (byte) 0xaf, (byte) 0xbc, 0x53, (byte) 0xef, 0x7e, (byte) 0xc2, (byte) 0xa4, (byte) 0xad,
+ (byte) 0xed, 0x51, 0x29, 0x6e, 0x08, (byte) 0xfe, (byte) 0xa9, (byte) 0xe2, (byte) 0xb5,
+ (byte) 0xa7, 0x36, (byte) 0xee, 0x62, (byte) 0xd6, 0x3d, (byte) 0xbe, (byte) 0xa4, 0x5e,
+ (byte) 0x8c, (byte) 0xa9, 0x67, 0x12, (byte) 0x82, (byte) 0xfa, (byte) 0xfb, 0x69, (byte) 0xda,
+ (byte) 0x92, 0x72, (byte) 0x8b, 0x1a, 0x71, (byte) 0xde, 0x0a, (byte) 0x9e, 0x06, 0x0b, 0x29,
+ 0x05, (byte) 0xd6, (byte) 0xa5, (byte) 0xb6, 0x7e, (byte) 0xcd, 0x3b, 0x36, (byte) 0x92,
+ (byte) 0xdd, (byte) 0xbd, 0x7f, 0x2d, 0x77, (byte) 0x8b, (byte) 0x8c, (byte) 0x98, 0x03,
+ (byte) 0xae, (byte) 0xe3, 0x28, 0x09, 0x1b, 0x58, (byte) 0xfa, (byte) 0xb3, 0x24, (byte) 0xe4,
+ (byte) 0xfa, (byte) 0xd6, 0x75, (byte) 0x94, 0x55, (byte) 0x85, (byte) 0x80, (byte) 0x8b, 0x48,
+ 0x31, (byte) 0xd7, (byte) 0xbc, 0x3f, (byte) 0xf4, (byte) 0xde, (byte) 0xf0, (byte) 0x8e, 0x4b,
+ 0x7a, (byte) 0x9d, (byte) 0xe5, 0x76, (byte) 0xd2, 0x65, (byte) 0x86, (byte) 0xce, (byte) 0xc6,
+ 0x4b, 0x61, 0x16
+ };
+ final byte[] expectedTag = new byte[]{
+ 0x1a, (byte) 0xe1, 0x0b, 0x59, 0x4f, 0x09, (byte) 0xe2, 0x6a, 0x7e, (byte) 0x90, 0x2e,
+ (byte) 0xcb, (byte) 0xd0, 0x60, 0x06, (byte) 0x91
+ };
+
+ byte[] inputBytes = inputText.getBytes(StandardCharsets.UTF_8);
+
+ MemorySegment resultSegmentAlias;
+
+ // 보안 스코프 내에서 암호화 연산 수행
+ try (SDCScopeContext context = new SDCScopeContext()) {
+ SensitiveDataContainer inputData = context.allocate(inputBytes, true);
+ SensitiveDataContainer key = context.allocate(new byte[]{
+ (byte) 0x80, (byte) 0x81, (byte) 0x82, (byte) 0x83, (byte) 0x84, (byte) 0x85, (byte) 0x86, (byte) 0x87,
+ (byte) 0x88, (byte) 0x89, (byte) 0x8a, (byte) 0x8b, (byte) 0x8c, (byte) 0x8d, (byte) 0x8e, (byte) 0x8f,
+ (byte) 0x90, (byte) 0x91, (byte) 0x92, (byte) 0x93, (byte) 0x94, (byte) 0x95, (byte) 0x96, (byte) 0x97,
+ (byte) 0x98, (byte) 0x99, (byte) 0x9a, (byte) 0x9b, (byte) 0x9c, (byte) 0x9d, (byte) 0x9e, (byte) 0x9f
+ }, true);
+ SensitiveDataContainer nonce = context.allocate(new byte[]{
+ 0x07, 0x00, 0x00, 0x00, 0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47
+ }, true);
+ SensitiveDataContainer aad = context.allocate(new byte[]{
+ 0x50, 0x51, 0x52, 0x53, (byte) 0xc0, (byte) 0xc1, (byte) 0xc2, (byte) 0xc3, (byte) 0xc4, (byte) 0xc5, (byte) 0xc6, (byte) 0xc7
+ }, true);
+ SensitiveDataContainer result = ChaCha20.encrypt(context, key, nonce, aad, inputData);
+
+ assertNotNull(result, "연산 결과는 null일 수 없습니다.");
+ resultSegmentAlias = InternalNativeBridge.unwrapMemorySegment(result);
+
+ // [검증 A] 길이 검증
+ assertEquals(expected.length + 16, resultSegmentAlias.byteSize(),
+ "암호문 길이가 불일치합니다.");
+
+ // [검증 B] 무결성 검증 (correctness check)
+ byte[] actualCipherBytes = resultSegmentAlias.toArray(ValueLayout.JAVA_BYTE); // 프로덕션에서 사용 권장 X
+ assertEquals(actualCipherBytes.length, expected.length + 16, "암호문 길이가 불일치합니다.");
+ byte[] newACBytes = new byte[actualCipherBytes.length - 16];
+ System.arraycopy(actualCipherBytes, 0, newACBytes, 0, actualCipherBytes.length - 16);
+ assertEquals(Hex.toHexString(expected), Hex.toHexString(newACBytes),
+ "암호문이 불일치합니다.");
+ newACBytes = new byte[16];
+ System.arraycopy(actualCipherBytes, actualCipherBytes.length - 16, newACBytes, 0, 16);
+ assertEquals(Hex.toHexString(expectedTag), Hex.toHexString(newACBytes),
+ "MAC 태그가 불일치합니다.");
+
+ //
+ // 복호화
+ //
+ SensitiveDataContainer decryptResult = ChaCha20.decrypt(context, key, nonce, aad, result);
+ MemorySegment decResultOpt = InternalNativeBridge.unwrapMemorySegment(decryptResult);
+ assertNotEquals(MemorySegment.NULL, decResultOpt, "네이티브 측 복호화 결과가 null입니다.");
+ assertNotEquals(0, decResultOpt.address(), "네이티브 측 복호화 결과가 유효하지 않습니다.");
+ byte[] actualDecBytes = decResultOpt.toArray(ValueLayout.JAVA_BYTE); // 프로덕션에서 사용 권장 X
+ byte[] newADCBytes = new byte[actualDecBytes.length];
+ System.arraycopy(actualDecBytes, 0, newADCBytes, 0, actualDecBytes.length);
+ assertEquals(Hex.toHexString(inputBytes), Hex.toHexString(newADCBytes), "복호화 결과가 불일치합니다.");
+ } // 스코프 벗어남 -> 컨텍스트 내부 모든 데이터 소거 요청 -> Rust에서 소거
+
+ assertThrows(IllegalStateException.class, () ->
+ resultSegmentAlias.get(ValueLayout.JAVA_BYTE, 0),
+ "스코프가 종료된 이후 메모리 세그먼트에 접근할 경우 반드시 예외가 발생하여 잔류 데이터 유출을 막아야 합니다.");
+ }
+}
\ No newline at end of file
diff --git a/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/RNGTest.java b/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/RNGTest.java
new file mode 100644
index 0000000..22b3476
--- /dev/null
+++ b/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/RNGTest.java
@@ -0,0 +1,99 @@
+package space.qu4nt.entanglementlib.security.crypto;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Disabled;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import space.qu4nt.entanglementlib.core.exception.security.checked.ELIBSecurityProcessException;
+import space.qu4nt.entanglementlib.core.exception.security.critical.ELIBSecurityNativeCritical;
+import space.qu4nt.entanglementlib.security.EntanglementLibSecurityConfig;
+import space.qu4nt.entanglementlib.security.EntanglementLibSecurityFacade;
+import space.qu4nt.entanglementlib.security.crypto.rng.RNG;
+import space.qu4nt.entanglementlib.security.data.HeuristicArenaFactory;
+import space.qu4nt.entanglementlib.security.data.InternalNativeBridge;
+import space.qu4nt.entanglementlib.security.data.SDCScopeContext;
+import space.qu4nt.entanglementlib.security.data.SensitiveDataContainer;
+import space.qu4nt.entanglementlib.security.entlibnative.Function;
+import space.qu4nt.entanglementlib.security.entlibnative.NativeSpecContext;
+
+import java.lang.foreign.MemorySegment;
+import java.lang.foreign.ValueLayout;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class RNGTest {
+
+ @BeforeAll
+ static void setUp() {
+ // 테스트 클래스 로드 시 1회만 네이티브 라이브러리를 초기화하여 성능 최적화
+ EntanglementLibSecurityFacade.initialize(
+ EntanglementLibSecurityConfig.create(
+ new NativeSpecContext(System.getenv("ENTLIB_NATIVE_BIN"), "entlib_native_ffi",
+ Function.chain(
+ Function.withCalleeSecureBuffer(),
+ Function.withCallerSecureBuffer(),
+ Function.withRNG())),
+ HeuristicArenaFactory.ArenaMode.CONFINED)
+ );
+ }
+
+ @Test
+ @DisplayName("로컬 하드웨어(local hardware) 기반 혼합 난수 생성 및 소거(zeroize) 검증")
+ void hardwareRngLifecycleAndZeroizeTest() throws ELIBSecurityProcessException {
+ final long PQC_KEY_LENGTH = 32; // 양자-내성 암호화(post-quantum cryptography) 키 길이를 가정한 32바이트
+ MemorySegment capturedSegment;
+
+ // 보안 스코프(secure scope) 컨텍스트 생성 및 난수 할당
+ try (SDCScopeContext scope = new SDCScopeContext()) {
+ SensitiveDataContainer sdc = RNG.generateRNG(RNG.LOCAL_HARDWARE, scope, PQC_KEY_LENGTH);
+
+ assertNotNull(sdc, "생성된 민감 데이터 컨테이너(sensitive data container)는 null이 아니어야 합니다.");
+ capturedSegment = InternalNativeBridge.unwrapMemorySegment(sdc);
+
+ // arena 및 메모리 세그먼트 유효성 검증
+ assertTrue(InternalNativeBridge.unwrapArena(sdc).scope().isAlive(), "스코프(scope) 내부에서는 Arena가 활성화 상태여야 합니다.");
+ assertEquals(PQC_KEY_LENGTH, capturedSegment.byteSize(), "생성된 난수의 크기가 요청한 길이와 일치해야 합니다.");
+
+ // 엔트로피 데이터 존재 여부 검증 (모두 0인지 확인)
+ boolean hasNonZero = false;
+ for (long i = 0; i < PQC_KEY_LENGTH; i++) {
+ if (capturedSegment.get(ValueLayout.JAVA_BYTE, i) != 0) {
+ hasNonZero = true;
+ break;
+ }
+ }
+ assertTrue(hasNonZero, "초기화된 난수 버퍼가 모두 0일 수는 없습니다. (엔트로피 부족 의심)");
+ } // try-with-resources 종료 시 scope.close() 호출 -> SDC 소거(zeroize) 자동 수행
+
+ // 스코프 종료 후 자원 파기 검증
+ // SDCScopeContext가 닫히면서 소속된 모든 컨테이너의 아레나가 닫히고 네이티브 포인터가 무효화되어야 함
+ assertFalse(capturedSegment.scope().isAlive(), "컨텍스트 종료 후에는 Arena가 반드시 닫혀야 합니다.");
+
+ // 메모리 영역 강제 접근 시 예외 발생 검증
+ assertThrows(IllegalStateException.class, () -> {
+ capturedSegment.get(ValueLayout.JAVA_BYTE, 0);
+ }, "해제 및 소거(zeroize)된 네이티브 메모리에 접근 시도 시 예외가 발생해야 합니다.");
+ }
+
+ @Test
+ @Disabled
+ @DisplayName("양자 네트워크(quantum network) 기반 혼합 난수 생성 에러 핸들링 검증")
+ void quantumNetworkRngErrorHandlingTest() throws ELIBSecurityProcessException {
+ // 양자 네트워크 특성상 외부 통신 환경에 따라 실패할 수 있어서 생성 성공 여부 또는
+ // 네트워크 타임아웃/파싱 에러 시 ELIBSecurityNativeCritical 예외가 올바르게 전파되는지 검증해야됌
+ try (SDCScopeContext scope = new SDCScopeContext()) {
+ try {
+ SensitiveDataContainer sdc = RNG.generateRNG(RNG.QUANTUM_NETWORK, scope, 64);
+ assertNotNull(sdc);
+ assertTrue(InternalNativeBridge.unwrapArena(sdc).scope().isAlive());
+ } catch (ELIBSecurityNativeCritical e) {
+ // 통신 실패 시 던져지는 예외 메시지가 우리가 정의한 규칙에 부합하는지 확인
+ String msg = e.getMessage();
+ assertTrue(
+ msg.contains("네트워크(network)") || msg.contains("파싱(parsing)") || msg.contains("알 수 없는"),
+ "예상치 못한 네이티브 에러가 발생했습니다: " + msg
+ );
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/SHA2HashTest.java b/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/SHA2HashTest.java
new file mode 100644
index 0000000..d092042
--- /dev/null
+++ b/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/SHA2HashTest.java
@@ -0,0 +1,190 @@
+package space.qu4nt.entanglementlib.security.crypto;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import space.qu4nt.entanglementlib.security.EntanglementLibSecurityConfig;
+import space.qu4nt.entanglementlib.security.EntanglementLibSecurityFacade;
+import space.qu4nt.entanglementlib.security.crypto.hash.Hash;
+import space.qu4nt.entanglementlib.security.data.HeuristicArenaFactory;
+import space.qu4nt.entanglementlib.security.data.InternalNativeBridge;
+import space.qu4nt.entanglementlib.security.data.SDCScopeContext;
+import space.qu4nt.entanglementlib.security.data.SensitiveDataContainer;
+import space.qu4nt.entanglementlib.security.entlibnative.Function;
+import space.qu4nt.entanglementlib.security.entlibnative.NativeSpecContext;
+
+import java.lang.foreign.MemorySegment;
+import java.lang.foreign.ValueLayout;
+import java.nio.charset.StandardCharsets;
+import java.util.HexFormat;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class SHA2HashTest {
+
+ @BeforeAll
+ static void setUp() {
+ // 테스트 클래스 로드 시 1회만 네이티브 라이브러리를 초기화하여 성능 최적화
+ EntanglementLibSecurityFacade.initialize(
+ EntanglementLibSecurityConfig.create(
+ new NativeSpecContext(System.getenv("ENTLIB_NATIVE_BIN"), "entlib_native_ffi",
+ Function.chain(
+ Function.withCalleeSecureBuffer(),
+ Function.withCallerSecureBuffer(),
+ Function.withHash(true))),
+ HeuristicArenaFactory.ArenaMode.CONFINED)
+ );
+ }
+
+ @Test
+ @DisplayName("SHA-224 known answer test & 메모리 안전성 검증")
+ void sha224StrictTest() throws Throwable {
+ // 테스트 벡터
+ final String inputText = "Hello, World!";
+ // SHA-224 기댓값
+ final String expectedHex = "72a23dfa411ba6fde01dbfabf3b00a709c93ebf273dc29e2d8b261ff";
+ final byte[] inputBytes = inputText.getBytes(StandardCharsets.UTF_8);
+
+ MemorySegment resultSegmentAlias;
+
+ // 보안 스코프 내에서 암호화 연산 수행
+ try (SDCScopeContext context = new SDCScopeContext()) {
+ SensitiveDataContainer inputData = context.allocate(inputBytes, true);
+ SensitiveDataContainer result = Hash.sha2(224, context, inputData);
+
+ assertNotNull(result, "해시 연산 결과는 null일 수 없습니다.");
+ resultSegmentAlias = InternalNativeBridge.unwrapMemorySegment(result);
+
+ // [검증 A] 길이 검증
+ assertEquals(28, resultSegmentAlias.byteSize(),
+ "SHA-224 해시 결과는 정확히 28바이트(224비트)여야 합니다.");
+
+ // [검증 B] 무결성 검증 (correctness check)
+ byte[] actualHashBytes = resultSegmentAlias.toArray(ValueLayout.JAVA_BYTE);
+ String actualHex = HexFormat.of().formatHex(actualHashBytes);
+ assertEquals(expectedHex, actualHex,
+ "계산된 해시값이 예상된 SHA-224 KAT(known answer test) 값과 정확히 일치해야 합니다.");
+ }
+
+ // 스코프 종료 후 메모리 보호 메커니즘 검증
+ // 컨텍스트(context)가 close()된 이후, 해당 arena에 종속된 세그먼트에 접근을 시도하면
+ // 자바 런타임이 IllegalStateException을 발생시켜야 안전한 소거 및 접근 차단이 입증됨
+ assertThrows(IllegalStateException.class, () ->
+ resultSegmentAlias.get(ValueLayout.JAVA_BYTE, 0),
+ "스코프가 종료된 이후 메모리 세그먼트에 접근할 경우 반드시 예외가 발생하여 잔류 데이터 유출을 막아야 합니다.");
+ }
+
+ @Test
+ @DisplayName("SHA-256 known answer test & 메모리 안전성 검증")
+ void sha256StrictTest() throws Throwable {
+ // 테스트 벡터
+ final String inputText = "Hello, World!";
+ // SHA-256 기댓값
+ final String expectedHex = "dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f";
+ final byte[] inputBytes = inputText.getBytes(StandardCharsets.UTF_8);
+
+ MemorySegment resultSegmentAlias;
+
+ // 보안 스코프 내에서 암호화 연산 수행
+ try (SDCScopeContext context = new SDCScopeContext()) {
+ SensitiveDataContainer inputData = context.allocate(inputBytes, true);
+ SensitiveDataContainer result = Hash.sha2(256, context, inputData);
+
+ assertNotNull(result, "해시 연산 결과는 null일 수 없습니다.");
+ resultSegmentAlias = InternalNativeBridge.unwrapMemorySegment(result);
+
+ // [검증 A] 길이 검증
+ assertEquals(32, resultSegmentAlias.byteSize(),
+ "SHA-256 해시 결과는 정확히 32바이트(256비트)여야 합니다.");
+
+ // [검증 B] 무결성 검증 (correctness check)
+ byte[] actualHashBytes = resultSegmentAlias.toArray(ValueLayout.JAVA_BYTE);
+ String actualHex = HexFormat.of().formatHex(actualHashBytes);
+ assertEquals(expectedHex, actualHex,
+ "계산된 해시값이 예상된 SHA-256 KAT(known answer test) 값과 정확히 일치해야 합니다.");
+ }
+
+ // 스코프 종료 후 메모리 보호 메커니즘 검증
+ // 컨텍스트(context)가 close()된 이후, 해당 arena에 종속된 세그먼트에 접근을 시도하면
+ // 자바 런타임이 IllegalStateException을 발생시켜야 안전한 소거 및 접근 차단이 입증됨
+ assertThrows(IllegalStateException.class, () ->
+ resultSegmentAlias.get(ValueLayout.JAVA_BYTE, 0),
+ "스코프가 종료된 이후 메모리 세그먼트에 접근할 경우 반드시 예외가 발생하여 잔류 데이터 유출을 막아야 합니다.");
+ }
+
+ @Test
+ @DisplayName("SHA-384 known answer test & 메모리 안전성 검증")
+ void sha384StrictTest() throws Throwable {
+ // 테스트 벡터
+ final String inputText = "Hello, World!";
+ // SHA-384 기댓값
+ final String expectedHex = "5485cc9b3365b4305dfb4e8337e0a598a574f8242bf17289e0dd6c20a3cd44a089de16ab4ab308f63e44b1170eb5f515";
+ final byte[] inputBytes = inputText.getBytes(StandardCharsets.UTF_8);
+
+ MemorySegment resultSegmentAlias;
+
+ // 보안 스코프 내에서 암호화 연산 수행
+ try (SDCScopeContext context = new SDCScopeContext()) {
+ SensitiveDataContainer inputData = context.allocate(inputBytes, true);
+ SensitiveDataContainer result = Hash.sha2(384, context, inputData);
+
+ assertNotNull(result, "해시 연산 결과는 null일 수 없습니다.");
+ resultSegmentAlias = InternalNativeBridge.unwrapMemorySegment(result);
+
+ // [검증 A] 길이 검증
+ assertEquals(48, resultSegmentAlias.byteSize(),
+ "SHA-384 해시 결과는 정확히 48바이트(384비트)여야 합니다.");
+
+ // [검증 B] 무결성 검증 (correctness check)
+ byte[] actualHashBytes = resultSegmentAlias.toArray(ValueLayout.JAVA_BYTE);
+ String actualHex = HexFormat.of().formatHex(actualHashBytes);
+ assertEquals(expectedHex, actualHex,
+ "계산된 해시값이 예상된 SHA-384 KAT(known answer test) 값과 정확히 일치해야 합니다.");
+ }
+
+ // 스코프 종료 후 메모리 보호 메커니즘 검증
+ // 컨텍스트(context)가 close()된 이후, 해당 arena에 종속된 세그먼트에 접근을 시도하면
+ // 자바 런타임이 IllegalStateException을 발생시켜야 안전한 소거 및 접근 차단이 입증됨
+ assertThrows(IllegalStateException.class, () ->
+ resultSegmentAlias.get(ValueLayout.JAVA_BYTE, 0),
+ "스코프가 종료된 이후 메모리 세그먼트에 접근할 경우 반드시 예외가 발생하여 잔류 데이터 유출을 막아야 합니다.");
+ }
+
+ @Test
+ @DisplayName("SHA-512 known answer test & 메모리 안전성 검증")
+ void sha512StrictTest() throws Throwable {
+ // 테스트 벡터
+ final String inputText = "Hello, World!";
+ // SHA-512 기댓값
+ final String expectedHex = "374d794a95cdcfd8b35993185fef9ba368f160d8daf432d08ba9f1ed1e5abe6cc69291e0fa2fe0006a52570ef18c19def4e617c33ce52ef0a6e5fbe318cb0387";
+ final byte[] inputBytes = inputText.getBytes(StandardCharsets.UTF_8);
+
+ MemorySegment resultSegmentAlias;
+
+ // 보안 스코프 내에서 암호화 연산 수행
+ try (SDCScopeContext context = new SDCScopeContext()) {
+ SensitiveDataContainer inputData = context.allocate(inputBytes, true);
+ SensitiveDataContainer result = Hash.sha2(512, context, inputData);
+
+ assertNotNull(result, "해시 연산 결과는 null일 수 없습니다.");
+ resultSegmentAlias = InternalNativeBridge.unwrapMemorySegment(result);
+
+ // [검증 A] 길이 검증
+ assertEquals(64, resultSegmentAlias.byteSize(),
+ "SHA-512 해시 결과는 정확히 64바이트(512비트)여야 합니다.");
+
+ // [검증 B] 무결성 검증 (correctness check)
+ byte[] actualHashBytes = resultSegmentAlias.toArray(ValueLayout.JAVA_BYTE);
+ String actualHex = HexFormat.of().formatHex(actualHashBytes);
+ assertEquals(expectedHex, actualHex,
+ "계산된 해시값이 예상된 SHA-512 KAT(known answer test) 값과 정확히 일치해야 합니다.");
+ }
+
+ // 스코프 종료 후 메모리 보호 메커니즘 검증
+ // 컨텍스트(context)가 close()된 이후, 해당 arena에 종속된 세그먼트에 접근을 시도하면
+ // 자바 런타임이 IllegalStateException을 발생시켜야 안전한 소거 및 접근 차단이 입증됨
+ assertThrows(IllegalStateException.class, () -> {
+ resultSegmentAlias.get(ValueLayout.JAVA_BYTE, 0);
+ }, "스코프가 종료된 이후 메모리 세그먼트에 접근할 경우 반드시 예외가 발생하여 잔류 데이터 유출을 막아야 합니다.");
+ }
+}
\ No newline at end of file
diff --git a/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/SHA3HashTest.java b/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/SHA3HashTest.java
new file mode 100644
index 0000000..ed32ec8
--- /dev/null
+++ b/security/src/test/java/space/qu4nt/entanglementlib/security/crypto/SHA3HashTest.java
@@ -0,0 +1,267 @@
+package space.qu4nt.entanglementlib.security.crypto;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import space.qu4nt.entanglementlib.security.EntanglementLibSecurityConfig;
+import space.qu4nt.entanglementlib.security.EntanglementLibSecurityFacade;
+import space.qu4nt.entanglementlib.security.data.HeuristicArenaFactory;
+import space.qu4nt.entanglementlib.security.crypto.hash.Hash;
+import space.qu4nt.entanglementlib.security.data.InternalNativeBridge;
+import space.qu4nt.entanglementlib.security.data.SDCScopeContext;
+import space.qu4nt.entanglementlib.security.data.SensitiveDataContainer;
+import space.qu4nt.entanglementlib.security.entlibnative.Function;
+import space.qu4nt.entanglementlib.security.entlibnative.NativeSpecContext;
+
+import java.lang.foreign.MemorySegment;
+import java.lang.foreign.ValueLayout;
+import java.nio.charset.StandardCharsets;
+import java.util.HexFormat;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class SHA3HashTest {
+
+ @BeforeAll
+ static void setUp() {
+ // 테스트 클래스 로드 시 1회만 네이티브 라이브러리를 초기화하여 성능 최적화
+ EntanglementLibSecurityFacade.initialize(
+ EntanglementLibSecurityConfig.create(
+ new NativeSpecContext(System.getenv("ENTLIB_NATIVE_BIN"), "entlib_native_ffi",
+ Function.chain(
+ Function.withCalleeSecureBuffer(),
+ Function.withCallerSecureBuffer(),
+ Function.withHash(false))
+ ),
+ HeuristicArenaFactory.ArenaMode.CONFINED)
+ );
+ }
+
+ @Test
+ @DisplayName("SHA3-224 known answer test & 메모리 안전성 검증")
+ void sha3_224StrictTest() throws Throwable {
+ // 테스트 벡터
+ final String inputText = "Hello, World!";
+ // SHA3-224 기댓값
+ final String expectedHex = "853048fb8b11462b6100385633c0cc8dcdc6e2b8e376c28102bc84f2";
+ final byte[] inputBytes = inputText.getBytes(StandardCharsets.UTF_8);
+
+ MemorySegment resultSegmentAlias;
+
+ // 보안 스코프 내에서 암호화 연산 수행
+ try (SDCScopeContext context = new SDCScopeContext()) {
+ SensitiveDataContainer inputData = context.allocate(inputBytes, true);
+ SensitiveDataContainer result = Hash.sha3(224, context, inputData);
+
+ assertNotNull(result, "해시 연산 결과는 null일 수 없습니다.");
+ resultSegmentAlias = InternalNativeBridge.unwrapMemorySegment(result);
+
+ // [검증 A] 길이 검증
+ assertEquals(28, resultSegmentAlias.byteSize(),
+ "SHA3-224 해시 결과는 정확히 28바이트(224비트)여야 합니다.");
+
+ // [검증 B] 무결성 검증 (correctness check)
+ byte[] actualHashBytes = resultSegmentAlias.toArray(ValueLayout.JAVA_BYTE);
+ String actualHex = HexFormat.of().formatHex(actualHashBytes);
+ assertEquals(expectedHex, actualHex,
+ "계산된 해시값이 예상된 SH3A-224 KAT(known answer test) 값과 정확히 일치해야 합니다.");
+ }
+
+ // 스코프 종료 후 메모리 보호 메커니즘 검증
+ // 컨텍스트(context)가 close()된 이후, 해당 arena에 종속된 세그먼트에 접근을 시도하면
+ // 자바 런타임이 IllegalStateException을 발생시켜야 안전한 소거 및 접근 차단이 입증됨
+ assertThrows(IllegalStateException.class, () ->
+ resultSegmentAlias.get(ValueLayout.JAVA_BYTE, 0),
+ "스코프가 종료된 이후 메모리 세그먼트에 접근할 경우 반드시 예외가 발생하여 잔류 데이터 유출을 막아야 합니다.");
+ }
+
+ @Test
+ @DisplayName("SHA3-256 known answer test & 메모리 안전성 검증")
+ void sha3_256StrictTest() throws Throwable {
+ // 테스트 벡터
+ final String inputText = "Hello, World!";
+ // SHA3-256 기댓값
+ final String expectedHex = "1af17a664e3fa8e419b8ba05c2a173169df76162a5a286e0c405b460d478f7ef";
+ final byte[] inputBytes = inputText.getBytes(StandardCharsets.UTF_8);
+
+ MemorySegment resultSegmentAlias;
+
+ // 보안 스코프 내에서 암호화 연산 수행
+ try (SDCScopeContext context = new SDCScopeContext()) {
+ SensitiveDataContainer inputData = context.allocate(inputBytes, true);
+ SensitiveDataContainer result = Hash.sha3(256, context, inputData);
+
+ assertNotNull(result, "해시 연산 결과는 null일 수 없습니다.");
+ resultSegmentAlias = InternalNativeBridge.unwrapMemorySegment(result);
+
+ // [검증 A] 길이 검증
+ assertEquals(32, resultSegmentAlias.byteSize(),
+ "SHA3-256 해시 결과는 정확히 32바이트(256비트)여야 합니다.");
+
+ // [검증 B] 무결성 검증 (correctness check)
+ byte[] actualHashBytes = resultSegmentAlias.toArray(ValueLayout.JAVA_BYTE);
+ String actualHex = HexFormat.of().formatHex(actualHashBytes);
+ assertEquals(expectedHex, actualHex,
+ "계산된 해시값이 예상된 SHA3-256 KAT(known answer test) 값과 정확히 일치해야 합니다.");
+ }
+
+ // 스코프 종료 후 메모리 보호 메커니즘 검증
+ // 컨텍스트(context)가 close()된 이후, 해당 arena에 종속된 세그먼트에 접근을 시도하면
+ // 자바 런타임이 IllegalStateException을 발생시켜야 안전한 소거 및 접근 차단이 입증됨
+ assertThrows(IllegalStateException.class, () ->
+ resultSegmentAlias.get(ValueLayout.JAVA_BYTE, 0),
+ "스코프가 종료된 이후 메모리 세그먼트에 접근할 경우 반드시 예외가 발생하여 잔류 데이터 유출을 막아야 합니다.");
+ }
+
+ @Test
+ @DisplayName("SHA3-384 known answer test & 메모리 안전성 검증")
+ void sha3_384StrictTest() throws Throwable {
+ // 테스트 벡터
+ final String inputText = "Hello, World!";
+ // SHA3-384 기댓값
+ final String expectedHex = "aa9ad8a49f31d2ddcabbb7010a1566417cff803fef50eba239558826f872e468c5743e7f026b0a8e5b2d7a1cc465cdbe";
+ final byte[] inputBytes = inputText.getBytes(StandardCharsets.UTF_8);
+
+ MemorySegment resultSegmentAlias;
+
+ // 보안 스코프 내에서 암호화 연산 수행
+ try (SDCScopeContext context = new SDCScopeContext()) {
+ SensitiveDataContainer inputData = context.allocate(inputBytes, true);
+ SensitiveDataContainer result = Hash.sha3(384, context, inputData);
+
+ assertNotNull(result, "해시 연산 결과는 null일 수 없습니다.");
+ resultSegmentAlias = InternalNativeBridge.unwrapMemorySegment(result);
+
+ // [검증 A] 길이 검증
+ assertEquals(48, resultSegmentAlias.byteSize(),
+ "SHA3-384 해시 결과는 정확히 32바이트(384비트)여야 합니다.");
+
+ // [검증 B] 무결성 검증 (correctness check)
+ byte[] actualHashBytes = resultSegmentAlias.toArray(ValueLayout.JAVA_BYTE);
+ String actualHex = HexFormat.of().formatHex(actualHashBytes);
+ assertEquals(expectedHex, actualHex,
+ "계산된 해시값이 예상된 SHA3-384 KAT(known answer test) 값과 정확히 일치해야 합니다.");
+ }
+
+ // 스코프 종료 후 메모리 보호 메커니즘 검증
+ // 컨텍스트(context)가 close()된 이후, 해당 arena에 종속된 세그먼트에 접근을 시도하면
+ // 자바 런타임이 IllegalStateException을 발생시켜야 안전한 소거 및 접근 차단이 입증됨
+ assertThrows(IllegalStateException.class, () ->
+ resultSegmentAlias.get(ValueLayout.JAVA_BYTE, 0),
+ "스코프가 종료된 이후 메모리 세그먼트에 접근할 경우 반드시 예외가 발생하여 잔류 데이터 유출을 막아야 합니다.");
+ }
+
+ @Test
+ @DisplayName("SHA3-512 known answer test & 메모리 안전성 검증")
+ void sha3_512StrictTest() throws Throwable {
+ // 테스트 벡터
+ final String inputText = "Hello, World!";
+ // SHA3-512 기댓값
+ final String expectedHex = "38e05c33d7b067127f217d8c856e554fcff09c9320b8a5979ce2ff5d95dd27ba35d1fba50c562dfd1d6cc48bc9c5baa4390894418cc942d968f97bcb659419ed";
+ final byte[] inputBytes = inputText.getBytes(StandardCharsets.UTF_8);
+
+ MemorySegment resultSegmentAlias;
+
+ // 보안 스코프 내에서 암호화 연산 수행
+ try (SDCScopeContext context = new SDCScopeContext()) {
+ SensitiveDataContainer inputData = context.allocate(inputBytes, true);
+ SensitiveDataContainer result = Hash.sha3(512, context, inputData);
+
+ assertNotNull(result, "해시 연산 결과는 null일 수 없습니다.");
+ resultSegmentAlias = InternalNativeBridge.unwrapMemorySegment(result);
+
+ // [검증 A] 길이 검증
+ assertEquals(64, resultSegmentAlias.byteSize(),
+ "SHA3-512 해시 결과는 정확히 32바이트(512비트)여야 합니다.");
+
+ // [검증 B] 무결성 검증 (correctness check)
+ byte[] actualHashBytes = resultSegmentAlias.toArray(ValueLayout.JAVA_BYTE);
+ String actualHex = HexFormat.of().formatHex(actualHashBytes);
+ assertEquals(expectedHex, actualHex,
+ "계산된 해시값이 예상된 SHA3-512 KAT(known answer test) 값과 정확히 일치해야 합니다.");
+ }
+
+ // 스코프 종료 후 메모리 보호 메커니즘 검증
+ // 컨텍스트(context)가 close()된 이후, 해당 arena에 종속된 세그먼트에 접근을 시도하면
+ // 자바 런타임이 IllegalStateException을 발생시켜야 안전한 소거 및 접근 차단이 입증됨
+ assertThrows(IllegalStateException.class, () ->
+ resultSegmentAlias.get(ValueLayout.JAVA_BYTE, 0),
+ "스코프가 종료된 이후 메모리 세그먼트에 접근할 경우 반드시 예외가 발생하여 잔류 데이터 유출을 막아야 합니다.");
+ }
+
+ @Test
+ @DisplayName("SHA3-SHAKE128 known answer test & 메모리 안전성 검증")
+ void sha3_shake128StrictTest() throws Throwable {
+ // 테스트 벡터
+ final String inputText = "Hello, World!";
+ // SHA3-SHAKE128 (256비트) 기댓값
+ final String expectedHex = "2bf5e6dee6079fad604f573194ba8426bd4d30eb13e8ba2edae70e529b570cbd";
+ final byte[] inputBytes = inputText.getBytes(StandardCharsets.UTF_8);
+
+ MemorySegment resultSegmentAlias;
+
+ // 보안 스코프 내에서 암호화 연산 수행
+ try (SDCScopeContext context = new SDCScopeContext()) {
+ SensitiveDataContainer inputData = context.allocate(inputBytes, true);
+ SensitiveDataContainer result = Hash.sha3Shake(128, 32, context, inputData);
+
+ assertNotNull(result, "해시 연산 결과는 null일 수 없습니다.");
+ resultSegmentAlias = InternalNativeBridge.unwrapMemorySegment(result);
+
+ // [검증 A] 길이 검증
+ assertEquals(32, resultSegmentAlias.byteSize(),
+ "이 테스트에서 SHA3-SHAKE128 해시 결과는 정확히 256비트여야 합니다.");
+
+ // [검증 B] 무결성 검증 (correctness check)
+ byte[] actualHashBytes = resultSegmentAlias.toArray(ValueLayout.JAVA_BYTE);
+ String actualHex = HexFormat.of().formatHex(actualHashBytes);
+ assertEquals(expectedHex, actualHex,
+ "계산된 해시값이 예상된 SHA3-SHAKE128 KAT(known answer test) 값과 정확히 일치해야 합니다.");
+ }
+
+ // 스코프 종료 후 메모리 보호 메커니즘 검증
+ // 컨텍스트(context)가 close()된 이후, 해당 arena에 종속된 세그먼트에 접근을 시도하면
+ // 자바 런타임이 IllegalStateException을 발생시켜야 안전한 소거 및 접근 차단이 입증됨
+ assertThrows(IllegalStateException.class, () ->
+ resultSegmentAlias.get(ValueLayout.JAVA_BYTE, 0),
+ "스코프가 종료된 이후 메모리 세그먼트에 접근할 경우 반드시 예외가 발생하여 잔류 데이터 유출을 막아야 합니다.");
+ }
+
+ @Test
+ @DisplayName("SHA3-SHAKE256 known answer test & 메모리 안전성 검증")
+ void sha3_shake256StrictTest() throws Throwable {
+ // 테스트 벡터
+ final String inputText = "Hello, World!";
+ // SHA3-SHAKE256 (512비트) 기댓값
+ final String expectedHex = "b3be97bfd978833a65588ceae8a34cf59e95585af62063e6b89d0789f372424e8b0d1be4f21b40ce5a83a438473271e0661854f02d431db74e6904d6c347d757";
+ final byte[] inputBytes = inputText.getBytes(StandardCharsets.UTF_8);
+
+ MemorySegment resultSegmentAlias;
+
+ // 보안 스코프 내에서 암호화 연산 수행
+ try (SDCScopeContext context = new SDCScopeContext()) {
+ SensitiveDataContainer inputData = context.allocate(inputBytes, true);
+ SensitiveDataContainer result = Hash.sha3Shake(256, 64, context, inputData);
+
+ assertNotNull(result, "해시 연산 결과는 null일 수 없습니다.");
+ resultSegmentAlias = InternalNativeBridge.unwrapMemorySegment(result);
+
+ // [검증 A] 길이 검증
+ assertEquals(64, resultSegmentAlias.byteSize(),
+ "이 테스트에서 SHA3-SHAKE256 해시 결과는 정확히 128자리여야 합니다.");
+
+ // [검증 B] 무결성 검증 (correctness check)
+ byte[] actualHashBytes = resultSegmentAlias.toArray(ValueLayout.JAVA_BYTE);
+ String actualHex = HexFormat.of().formatHex(actualHashBytes);
+ assertEquals(expectedHex, actualHex,
+ "계산된 해시값이 예상된 SHA3-SHAKE256 KAT(known answer test) 값과 정확히 일치해야 합니다.");
+ }
+
+ // 스코프 종료 후 메모리 보호 메커니즘 검증
+ // 컨텍스트(context)가 close()된 이후, 해당 arena에 종속된 세그먼트에 접근을 시도하면
+ // 자바 런타임이 IllegalStateException을 발생시켜야 안전한 소거 및 접근 차단이 입증됨
+ assertThrows(IllegalStateException.class, () ->
+ resultSegmentAlias.get(ValueLayout.JAVA_BYTE, 0),
+ "스코프가 종료된 이후 메모리 세그먼트에 접근할 경우 반드시 예외가 발생하여 잔류 데이터 유출을 막아야 합니다.");
+ }
+}
\ No newline at end of file
diff --git a/settings.gradle.kts b/settings.gradle.kts
index b1fc284..d219926 100644
--- a/settings.gradle.kts
+++ b/settings.gradle.kts
@@ -1 +1,5 @@
-rootProject.name = "entanglementlib"
\ No newline at end of file
+rootProject.name = "entanglementlib"
+include("core")
+include("security")
+include("annotations")
+include("annotation-processor")
\ No newline at end of file
diff --git a/src/main/java/space/qu4nt/entanglementlib/CallerResponsibility.java b/src/main/java/space/qu4nt/entanglementlib/CallerResponsibility.java
deleted file mode 100644
index e4f6d12..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/CallerResponsibility.java
+++ /dev/null
@@ -1,34 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib;
-
-import java.lang.annotation.Documented;
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Target;
-
-/**
- * 보안적 책임은 호출자에게 있음을 알리는 어노테이션입니다.
- * 호출자가 해당 어노테이션이 사용된 멤버 사용 시, 작업 종료 후
- * 반드시 보안 작업이 필요함을 의미합니다.
- *
- * 예를 들어, 이 어노테이션이 (복사본이 아닌) 원본 데이터를 반환하는 메소드에 사용되었고
- * 해당 메소드를 사용하고자 하는 경우 반환받은 데이터를 소거해야 합니다.
- *
- * @author Q. T. Felix
- * @since 1.1.0
- */
-@Documented
-@Target(ElementType.TYPE_USE)
-public @interface CallerResponsibility {
-
- /**
- * 책임 전가의 사유 또는 설명를 정의합니다.
- *
- * @return 책임 전가 사유 또는 설명
- */
- String value() default "";
-
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/EntanglementLibBootstrap.java b/src/main/java/space/qu4nt/entanglementlib/EntanglementLibBootstrap.java
deleted file mode 100644
index f151508..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/EntanglementLibBootstrap.java
+++ /dev/null
@@ -1,118 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib;
-
-import lombok.AccessLevel;
-import lombok.AllArgsConstructor;
-import lombok.Getter;
-import lombok.Setter;
-import lombok.extern.slf4j.Slf4j;
-import org.jetbrains.annotations.ApiStatus;
-import org.jetbrains.annotations.NotNull;
-
-import java.io.IOException;
-import java.lang.reflect.Field;
-import java.nio.charset.StandardCharsets;
-import java.nio.file.Files;
-import java.nio.file.Paths;
-import java.security.Provider;
-import java.security.SecureRandom;
-import java.security.Security;
-import java.util.*;
-
-/**
- * 얽힘 라이브러리의 몇 가지 기능을 외부에서 즉시 호출할 수도 있지만
- * 이 경우 정적 블록에 대한 메모리 할당 및 그에 상응하는 작업의 시간 복잡도가
- * 증가합니다. 이를 해결하기 위해 만들어진 내부 로딩 부트스트랩 클래스입니다.
- *
- * 이 클래스가 내부에서 사용되는 경우는 전달받은 외부 프로젝트(호출자)의 이름을
- * 사용하는 때 이외엔 없으며, 호출되어서도 안 됩니다.
- *
- * @author Q. T. Felix
- * @since 1.1.0
- */
-@Slf4j
-@Getter
-@Setter
-@AllArgsConstructor(access = AccessLevel.PRIVATE)
-public final class EntanglementLibBootstrap {
-
- static {
- log.debug("얽힘 라이브러리(EntanglementLib) 등록");
- }
-
- @ApiStatus.Internal
- private @NotNull String projectName;
-
- @ExternalPattern
- public static EntanglementLibBootstrap registerEntanglementLib(@NotNull String projectName, boolean setBCProviders) {
- if (setBCProviders)
- InternalFactory.registerInternalEntanglementLib();
- return new EntanglementLibBootstrap(projectName);
- }
-
- @ExternalPattern
- public @NotNull SecureRandom getSafeRandom() {
- return InternalFactory.getSafeRandom();
- }
-
- @ApiStatus.Internal
- public static void providerInformation() throws IOException {
- Map>> providerInfo = new LinkedHashMap<>();
-
- for (Provider provider : Security.getProviders()) {
- if (provider == null || provider.getName() == null) continue;
-
- String providerName = provider.getName();
- Map> services = new TreeMap<>();
-
- for (Provider.Service service : provider.getServices()) {
- String type = service.getType();
- String algorithm = service.getAlgorithm();
-
- StringBuilder algoDetails = new StringBuilder(algorithm);
-
- try {
- Field attrField = service.getClass().getDeclaredField("attributes");
- attrField.setAccessible(true);
- @SuppressWarnings("unchecked")
- Map map = (Map) attrField.get(service);
- if (map != null) {
- map.forEach((k, v) -> {
- if (!"Software".equals(v)) {
-// algoDetails.append("\n - ").append(k).append(": ").append(v);
- }
- });
- }
- } catch (Exception _) {
- }
-
- services.computeIfAbsent(type, k -> new ArrayList<>()).add(algoDetails.toString());
- }
- providerInfo.put(providerName, services);
- }
-
- StringBuilder stringTower = new StringBuilder();
- providerInfo.forEach((pName, services) -> {
- stringTower.append("공급자: ").append(pName).append("\n");
- services.forEach((type, algos) -> {
- stringTower.append("- ").append(type).append("\n");
- for (String algo : algos) {
- stringTower.append(" - ").append(algo).append("\n");
- }
- });
- stringTower.append("\n");
- });
-
- Files.writeString(Paths.get(InternalFactory.envEntanglementPublicDir()).resolve("security-providers.txt"), stringTower.toString(), StandardCharsets.UTF_8);
- }
-
- @ApiStatus.Internal
- static void main() throws IOException {
- InternalFactory.setupSecurityProviders();
- providerInformation();
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/EntanglementLibEnvs.java b/src/main/java/space/qu4nt/entanglementlib/EntanglementLibEnvs.java
deleted file mode 100644
index 6b303f3..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/EntanglementLibEnvs.java
+++ /dev/null
@@ -1,57 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib;
-
-import com.quant.quantregular.annotations.QuantTypeOwner;
-import com.quant.quantregular.annotations.Quanters;
-
-/**
- * {@code EntanglementLib}에서 공통으로 사용되는 환경 변수 값을 정의한 클래스입니다.
- *
- * 이 클래스는 {@link InternalFactory}에서만 구현되며, 외부에서 호출할 수 없습니다.
- *
- * @author Q. T. Felix
- * @since 1.0.0
- */
-@QuantTypeOwner(Quanters.Q_T_FELIX)
-sealed class EntanglementLibEnvs extends WrapEnv permits InternalFactory {
-
- private static final EntanglementLibEnvs entanglementPublicDir;
-
- private static final EntanglementLibEnvs entanglementHomeDir;
-
- private static final EntanglementLibEnvs entLibNativeDir;
-
- static {
- entanglementPublicDir = new EntanglementLibEnvs("ENTANGLEMENT_PUBLIC_DIR" , true);
- entanglementHomeDir = new EntanglementLibEnvs("ENTANGLEMENT_HOME_DIR" , true);
- entLibNativeDir = new EntanglementLibEnvs("ENTLIB_NATIVE_BIN" , false, "native");
- }
-
- EntanglementLibEnvs() {
- throw new UnsupportedOperationException("do not empty instantiate this class");
- }
-
- EntanglementLibEnvs(String env, boolean req, String def) {
- super(env, req, def);
- }
-
- EntanglementLibEnvs(String env, boolean req) {
- this(env, req, null);
- }
-
- public static String envEntanglementPublicDir() {
- return entanglementPublicDir.getEnv();
- }
-
- public static String envEntanglementHomeDir() {
- return entanglementHomeDir.getEnv();
- }
-
- public static String envEntLibNativeDir() {
- return entLibNativeDir.getEnv();
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/InternalFactory.java b/src/main/java/space/qu4nt/entanglementlib/InternalFactory.java
deleted file mode 100644
index 822ef17..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/InternalFactory.java
+++ /dev/null
@@ -1,234 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib;
-
-import lombok.extern.slf4j.Slf4j;
-import org.bouncycastle.crypto.CryptoServicesRegistrar;
-import org.bouncycastle.jce.provider.BouncyCastleProvider;
-import org.bouncycastle.jsse.provider.BouncyCastleJsseProvider;
-import org.bouncycastle.pqc.jcajce.provider.BouncyCastlePQCProvider;
-import org.jetbrains.annotations.ApiStatus;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
-import space.qu4nt.entanglementlib.entlibnative.NativeLinkerManager;
-import space.qu4nt.entanglementlib.exception.critical.EntLibNativeError;
-import space.qu4nt.entanglementlib.resource.config.PublicConfiguration;
-import space.qu4nt.entanglementlib.resource.language.LanguageInstanceBased;
-import space.qu4nt.entanglementlib.security.crypto.EntLibCryptoRegistry;
-import space.qu4nt.entanglementlib.util.chunk.ByteArrayChunkProcessor;
-import tools.jackson.databind.ObjectMapper;
-
-import java.lang.foreign.ValueLayout;
-import java.security.*;
-import java.util.Objects;
-
-/// 환경 변수 할당 및 암호화 연산을 중앙에서 처리하기 위한 내부 클래스입니다.
-///
-/// `BouncyCastle` 라이브러리 공급자를 `JCA`에 등록하거나 서명, KEM 등의 알고리즘 연산을 간편화할 때 사용됩니다.
-/// 필요한 경우 [#_bcNormalProvider] 또는 [#_bcPQCProvider] 상수를 통해 라이브러리 공급자 이름을 사용하거나
-/// `JCA`에 공급자를 등록할 수 있습니다.
-///
-/// @author Q. T. Felix
-/// @since 1.0.0
-@ApiStatus.Internal
-@Slf4j
-public final class InternalFactory extends EntanglementLibEnvs {
-
- /**
- * 얽힘 라이브러리의 공개 구성입니다. 라이브러리 로드 시 가장 먼저 초기화되어야 합니다.
- */
- private static final PublicConfiguration config;
- /**
- * {@link InternalFactory} 클래스에 대한 다국어 지원 인스턴스입니다.
- */
- private static final LanguageInstanceBased lang;
-
- /**
- * BouncyCastle 일반 및 NIST 표준화된 암호화 공급자 이름입니다.
- */
- private static String _bcNormalProvider;
- /**
- * BouncyCastle 양자-내성 암호화 공급자 이름입니다.
- */
- private static String _bcPQCProvider;
- /**
- * BouncyCastle JSSE (Java Secure Socket Extension) 공급자 이름입니다.
- */
- private static String _bcJSSEProvider;
-
- /**
- * 최초 선언 후 변경되지 않는 보안 난수 생성기입니다.
- *
- * 보안 난수를 생성하기 위해 해당 상수만을 사용해야 합니다.
- *
- * {@code BouncyCastle} 라이브러리가 자동으로 최적의 소스를 선택합니다.
- */
- private static final SecureRandom SAFE_RANDOM;
-
- // TODO: 동적 리소스 할당 로직과 그에 따른 약간의 패턴 변형
- static {
- config = new PublicConfiguration(new ObjectMapper());
- lang = LanguageInstanceBased.create(InternalFactory.class);
- log.debug(lang.argsNonTopKey("loaded-configuration", config));
-
- SAFE_RANDOM = CryptoServicesRegistrar.getSecureRandom();
- log.debug(lang.msg("init-saferandom"));
- }
-
- //
- // EntLib-Native - start
- //
-
- private static final NativeLinkerManager NATIVE;
-
- static {
- log.debug("네이티브 로드");
- NATIVE = new NativeLinkerManager("entlib_native")
- .addVoidMethodHandle("entanglement_secure_wipe", ValueLayout.ADDRESS, ValueLayout.JAVA_LONG);
- }
-
- @NotNull
- public static NativeLinkerManager callNativeLib() {
- if (NATIVE == null)
- throw new EntLibNativeError("네이티브 라이브러리가 등록되지 않았습니다!");
- return NATIVE;
- }
-
- //
- // EntLib-Native - end todo; 배포 용이하게 수정
- //
-
- static void registerInternalEntanglementLib() {
- setupSecurityProviders();
- System.setProperty("jdk.tls.maxHandshakeMessageSize", String.valueOf(config.getTlsMaxHandshakeMessageSize()));
- log.debug("얽힘 라이브러리 레지스트리에 {}개의 알고리즘 등록됨", EntLibCryptoRegistry.registeredCount());
- }
-
- /**
- * 유틸리티 클래스의 인스턴스화를 방지하기 위한 생성자입니다.
- */
- private InternalFactory() {
- throw new UnsupportedOperationException("InternalFactory");
- }
-
- /**
- * 등록된 {@link BouncyCastleProvider} 공급자명을 가져오는 메소드입니다.
- *
- * @return {@link BouncyCastleProvider} 공급자명
- */
- public static String getBCNormalProvider() {
- return _bcNormalProvider;
- }
-
- /**
- * 등록된 {@link BouncyCastlePQCProvider} 공급자명을 가져오는 메소드입니다.
- *
- * 구성에 {@code enabledExperimental} 옵션이 비활성화 되어있으면 해당 공급자를
- * 사용할 수 없습니다.
- *
- * @return {@link BouncyCastlePQCProvider} 공급자명, 구성 비활성화 시 {@code null}
- */
- public static @Nullable String getBCPQCProvider() {
- return _bcPQCProvider;
- }
-
- /**
- * 등록된 {@link BouncyCastleJsseProvider} 공급자명을 가져오는 메소드입니다.
- *
- * @return {@link BouncyCastleJsseProvider} 공급자명
- */
- public static String getBCJSSEProvider() {
- return _bcJSSEProvider;
- }
-
- /**
- * 최초 선언 후 변경되지 않는 보안 난수 생성기입니다.
- *
- * 보안 난수를 생성하기 위해 해당 상수만을 사용해야 합니다.
- *
- * {@code BouncyCastle} 라이브러리가 자동으로 최적의 소스(/dev/urandom, Fortuna/PRNG, Auto-seeding 등)를 선택합니다.
- */
- public static SecureRandom getSafeRandom() {
- return SAFE_RANDOM;
- }
-
- /**
- * 라이브러리의 공개 구성을 가져오는 메소드입니다.
- *
- * @return {@link PublicConfiguration} 인스턴스
- */
- public static PublicConfiguration getPublicConfig() {
- return Objects.requireNonNull(config, "public config");
- }
-
- /**
- * 지정된 이름의 보안 공급자가 등록되어 있지 않은지 확인하는 메소드입니다.
- *
- * @param provider 확인할 공급자 이름
- * @return 등록되어 있지 않으면 {@code true}, 그렇지 않으면 {@code false}
- */
- static boolean isNotBindingSecurityProvider(String provider) {
- return getSpecificProvider(provider) == null;
- }
-
- /**
- * 지정된 이름의 보안 공급자를 가져오는 메소드입니다.
- *
- * @param provider 가져올 공급자 이름
- * @return {@link Provider} 인스턴스, 없으면 {@code null}
- */
- static Provider getSpecificProvider(String provider) {
- return Security.getProvider(provider);
- }
-
- /**
- * BouncyCastle 보안 공급자를 JCA에 등록하는 메소드입니다.
- *
- * 일반, PQC, JSSE 공급자를 순서대로 등록하며, 실험적 기능 사용 여부에 따라 PQC 공급자 등록이 결정됩니다.
- * 멀티 스레드 환경에서의 안전한 등록을 위해 동기화 처리되었습니다.
- */
- static synchronized void setupSecurityProviders() {
- if (isNotBindingSecurityProvider(_bcNormalProvider)) {
- Security.addProvider(new BouncyCastleProvider());
- _bcNormalProvider = BouncyCastleProvider.PROVIDER_NAME;
- log.debug(lang.argsNonTopKey("setting-bc-provider", _bcNormalProvider));
- }
-
- // NOTE: 실험적 기능이 포함된 공급자는 테스트 시에만 사용
- if (getPublicConfig().isEnabledExperimental()) {
- if (isNotBindingSecurityProvider(_bcPQCProvider)) {
- Security.addProvider(new BouncyCastlePQCProvider());
- _bcPQCProvider = BouncyCastlePQCProvider.PROVIDER_NAME;
- log.debug(lang.argsNonTopKey("setting-bc-provider", _bcPQCProvider));
- }
- }
-
- if (isNotBindingSecurityProvider(_bcJSSEProvider)) {
- Security.addProvider(new BouncyCastleJsseProvider());
- _bcJSSEProvider = BouncyCastleJsseProvider.PROVIDER_NAME;
- log.debug(lang.argsNonTopKey("setting-bc-provider", _bcJSSEProvider));
- }
- }
-
- /**
- * {@link Signature} 객체에 평문 데이터를 업데이트하는 공통 메소드입니다.
- *
- * 대용량 데이터의 경우 청크 단위로 처리하며, 작은 데이터는 일반 업데이트를 수행합니다.
- * 이 메소드는 서명 생성 및 검증 과정에서 공통으로 사용됩니다.
- *
- * @param signature 업데이트할 Signature 객체
- * @param plain 업데이트할 평문 데이터
- * @param chunkSize 청크 크기 (0 이하인 경우 일반 처리)
- * @throws SignatureException 서명 업데이트 중 예외가 발생한 경우
- */
- private static void updateSignature(@NotNull Signature signature, byte @NotNull [] plain, int chunkSize) throws SignatureException {
- if (plain.length > 1023 && chunkSize > 0) {
- ByteArrayChunkProcessor.processInChunks(plain, chunkSize, signature::update);
- } else {
- signature.update(plain, 0, plain.length);
- }
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/WrapEnv.java b/src/main/java/space/qu4nt/entanglementlib/WrapEnv.java
deleted file mode 100644
index 0368033..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/WrapEnv.java
+++ /dev/null
@@ -1,67 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib;
-
-import lombok.AccessLevel;
-import lombok.Getter;
-import lombok.NoArgsConstructor;
-import lombok.Setter;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
-import space.qu4nt.entanglementlib.exception.critical.EntLibEnvError;
-import space.qu4nt.entanglementlib.util.StringUtil;
-
-import java.util.Optional;
-
-/**
- * {@code EntanglementLib}에서 사용되는 환경 변수를 래핑하는 추상 클래스입니다.
- *
- * 이 라이브러리의 환경 변수는 이 클래스의 인스턴스를 통해 호출이 이루어져야 합니다.
- *
- * @author Q. T. Felix
- * @since 1.0.0
- */
-@Getter(AccessLevel.PACKAGE)
-@Setter(AccessLevel.PACKAGE)
-@NoArgsConstructor
-sealed abstract class WrapEnv permits EntanglementLibEnvs {
-
- String env;
- boolean req;
-
- /**
- * 해당 환경변수 값의 {@code req} 필드가 {@code true}인 경우
- * 그 값은 {@code null}이면 안 됩니다. 이 메소드는 이러한 경우를 체크합니다.
- *
- * 해당 환경 변수의 기본값이 할당되어 있으며 {@code req} 필드가 {@code false}인 경우,
- * 할당된 기본값을 반환합니다.
- *
- * @param env 타겟 환경 변수
- * @param req 필수 여부
- * @param def 필수가 아니며 타겟 환경 변수가 {@code null}인 경우 반환값
- */
- WrapEnv(@NotNull String env, boolean req, @Nullable String def) {
- env = StringUtil.toUpperCase(env);
- Optional opt = Optional.ofNullable(System.getenv(env));
- if (opt.isPresent()) {
- this.env = opt.get();
- } else {
- if (req) error(env);
- if (def == null) error(env);
- this.env = def;
- }
- this.req = req;
- }
-
- /**
- * 런타임 예외를 발생시키는 메소드입니다.
- *
- * @param env 예외에 보여질 누락된 환경 변수 이름
- */
- static void error(String env) {
- throw new EntLibEnvError(env);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/entlibnative/NativeLinkerManager.java b/src/main/java/space/qu4nt/entanglementlib/entlibnative/NativeLinkerManager.java
deleted file mode 100644
index 2f21ad1..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/entlibnative/NativeLinkerManager.java
+++ /dev/null
@@ -1,174 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.entlibnative;
-
-import lombok.Getter;
-import lombok.Setter;
-import lombok.extern.slf4j.Slf4j;
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.InternalFactory;
-import space.qu4nt.entanglementlib.exception.critical.EntLibNativeError;
-
-import java.lang.foreign.*;
-import java.lang.invoke.MethodHandle;
-import java.nio.file.Files;
-import java.nio.file.Path;
-import java.util.ArrayList;
-import java.util.List;
-import java.util.Map;
-import java.util.Objects;
-import java.util.concurrent.ConcurrentHashMap;
-
-/// 얽힘 라이브러리 네이티브 라이브러리 브릿지를 위한 매니지먼트 클래스입니다.
-/// 해당 클래스는 [InternalFactory]를 통해 런타임에서 생성 후 변경되지
-/// 않습니다. 따라서 호출은 [#NativeLinkerManager(String)]가 아닌
-/// [InternalFactory#callNativeLib()] 메소드를 사용해야 합니다.
-///
-/// 이 클래스를 외부에서 사용한다면 사용자 설정된 네이티브를 호출할 수도
-/// 있지만, 이 클래스는 기본적으로 얽힘 라이브러리에서 `entlib-native`
-/// 라이브러리만이 호출됨을 예상합니다.
-///
-/// @author Q. T. Felix
-/// @since 1.1.0
-@Slf4j
-@Getter
-@Setter
-public class NativeLinkerManager {
-
- private static final String OS_NAME = System.getProperty("os.name").toLowerCase();
- private static final String OS_ARCH = System.getProperty("os.arch").toLowerCase();
-
- private final SymbolLookup lookup;
- private final Linker linker;
-
- private String libName;
- private Map handles;
-
- public NativeLinkerManager(final @NotNull String libName) {
- Objects.requireNonNull(libName);
- Path nativeDir = Path.of(InternalFactory.envEntLibNativeDir()).toAbsolutePath();
- Path lib = resolveNativeLibrary(nativeDir, libName);
- if (lib == null)
- throw new EntLibNativeError("네이티브 라이브러리 '" + libName + "'을(를) 찾을 수 없습니다! " +
- "(검색 경로: " + nativeDir + ", OS: " + OS_NAME + ", Arch: " + OS_ARCH + ")");
- this.libName = lib.getFileName().toString();
- log.debug("네이티브 라이브러리 로드: {}", lib);
- this.lookup = SymbolLookup.libraryLookup(lib, Arena.global());
- this.linker = Linker.nativeLinker();
- this.handles = new ConcurrentHashMap<>();
- }
-
- /// 현재 플랫폼과 아키텍처에 맞는 네이티브 라이브러리 파일을 찾는 메소드입니다.
- /// 검색 우선순위는 다음과 같습니다.
- ///
- /// 1. 정확한 이름 (예: libentlib_native.dylib)
- /// 2. 아키텍처 특정 이름 (예: libentlib_native_aarch64.dylib)
- /// 3. macOS의 경우 universal 바이너리 (예: libentlib_native_universal.dylib)
- ///
- /// @param nativeDir 바이너리 파일이 위치한 네이티브 디렉토리
- /// @param libName 네이티브 라이브러리명
- /// @return 특정된 바이너리 파일
- private static Path resolveNativeLibrary(@NotNull Path nativeDir, @NotNull String libName) {
- List candidates = generateCandidateNames(libName);
- for (String candidate : candidates) {
- Path path = nativeDir.resolve(candidate);
- if (Files.exists(path)) {
- return path;
- }
- }
- return null;
- }
-
- /// 플랫폼과 아키텍처에 따라 후보 파일명 목록을 생성하는 메소드입니다.
- private static List generateCandidateNames(@NotNull String libName) {
- List candidates = new ArrayList<>();
- String archSuffix = getArchitectureSuffix();
- String ext = getLibraryExtension();
- String prefix = getLibraryPrefix();
-
- // 1. 정확한 이름 (System.mapLibraryName과 동일)
- candidates.add(prefix + libName + ext);
-
- // 2. 아키텍처 특정 이름
- candidates.add(prefix + libName + "_" + archSuffix + ext);
-
- // 3. macOS의 경우 universal 바이너리
- if (isMacOS()) {
- candidates.add(prefix + libName + "_universal" + ext);
- }
-
- return candidates;
- }
-
- private static String getArchitectureSuffix() {
- if (OS_ARCH.contains("aarch64") || OS_ARCH.contains("arm64")) {
- return "aarch64";
- } else if (OS_ARCH.contains("amd64") || OS_ARCH.contains("x86_64")) {
- return "x86_64";
- } else if (OS_ARCH.contains("x86") || OS_ARCH.contains("i386") || OS_ARCH.contains("i686")) {
- return "i686";
- }
- return OS_ARCH;
- }
-
- private static String getLibraryExtension() {
- if (isMacOS()) return ".dylib";
- if (isWindows()) return ".dll";
- return ".so";
- }
-
- private static String getLibraryPrefix() {
- if (isWindows()) return "";
- return "lib";
- }
-
- private static boolean isMacOS() {
- return OS_NAME.contains("mac") || OS_NAME.contains("darwin");
- }
-
- private static boolean isWindows() {
- return OS_NAME.contains("win");
- }
-
- @NotNull
- public FunctionDescriptor descriptor(@NotNull MemoryLayout resLayout, MemoryLayout... argLayouts) {
- return FunctionDescriptor.of(resLayout, argLayouts);
- }
-
- @NotNull
- public FunctionDescriptor descriptorVoid(MemoryLayout... argLayouts) {
- return FunctionDescriptor.ofVoid(argLayouts);
- }
-
- @NotNull
- MethodHandle getLookup(@NotNull String name, FunctionDescriptor function) {
- return lookup.find(name)
- .map(symbol -> linker.downcallHandle(symbol, function))
- .orElseThrow(() -> new EntLibNativeError("네이티브 함수 '" + name + "'을(를) 찾을 수 없습니다!"));
- }
-
- /// static 블럭에서 사용해야함
- public NativeLinkerManager addVoidMethodHandle(@NotNull String name, MemoryLayout... argLayouts) {
- handles.put(name, getLookup(name, descriptorVoid(argLayouts)));
- log.debug("\t네이티브 함수 '{}'을(를) 연결했습니다.", name);
- return this;
- }
-
- /// static 블럭에서 사용해야함
- public NativeLinkerManager addReturnableMethodHandle(@NotNull String name, @NotNull MemoryLayout resLayout, MemoryLayout... argLayouts) {
- handles.put(name, getLookup(name, descriptor(resLayout, argLayouts)));
- log.debug("\t반환값을 가진 네이티브 함수 '{}'을(를) 연결했습니다.", name);
- return this;
- }
-
- @NotNull
- public MethodHandle getHandle(final @NotNull String name) {
- MethodHandle handle = handles.getOrDefault(name, null);
- if (handle == null)
- throw new EntLibNativeError("네이티브 함수 '" + name + "'을(를) 찾을 수 없습니다!");
- return handle;
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/entlibnative/ProgressResult.java b/src/main/java/space/qu4nt/entanglementlib/entlibnative/ProgressResult.java
deleted file mode 100644
index 6def668..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/entlibnative/ProgressResult.java
+++ /dev/null
@@ -1,35 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.entlibnative;
-
-import lombok.Getter;
-
-import java.util.Arrays;
-
-@Getter
-public enum ProgressResult {
-
- SUCCESS(0),
- CALC_FAILURE(-1),
- JUST_FAILURE(-2);
-
- private final int code;
-
- ProgressResult(int code) {
- this.code = code;
- }
-
- public boolean isFail() {
- return this.code != 0;
- }
-
- public static ProgressResult fromCode(final int code) {
- return Arrays.stream(ProgressResult.values())
- .filter(i -> i.getCode() == code)
- .findFirst()
- .orElseThrow();
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/entlibnative/SensitiveDataContainer.java b/src/main/java/space/qu4nt/entanglementlib/entlibnative/SensitiveDataContainer.java
deleted file mode 100644
index 8e6cbe4..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/entlibnative/SensitiveDataContainer.java
+++ /dev/null
@@ -1,335 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.entlibnative;
-
-import lombok.Getter;
-import lombok.extern.slf4j.Slf4j;
-import org.bouncycastle.util.encoders.Base64;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
-import org.jetbrains.annotations.Range;
-import space.qu4nt.entanglementlib.HeuristicArenaFactory;
-import space.qu4nt.entanglementlib.InternalFactory;
-import space.qu4nt.entanglementlib.Unsafe;
-import space.qu4nt.entanglementlib.exception.secure.EntLibSecureIllegalStateException;
-import space.qu4nt.entanglementlib.security.KeyDestroyHelper;
-
-import java.lang.foreign.Arena;
-import java.lang.foreign.MemorySegment;
-import java.lang.foreign.ValueLayout;
-import java.nio.ByteBuffer;
-import java.security.SecureRandom;
-import java.util.*;
-
-/// `Rust`의 소유권(ownership) 개념처럼 이 클래스도 전달받은 민감 정보에 대한 소유권을 가집니다.
-/// 이 클래스에 저장된 데이터는 진행중인 세션에 종속되고, 세션이 종료됨에 따라 모든 데이터가 완벽하게
-/// 소거됩니다. 데이터 소거는 `entlib-native`에서 진행됩니다.
-///
-/// [#SensitiveDataContainer(byte\[\], boolean)] 생성자를 사용하여 전달받은 바이트 배열
-/// 데이터에 대한 소유권을 이 클래스에 넘길지 결정할 수 있습니다. 논리 값이 `true`일 경우 데이터는
-/// 즉시 소거됩니다.
-///
-/// 이 컨테이너 클래스는 연쇄적으로 사용할 수 있습니다. [#bindings] 리스트는 하위(또는 동등)에
-/// 또 다른 컨테이너를 보관할 수 있도록 만들어졌습니다. 이 기능은 통신 구조에서, 세션에 연결된 각
-/// 통신 상대방에게 다양한 데이터를 함께 전송해야 할 때 용이합니다.
-///
-/// @author Q. T. Felix
-/// @see HeuristicArenaFactory
-/// @since 1.1.0
-@Slf4j
-public class SensitiveDataContainer implements AutoCloseable {
-
- @Getter
- private final Arena arena;
- @Getter
- private final MemorySegment memorySegment;
-
- /// 사용자가 인스턴스 생성에 전달한 바이트 배열 데이터
- private byte @Nullable [] fromData;
-
- /// 이 인스턴스가 통신 구조에서 사용되는 경우 통신 상대방에게
- /// 네이티브 메모리 세그먼트에 저장된 데이터를 직렬화하여
- /// 전달하기 위해 사용되는 바이트 배열 값입니다.
- ///
- /// 선언 시에는 `null` 상태를 가지며, 할당 후 이 데이터에
- /// 대한 소유권은 절대적으로 이 인스턴스가 가지게 됩니다.
- private byte @Nullable [] segmentData;
-
- /// 민감 데이터 컨테이너에 여러 데이터 컨테이너 바인딩
- /// 동시성 이슈 해결을 위해 동기적 리스트 선언
- ///
- /// # Solved Problems
- ///
- /// *`20250126` - race conditions*
- private final List bindings = Collections.synchronizedList(new ArrayList<>());
-
- /// 네이티브 메모리에 전달받은 정수 값(바이트 크기) 만큼의 메모리 세그먼트를
- /// 생성하여 이 인스턴스를 생성합니다.
- ///
- /// @param allocateSIze 바이트 크기
- public SensitiveDataContainer(final int allocateSIze) {
- this.arena = HeuristicArenaFactory.intelligenceCreateArena();
- this.memorySegment = Objects.requireNonNull(arena.allocate(allocateSIze));
- this.fromData = null;
- }
-
- /// 원본 바이트 배열을 전달받고 네이티브 메모리에 바인딩하여 이 인스턴스를 생성합니다.
- ///
- /// 생성 시점에 전달받은 원본 바이트 배열 데이터에 대한 소유권을 이 인스턴스에 넘길지 결정할 수
- /// 있습니다. 논리 값이 `true`일 경우 데이터는 즉시 소거되고, 이는 이 인스턴스가 소유권을
- /// 가질 필요가 없다는 것을 의미합니다.
- ///
- /// @param from 네이티브 메모리에 바인딩할 원본 바이트 배열
- /// @param forceWipe 인스턴스에 소유권 이전 여부
- public SensitiveDataContainer(final byte @NotNull [] from, boolean forceWipe) {
- this.arena = HeuristicArenaFactory.intelligenceCreateArena();
- this.memorySegment = Objects.requireNonNull(arena.allocateFrom(ValueLayout.JAVA_BYTE, from));
- if (forceWipe)
- KeyDestroyHelper.zeroing(from);
- else this.fromData = from;
- }
-
- /// 외부에서 생성된 컨테이너를 이 인스턴스의 하위 바인딩으로 추가하는 메소드입니다
- /// 동시성 안전성을 보장하기 위해 [#bindings] 리스트에 대한 락을 획득한 후 수행됩니다.
- ///
- /// @param container 하위로 종속시킬 컨테이너
- /// @return 추가된 컨테이너
- /// @throws EntLibSecureIllegalStateException 부모 컨테이너가 이미 소거된 경우
- public SensitiveDataContainer addContainerData(SensitiveDataContainer container)
- throws EntLibSecureIllegalStateException {
- synchronized (this.bindings) {
- if (!this.arena.scope().isAlive()) {
- // 이미 부모가 죽은 상태라면 추가하려는 자식도 고아 상태가 되지 않도록 예외 던짐
- throw new EntLibSecureIllegalStateException("이미 소거된 컨테이너에는 하위 데이터를 추가할 수 없습니다!");
- }
- this.bindings.add(container);
- return container;
- }
- }
-
- /// 새로운 크기만큼의 컨테이너를 생성하고 하위 바인딩으로 추가하는 메소드입니다
- ///
- /// @param allocateSIze 할당할 바이트 크기
- /// @return 생성 및 바인딩된 새 컨테이너
- public SensitiveDataContainer addContainerData(final int allocateSIze)
- throws EntLibSecureIllegalStateException {
- synchronized (this.bindings) {
- if (!this.arena.scope().isAlive()) {
- throw new EntLibSecureIllegalStateException("이미 소거된 컨테이너입니다!");
- }
- // lock 내부에서 생성 및 추가를 수행하여 원자성 보장
- SensitiveDataContainer s = new SensitiveDataContainer(allocateSIze);
- this.bindings.add(s);
- return s;
- }
- }
-
- /// 바이트 배열을 기반으로 컨테이너를 생성하고 하위 바인딩으로 추가하는 메소드입니다
- ///
- /// @param from 원본 바이트 배열
- /// @param forceWipe 원본 배열 소거 여부
- /// @return 생성 및 바인딩된 새 컨테이너
- public SensitiveDataContainer addContainerData(final byte @NotNull [] from, boolean forceWipe)
- throws EntLibSecureIllegalStateException {
- synchronized (this.bindings) {
- if (!this.arena.scope().isAlive()) {
- KeyDestroyHelper.zeroing(from);
- throw new EntLibSecureIllegalStateException("이미 소거된 컨테이너입니다! 이 예외가 발생했지만, 전달받은 바이트 배열은 소거되었습니다.");
- }
- SensitiveDataContainer s = new SensitiveDataContainer(from, forceWipe);
- this.bindings.add(s);
- return s;
- }
- }
-
- public Optional get(final int index) {
- try {
- return Optional.of(this.bindings.get(index));
- } catch (ArrayIndexOutOfBoundsException e) {
- log.error("인덱스 '{}'에 바인딩된 컨테이너가 없습니다!", index);
- }
- return Optional.empty();
- }
-
- /// 네이티브 메모리 세그먼트의 내용을 `heap` 메모리로 복사하는
- /// 메소드입니다.
- ///
- /// 복사된 데이터에 대한 소유권은 여전히 이 인스턴스가
- /// 가집니다. 인스턴스가 `try-with-resource` 블럭 내에서
- /// 사용될 경우 해당 값은 자동으로 소거됩니다.
- ///
- /// 이 메소드를 수행하면 [#segmentData] 변수를 통해
- /// 복사된 바이트 배열 데이터를 호출할 수 있습니다.
- ///
- /// # Unsafe
- ///
- /// 얽힘 라이브러리는 극한의 보안 환경을 중요시합니다. 이런 관점에서
- /// 해당 메소드는 다음의 딜레마에 빠지게 됩니다.
- ///
- /// > *어째서 안전한 `Off-Heap` 데이터를 다시 불안정한 `Java Heap`으로 복사하는가?*
- ///
- /// 이 메소드는 분명 편의성을 위한 기능이지만, Java Heap에 올라간 데이터는 GC가
- /// 동작하면서 메모리 위치를 옮길(Relocation) 수 있고, 이 과정에서 지워지지
- /// 않는 고아 복사본이 메모리 어딘가에 남을 수 있습니다.
- ///
- /// 따라서 얽힘 라이브러리의 보안 철학에 따라 이 메소드는 [`Unsafe`][Unsafe]
- /// 처리되며, 다음 릴리즈 공개 전에 제거하기로 결정했습니다.
- ///
- /// @see #getSegmentData() 복사 반환 메소드
- /// @see #getSegmentDataBase64() Base64 복사 반환 메소드
- /// @see #getSegmentDataToByteBuffer() ByteBuffer 복사 반환 메소드
- @Unsafe
- @Deprecated(forRemoval = true)
- public void exportData()
- throws EntLibSecureIllegalStateException {
- synchronized (this.bindings) {
- // 락 획득 후 생존 여부 확인 (check-then-act 보호)
- if (!arena.scope().isAlive()) {
- throw new EntLibSecureIllegalStateException("이미 소거된 컨테이너입니다!");
- }
- // 안전하게 데이터 복사
- this.segmentData = memorySegment.toArray(ValueLayout.JAVA_BYTE);
- }
- }
-
- /// `heap` 메모리에 복사된 데이터를 외부에서도 소거할 수 있도록 하는
- /// 메소드입니다.
- public void zeroingExportedData() {
- if (segmentData != null)
- KeyDestroyHelper.zeroing(segmentData);
- }
-
- /// `heap` 메모리에 복사된 네이티브 메모리 세그먼트 데이터의 복사본을
- /// 반환하는 메소드입니다.
- ///
- /// @return 네이티브 메모리 세그먼트 데이터의 바이트 배열 복사본
- public byte @Nullable [] getSegmentData() {
- return segmentData != null ? Arrays.copyOf(segmentData, segmentData.length) : null;
- }
-
- /// `heap` 메모리에 복사된 네이티브 메모리 세그먼트 데이터의 복사본을
- /// `Base64` 인코딩하여 반환하는 메소드입니다. 이 메소드는
- /// 직렬화에 용이합니다.
- ///
- /// 단순히 인코딩된 이 값을 직렬화할 수도 있지만, 보안상 추가적인
- /// 작업이 권장됩니다. 예를 들어, 이 값에 대칭키 암호화 연산을 수행할
- /// 수 있습니다.
- ///
- /// @return 직렬화된 네이티브 메모리 세그먼트 데이터의 바이트 배열 복사본
- public @Nullable String getSegmentDataBase64() {
- return getSegmentData() != null ? Base64.toBase64String(getSegmentData()) : null;
- }
-
- public ByteBuffer getSegmentDataToByteBuffer() {
- return memorySegment.asByteBuffer();
- }
-
- /// 인스턴스가 소유권을 가진 상태인 경우 해당 메소드를 사용하여 데이터의 복사본을 호출할 수
- /// 있습니다. 내부적으로 [Arrays#copyOf(byte\[\], int)]를 사용하여 사본을 반환합니다.
- ///
- /// @return 안전한 데이터 복사본
- public byte @Nullable [] getFromData() {
- return fromData != null ? Arrays.copyOf(fromData, fromData.length) : null;
- }
-
- /**
- * 암호학적으로 안전한 바이트 배열을 생성하는 메소드입니다.
- *
- * @param length 0 이상의 바이트 배열 사이즈
- * @return {@code Base64} 인코딩된 문자열
- */
- public static byte @NotNull [] generateSafeRandomBytes(@Range(from = 0, to = Integer.MAX_VALUE) int length) {
- final SecureRandom random = InternalFactory.getSafeRandom();
- final byte[] bytes = new byte[length];
- random.nextBytes(bytes);
- return bytes;
- }
-
- /**
- * 암호학적으로 안전한 {@code Base64} 인코딩된 문자열을 반환하는 메소드입니다.
- *
- * @param length 0 이상의 바이트 배열 사이즈
- * @return {@code Base64} 인코딩된 문자열
- */
- public static @NotNull String generateBase64String(@Range(from = 0, to = Integer.MAX_VALUE) int length) {
- return Base64.toBase64String(generateSafeRandomBytes(length));
- }
-
- @Override
- public void close() {
- // SECURE UPDATE: 20250126 - qtfelix
- // [Phase 1] 스냅샷 생성 및 연결 해제 (Critical Section 최소화)
- List snapshot;
- synchronized (bindings) {
- // 이미 닫힌 경우 빠른 종료 (Idempotency)
- if (!arena.scope().isAlive()) {
- log.warn("해당 스레드에서 이미 닫힌 컨테이너입니다.");
- return;
- }
-
- if (bindings.isEmpty()) {
- snapshot = Collections.emptyList();
- } else {
- // 방어적 복사: 리스트를 복제하고 원본은 즉시 비움
- snapshot = new ArrayList<>(bindings);
- bindings.clear();
- }
- } // 1차 락 해제: 이제 다른 스레드가 bindings에 접근해도 데드락이 발생하지 않음
-
- // [Phase 2] 하위 컨테이너 리소스 해제 (Open Call)
- // 락 바깥에서 수행하므로 자식 컨테이너가 부모를 다시 호출해도 안전함
- if (!snapshot.isEmpty()) {
- for (int i = snapshot.size() - 1; i >= 0; i--) {
- SensitiveDataContainer child = snapshot.get(i);
- try {
- child.close();
- } catch (Exception e) {
- log.error("하위 컨테이너 리소스 해제 중 예외가 발생했습니다!", e);
- }
- }
- }
-
- // [Phase 3] 네이티브 메모리 소거 및 최종 종료
- // 다시 락을 획득하여 [Phase 2] 도중에 추가된 데이터가 없는지 확인하고 소거
- synchronized (bindings) {
- // [Edge Case 방어] Phase 2 진행 중에 addContainerData가 호출되어
- // bindings에 새 데이터가 들어왔을 수 있음. 이를 확인하고 소거해야 함.
- if (!bindings.isEmpty()) {
- for (SensitiveDataContainer straggler : bindings) {
- try {
- straggler.close();
- } catch (Exception e) {
- log.error("지연 추가된 하위 컨테이너 해제 중 오류 발생", e);
- }
- }
- bindings.clear();
- }
-
- // Arena가 여전히 살아있는지 확인 후 소거 (Double Check)
- if (arena.scope().isAlive()) {
- try {
- // Rust Native Wipe 호출
- InternalFactory.callNativeLib()
- .getHandle("entanglement_secure_wipe")
- .invokeExact(memorySegment, memorySegment.byteSize());
- } catch (Throwable e) {
- log.error("치명적 보안 예외가 발생했습니다! (Native Wipe Failed)", e);
- }
-
- // Java Heap 데이터 소거
- if (fromData != null) {
- KeyDestroyHelper.zeroing(fromData);
- fromData = null; // GC Hint
- }
- zeroingExportedData();
- segmentData = null; // GC Hint
-
- // Arena 종료
- arena.close();
- }
- }
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/EntLibException.java b/src/main/java/space/qu4nt/entanglementlib/exception/EntLibException.java
deleted file mode 100644
index be3697b..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/EntLibException.java
+++ /dev/null
@@ -1,99 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.resource.language.LanguageInstanceBased;
-
-import java.io.Serial;
-
-/// 얽힘 라이브러리 전반에서 사용되는 기본 예외 클래스입니다.
-///
-/// 이 클래스는 [Exception]을 상속받으며, [LanguageInstanceBased]를 사용하여
-/// 다국어 메시지 처리를 지원합니다.
-///
-/// 이 클래스는 기본적으로 `Checked Exception`입니다. 확장하여 다양한 상황에 대해
-/// 예외 처리가 가능합니다.
-///
-/// @author Q. T. Felix
-/// @since 1.1.0
-public class EntLibException extends Exception {
-
- @Serial
- private static final long serialVersionUID = 2378593800480779310L;
-
- /**
- * 새로운 {@link EntLibException} 인스턴스를 생성하는 기본 생성자 메소드입니다.
- */
- public EntLibException() {
- super();
- }
-
- /**
- * 다국어 처리가 필요하지 않은 경우 이 인스턴스를 사용할 수 있습니다.
- *
- * @param message 메시지
- */
- public EntLibException(String message) {
- super(message);
- }
-
- /**
- * 발생한 예외만 넘기기 위해 이 인스턴스를 사용할 수 있습니다.
- *
- * @param cause 발생 예외
- */
- public EntLibException(Throwable cause) {
- super(cause);
- }
-
- /// 다국어 처리가 필요하지 않으며, 발생한 예외를 넘기기 위해 이
- /// 인스턴스를 사용할 수 있습니다.
- ///
- /// @param message 메시지
- /// @param cause 발생 예외
- public EntLibException(String message, Throwable cause) {
- super(message, cause);
- }
-
- /**
- * 지정된 클래스와 메시지 키를 사용하여 새로운 {@link EntLibException} 인스턴스를 생성하는 메소드입니다.
- *
- * {@link LanguageInstanceBased}를 통해 해당 클래스에 맞는 다국어 메시지를 조회합니다.
- *
- * @param i18nTargetClass 다국어 메시지 리소스를 조회할 대상 클래스
- * @param key 메시지 키 ({@code null}이 아니어야 함)
- * @param 대상 클래스의 타입
- */
- public EntLibException(Class i18nTargetClass, @NotNull String key) {
- super(LanguageInstanceBased.create(i18nTargetClass).msg(key));
- }
-
- /**
- * 지정된 클래스, 메시지 키, 그리고 원인 예외를 사용하여 새로운 {@link EntLibException} 인스턴스를 생성하는 메소드입니다.
- *
- * @param i18nTargetClass 다국어 메시지 리소스를 조회할 대상 클래스
- * @param key 메시지 키 ({@code null}이 아니어야 함)
- * @param cause 이 예외가 발생하게 된 원인 예외
- * @param 대상 클래스의 타입
- */
- public EntLibException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(LanguageInstanceBased.create(i18nTargetClass).thr(key, cause));
- }
-
- /**
- * 지정된 클래스, 메시지 키, 원인 예외, 그리고 포맷팅 인자들을 사용하여 새로운 {@link EntLibException} 인스턴스를 생성하는 메소드입니다.
- *
- * @param i18nTargetClass 다국어 메시지 리소스를 조회할 대상 클래스
- * @param key 메시지 키 ({@code null}이 아니어야 함)
- * @param cause 이 예외가 발생하게 된 원인 예외
- * @param args 메시지 포맷팅에 사용될 인자들
- * @param 대상 클래스의 타입
- */
- public EntLibException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(LanguageInstanceBased.create(i18nTargetClass).thr(key, cause, args));
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/EntLibUncheckedException.java b/src/main/java/space/qu4nt/entanglementlib/exception/EntLibUncheckedException.java
deleted file mode 100644
index 5fdd0e8..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/EntLibUncheckedException.java
+++ /dev/null
@@ -1,88 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.resource.language.LanguageInstanceBased;
-
-import java.io.Serial;
-
-/// 얽힘 라이브러리 전반에서 사용되는 기본 예외 클래스입니다.
-///
-/// 이 클래스는 [Exception]을 상속받으며, [LanguageInstanceBased]를 사용하여
-/// 다국어 메시지 처리를 지원합니다.
-///
-/// 이 클래스는 `Unchecked Exception`입니다.
-///
-/// @author Q. T. Felix
-/// @since 1.1.0
-public class EntLibUncheckedException extends RuntimeException {
-
- @Serial
- private static final long serialVersionUID = 2378593800480779310L;
-
- /**
- * 새로운 {@link EntLibUncheckedException} 인스턴스를 생성하는 기본 생성자 메소드입니다.
- */
- public EntLibUncheckedException() {
- }
-
- /**
- * 다국어 처리가 필요하지 않은 경우 이 인스턴스를 사용할 수 있습니다.
- *
- * @param message 메시지
- */
- public EntLibUncheckedException(String message) {
- super(message);
- }
-
- /**
- * 발생한 예외만 넘기기 위해 이 인스턴스를 사용할 수 있습니다.
- *
- * @param cause 발생 예외
- */
- public EntLibUncheckedException(Throwable cause) {
- super(cause);
- }
-
- /**
- * 지정된 클래스와 메시지 키를 사용하여 새로운 {@link EntLibUncheckedException} 인스턴스를 생성하는 메소드입니다.
- *
- * {@link LanguageInstanceBased}를 통해 해당 클래스에 맞는 다국어 메시지를 조회합니다.
- *
- * @param i18nTargetClass 다국어 메시지 리소스를 조회할 대상 클래스
- * @param key 메시지 키 ({@code null}이 아니어야 함)
- * @param 대상 클래스의 타입
- */
- public EntLibUncheckedException(Class i18nTargetClass, @NotNull String key) {
- super(LanguageInstanceBased.create(i18nTargetClass).msg(key));
- }
-
- /**
- * 지정된 클래스, 메시지 키, 그리고 원인 예외를 사용하여 새로운 {@link EntLibUncheckedException} 인스턴스를 생성하는 메소드입니다.
- *
- * @param i18nTargetClass 다국어 메시지 리소스를 조회할 대상 클래스
- * @param key 메시지 키 ({@code null}이 아니어야 함)
- * @param cause 이 예외가 발생하게 된 원인 예외
- * @param 대상 클래스의 타입
- */
- public EntLibUncheckedException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(LanguageInstanceBased.create(i18nTargetClass).thr(key, cause));
- }
-
- /**
- * 지정된 클래스, 메시지 키, 원인 예외, 그리고 포맷팅 인자들을 사용하여 새로운 {@link EntLibUncheckedException} 인스턴스를 생성하는 메소드입니다.
- *
- * @param i18nTargetClass 다국어 메시지 리소스를 조회할 대상 클래스
- * @param key 메시지 키 ({@code null}이 아니어야 함)
- * @param cause 이 예외가 발생하게 된 원인 예외
- * @param args 메시지 포맷팅에 사용될 인자들
- * @param 대상 클래스의 타입
- */
- public EntLibUncheckedException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(LanguageInstanceBased.create(i18nTargetClass).thr(key, cause, args));
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/critical/EntLibEnvError.java b/src/main/java/space/qu4nt/entanglementlib/exception/critical/EntLibEnvError.java
deleted file mode 100644
index 5bf9e85..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/critical/EntLibEnvError.java
+++ /dev/null
@@ -1,18 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.critical;
-
-import java.io.Serial;
-
-public class EntLibEnvError extends EntLibError {
-
- @Serial
- private static final long serialVersionUID = -4680763736515724771L;
-
- public EntLibEnvError(String envName) {
- super(envName + " env variables are missing");
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/critical/EntLibError.java b/src/main/java/space/qu4nt/entanglementlib/exception/critical/EntLibError.java
deleted file mode 100644
index e9a77fb..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/critical/EntLibError.java
+++ /dev/null
@@ -1,52 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.critical;
-
-/// 얽힘 라이브러리에서 발생하는 치명적인 오류를 나타내는 클래스입니다.
-///
-/// 이 클래스는 [Error]를 상속받으며, 복구할 수 없는 심각한 문제가 발생했을 때 사용됩니다.
-///
-/// @author Q. T. Felix
-/// @since 1.1.0
-public class EntLibError extends Error {
-
- /**
- * 새로운 {@link EntLibError} 인스턴스를 생성하는 기본 생성자 메소드입니다.
- */
- public EntLibError() {
- }
-
- /**
- * 지정된 상세 메시지를 사용하여 새로운 {@link EntLibError} 인스턴스를 생성하는 메소드입니다.
- *
- * @param message 상세 오류 메시지
- */
- public EntLibError(String message) {
- super(message);
- }
-
- /**
- * 지정된 상세 메시지와 원인 예외를 사용하여 새로운 {@link EntLibError} 인스턴스를 생성하는 메소드입니다.
- *
- * @param message 상세 오류 메시지
- * @param cause 이 오류가 발생하게 된 원인 ({@code null}이 허용됨)
- */
- public EntLibError(String message, Throwable cause) {
- super(message, cause);
- }
-
- /**
- * 지정된 원인 예외를 사용하여 새로운 {@link EntLibError} 인스턴스를 생성하는 메소드입니다.
- *
- * 상세 메시지는 {@code cause}가 {@code null}이 아닌 경우 {@code cause.toString()}의 결과로 설정됩니다.
- *
- *
- * @param cause 이 오류가 발생하게 된 원인 ({@code null}이 허용됨)
- */
- public EntLibError(Throwable cause) {
- super(cause);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/critical/EntLibNativeError.java b/src/main/java/space/qu4nt/entanglementlib/exception/critical/EntLibNativeError.java
deleted file mode 100644
index cd1507f..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/critical/EntLibNativeError.java
+++ /dev/null
@@ -1,22 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.critical;
-
-import java.io.Serial;
-
-public class EntLibNativeError extends EntLibError {
-
- @Serial
- private static final long serialVersionUID = -1665435182140213888L;
-
- public EntLibNativeError(String message) {
- super(message);
- }
-
- public EntLibNativeError(String message, Throwable cause) {
- super(message, cause);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/critical/EntLibSecurityError.java b/src/main/java/space/qu4nt/entanglementlib/exception/critical/EntLibSecurityError.java
deleted file mode 100644
index 52795d9..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/critical/EntLibSecurityError.java
+++ /dev/null
@@ -1,33 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.critical;
-
-import java.io.Serial;
-
-/// 이 에러는 보안 측면에서 큰 문제가 발생했거나, 시스템이 그렇게 예상할 때
-/// 사용됩니다.
-///
-/// # Safety
-///
-/// 이 에러가 발생한 경우 단순히 넘어가면 절대 안 됩니다. 얽힘 라이브러리의
-/// 시스템은 체계적이며, 치명적 에러를 던졌다 함은 단순히 내부적인 오류이기
-/// 보단 제3자의 의한 악의적인 수행일 수 있음을 의미합니다.
-///
-/// @author Q. T. Felix
-/// @since 1.1.0
-public class EntLibSecurityError extends EntLibError {
-
- @Serial
- private static final long serialVersionUID = -8998597327015285852L;
-
- private int[] codes;
-
- public EntLibSecurityError(String message) {
- // secure level 상승
- // JCA/JCE 공급자 전환
- super(message);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureCertProcessException.java b/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureCertProcessException.java
deleted file mode 100644
index 2838681..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureCertProcessException.java
+++ /dev/null
@@ -1,33 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.secure;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.exception.EntLibException;
-
-import java.io.Serial;
-
-public class EntLibSecureCertProcessException extends EntLibException {
-
- @Serial
- private static final long serialVersionUID = 3497403903418334407L;
-
- public EntLibSecureCertProcessException(Throwable cause) {
- super(cause);
- }
-
- public EntLibSecureCertProcessException(Class i18nTargetClass, @NotNull String key) {
- super(i18nTargetClass, key);
- }
-
- public EntLibSecureCertProcessException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(i18nTargetClass, key, cause);
- }
-
- public EntLibSecureCertProcessException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(i18nTargetClass, key, cause, args);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureException.java b/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureException.java
deleted file mode 100644
index 19b9565..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureException.java
+++ /dev/null
@@ -1,45 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.secure;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.exception.EntLibException;
-
-import java.io.Serial;
-
-public class EntLibSecureException extends EntLibException {
-
- @Serial
- private static final long serialVersionUID = -2452853243888606864L;
-
- public EntLibSecureException() {
- super();
- }
-
- public EntLibSecureException(String message) {
- super(message);
- }
-
- public EntLibSecureException(Throwable cause) {
- super(cause);
- }
-
- public EntLibSecureException(String message, Throwable cause) {
- super(message, cause);
- }
-
- public EntLibSecureException(Class i18nTargetClass, @NotNull String key) {
- super(i18nTargetClass, key);
- }
-
- public EntLibSecureException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(i18nTargetClass, key, cause);
- }
-
- public EntLibSecureException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(i18nTargetClass, key, cause, args);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureIllegalArgumentException.java b/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureIllegalArgumentException.java
deleted file mode 100644
index 1128dba..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureIllegalArgumentException.java
+++ /dev/null
@@ -1,41 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.secure;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.exception.EntLibException;
-
-import java.io.Serial;
-
-public class EntLibSecureIllegalArgumentException extends EntLibSecureException {
-
- @Serial
- private static final long serialVersionUID = -2452853243888606864L;
-
- public EntLibSecureIllegalArgumentException() {
- super();
- }
-
- public EntLibSecureIllegalArgumentException(String message) {
- super(message);
- }
-
- public EntLibSecureIllegalArgumentException(String message, Throwable cause) {
- super(message, cause);
- }
-
- public EntLibSecureIllegalArgumentException(Class i18nTargetClass, @NotNull String key) {
- super(i18nTargetClass, key);
- }
-
- public EntLibSecureIllegalArgumentException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(i18nTargetClass, key, cause);
- }
-
- public EntLibSecureIllegalArgumentException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(i18nTargetClass, key, cause, args);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureIllegalStateException.java b/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureIllegalStateException.java
deleted file mode 100644
index bfb6b8d..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureIllegalStateException.java
+++ /dev/null
@@ -1,37 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.secure;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.exception.EntLibException;
-
-import java.io.Serial;
-
-public class EntLibSecureIllegalStateException extends EntLibException {
-
- @Serial
- private static final long serialVersionUID = -5903209133861840394L;
-
- public EntLibSecureIllegalStateException() {
- super();
- }
-
- public EntLibSecureIllegalStateException(String message) {
- super(message);
- }
-
- public EntLibSecureIllegalStateException(Class i18nTargetClass, @NotNull String key) {
- super(i18nTargetClass, key);
- }
-
- public EntLibSecureIllegalStateException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(i18nTargetClass, key, cause);
- }
-
- public EntLibSecureIllegalStateException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(i18nTargetClass, key, cause, args);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureJCAJCEStoreProcessException.java b/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureJCAJCEStoreProcessException.java
deleted file mode 100644
index 56459ec..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSecureJCAJCEStoreProcessException.java
+++ /dev/null
@@ -1,33 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.secure;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.exception.EntLibException;
-
-import java.io.Serial;
-
-public class EntLibSecureJCAJCEStoreProcessException extends EntLibException {
-
- @Serial
- private static final long serialVersionUID = -1891654898835144441L;
-
- public EntLibSecureJCAJCEStoreProcessException(Throwable cause) {
- super(cause);
- }
-
- public EntLibSecureJCAJCEStoreProcessException(Class i18nTargetClass, @NotNull String key) {
- super(i18nTargetClass, key);
- }
-
- public EntLibSecureJCAJCEStoreProcessException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(i18nTargetClass, key, cause);
- }
-
- public EntLibSecureJCAJCEStoreProcessException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(i18nTargetClass, key, cause, args);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSensitiveDataException.java b/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSensitiveDataException.java
deleted file mode 100644
index 320aa3d..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/secure/EntLibSensitiveDataException.java
+++ /dev/null
@@ -1,33 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.secure;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.exception.EntLibException;
-
-import java.io.Serial;
-
-public class EntLibSensitiveDataException extends EntLibException {
-
- @Serial
- private static final long serialVersionUID = 6683621189466570305L;
-
- public EntLibSensitiveDataException() {
- super();
- }
-
- public EntLibSensitiveDataException(Class i18nTargetClass, @NotNull String key) {
- super(i18nTargetClass, key);
- }
-
- public EntLibSensitiveDataException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(i18nTargetClass, key, cause);
- }
-
- public EntLibSensitiveDataException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(i18nTargetClass, key, cause, args);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoCipherIllegalIVStateException.java b/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoCipherIllegalIVStateException.java
deleted file mode 100644
index e7c5130..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoCipherIllegalIVStateException.java
+++ /dev/null
@@ -1,33 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.secure.crypto;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.exception.EntLibException;
-
-import java.io.Serial;
-
-public class EntLibCryptoCipherIllegalIVStateException extends EntLibCryptoCipherProcessException {
-
- @Serial
- private static final long serialVersionUID = -1818319588140211117L;
-
- public EntLibCryptoCipherIllegalIVStateException(String message) {
- super(message);
- }
-
- public EntLibCryptoCipherIllegalIVStateException(Class i18nTargetClass, @NotNull String key) {
- super(i18nTargetClass, key);
- }
-
- public EntLibCryptoCipherIllegalIVStateException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(i18nTargetClass, key, cause);
- }
-
- public EntLibCryptoCipherIllegalIVStateException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(i18nTargetClass, key, cause, args);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoCipherProcessException.java b/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoCipherProcessException.java
deleted file mode 100644
index 923bd19..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoCipherProcessException.java
+++ /dev/null
@@ -1,41 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.secure.crypto;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.exception.EntLibException;
-
-import java.io.Serial;
-
-public class EntLibCryptoCipherProcessException extends EntLibException {
-
- @Serial
- private static final long serialVersionUID = 2560472028225459178L;
-
- public EntLibCryptoCipherProcessException(Throwable cause) {
- super(cause);
- }
-
- public EntLibCryptoCipherProcessException(String message) {
- super(message);
- }
-
- public EntLibCryptoCipherProcessException(String message, Throwable cause) {
- super(message, cause);
- }
-
- public EntLibCryptoCipherProcessException(Class i18nTargetClass, @NotNull String key) {
- super(i18nTargetClass, key);
- }
-
- public EntLibCryptoCipherProcessException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(i18nTargetClass, key, cause);
- }
-
- public EntLibCryptoCipherProcessException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(i18nTargetClass, key, cause, args);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoException.java b/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoException.java
deleted file mode 100644
index 9d485e0..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoException.java
+++ /dev/null
@@ -1,33 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.secure.crypto;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.exception.EntLibException;
-
-import java.io.Serial;
-
-public class EntLibCryptoException extends EntLibException {
-
- @Serial
- private static final long serialVersionUID = 7785037773312632659L;
-
- public EntLibCryptoException(Throwable cause) {
- super(cause);
- }
-
- public EntLibCryptoException(Class i18nTargetClass, @NotNull String key) {
- super(i18nTargetClass, key);
- }
-
- public EntLibCryptoException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(i18nTargetClass, key, cause);
- }
-
- public EntLibCryptoException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(i18nTargetClass, key, cause, args);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoKEMProcessingException.java b/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoKEMProcessingException.java
deleted file mode 100644
index 712e9b5..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoKEMProcessingException.java
+++ /dev/null
@@ -1,37 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.secure.crypto;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.exception.EntLibException;
-
-import java.io.Serial;
-
-public class EntLibCryptoKEMProcessingException extends EntLibException {
-
- @Serial
- private static final long serialVersionUID = 6227897663782430821L;
-
- public EntLibCryptoKEMProcessingException(String message) {
- super(message);
- }
-
- public EntLibCryptoKEMProcessingException(String message, Throwable cause) {
- super(message, cause);
- }
-
- public EntLibCryptoKEMProcessingException(Class i18nTargetClass, @NotNull String key) {
- super(i18nTargetClass, key);
- }
-
- public EntLibCryptoKEMProcessingException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(i18nTargetClass, key, cause);
- }
-
- public EntLibCryptoKEMProcessingException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(i18nTargetClass, key, cause, args);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoSignatureProcessingException.java b/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoSignatureProcessingException.java
deleted file mode 100644
index 25cca03..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoSignatureProcessingException.java
+++ /dev/null
@@ -1,37 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.secure.crypto;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.exception.EntLibException;
-
-import java.io.Serial;
-
-public class EntLibCryptoSignatureProcessingException extends EntLibException {
-
- @Serial
- private static final long serialVersionUID = 951548478208181292L;
-
- public EntLibCryptoSignatureProcessingException(String message) {
- super(message);
- }
-
- public EntLibCryptoSignatureProcessingException(String message, Throwable cause) {
- super(message, cause);
- }
-
- public EntLibCryptoSignatureProcessingException(Class i18nTargetClass, @NotNull String key) {
- super(i18nTargetClass, key);
- }
-
- public EntLibCryptoSignatureProcessingException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(i18nTargetClass, key, cause);
- }
-
- public EntLibCryptoSignatureProcessingException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(i18nTargetClass, key, cause, args);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoStreamCipherProcessException.java b/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoStreamCipherProcessException.java
deleted file mode 100644
index 7a77f48..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/secure/crypto/EntLibCryptoStreamCipherProcessException.java
+++ /dev/null
@@ -1,37 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.secure.crypto;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.exception.EntLibException;
-
-import java.io.Serial;
-
-public class EntLibCryptoStreamCipherProcessException extends EntLibException {
-
- @Serial
- private static final long serialVersionUID = 8751428890964444674L;
-
- public EntLibCryptoStreamCipherProcessException(Throwable cause) {
- super(cause);
- }
-
- public EntLibCryptoStreamCipherProcessException(String message, Throwable cause) {
- super(message, cause);
- }
-
- public EntLibCryptoStreamCipherProcessException(Class i18nTargetClass, @NotNull String key) {
- super(i18nTargetClass, key);
- }
-
- public EntLibCryptoStreamCipherProcessException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(i18nTargetClass, key, cause);
- }
-
- public EntLibCryptoStreamCipherProcessException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(i18nTargetClass, key, cause, args);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/server/EntLibServerException.java b/src/main/java/space/qu4nt/entanglementlib/exception/server/EntLibServerException.java
deleted file mode 100644
index b948faf..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/server/EntLibServerException.java
+++ /dev/null
@@ -1,34 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.server;
-
-import space.qu4nt.entanglementlib.exception.EntLibException;
-import space.qu4nt.entanglementlib.security.communication.session.Session;
-
-import java.io.Serial;
-
-/// 서버 관련 예외를 나타내는 클래스입니다.
-///
-/// @author Q. T. Felix
-/// @see Session
-/// @since 1.1.0
-public class EntLibServerException extends EntLibException {
-
- @Serial
- private static final long serialVersionUID = 9158866932313942233L;
-
- public EntLibServerException(String message) {
- super(message);
- }
-
- public EntLibServerException(Throwable cause) {
- super(cause);
- }
-
- public EntLibServerException(String message, Throwable cause) {
- super(message, cause);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/server/EntLibServerIllegalStateException.java b/src/main/java/space/qu4nt/entanglementlib/exception/server/EntLibServerIllegalStateException.java
deleted file mode 100644
index d83c307..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/server/EntLibServerIllegalStateException.java
+++ /dev/null
@@ -1,32 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.server;
-
-import space.qu4nt.entanglementlib.exception.EntLibException;
-import space.qu4nt.entanglementlib.security.communication.session.Session;
-
-import java.io.Serial;
-
-/// @author Q. T. Felix
-/// @see Session
-/// @since 1.1.0
-public class EntLibServerIllegalStateException extends EntLibException {
-
- @Serial
- private static final long serialVersionUID = 709411898221020869L;
-
- public EntLibServerIllegalStateException(String message) {
- super(message);
- }
-
- public EntLibServerIllegalStateException(Throwable cause) {
- super(cause);
- }
-
- public EntLibServerIllegalStateException(String message, Throwable cause) {
- super(message, cause);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/server/EntLibServerSecurityWarningException.java b/src/main/java/space/qu4nt/entanglementlib/exception/server/EntLibServerSecurityWarningException.java
deleted file mode 100644
index 2170be4..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/server/EntLibServerSecurityWarningException.java
+++ /dev/null
@@ -1,33 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.server;
-
-import space.qu4nt.entanglementlib.exception.EntLibException;
-
-import java.io.Serial;
-
-/// 이 예외는 서버의 보안 측면에서 큰 문제가 발생했거나, 시스템이 그렇게 예상할 때
-/// 사용됩니다.
-///
-/// # Safety
-///
-/// 이 예외가 발생한 경우, 발생한 문제가 얽힘 라이브러리에 의해 1차적으로 막혔다는
-/// 것을 의미합니다. 문제에 대해 방어되었지만, 서버의 보안 점검잉 긴급한 상황일 수
-/// 있습니다.
-///
-/// 이 예외가 발생한다고 해서 서버가 종료되지는 않습니다.
-///
-/// @author Q. T. Felix
-/// @since 1.1.0
-public class EntLibServerSecurityWarningException extends EntLibServerException {
-
- @Serial
- private static final long serialVersionUID = -9043595617089057163L;
-
- public EntLibServerSecurityWarningException(String type, String message) {
- super("[SERVER-SECURITY-WARNING] '" + type + "' 감지, 메시지: " + message);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/session/EntLibSessionException.java b/src/main/java/space/qu4nt/entanglementlib/exception/session/EntLibSessionException.java
deleted file mode 100644
index 4dc4a4b..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/session/EntLibSessionException.java
+++ /dev/null
@@ -1,37 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.session;
-
-import space.qu4nt.entanglementlib.exception.EntLibException;
-import space.qu4nt.entanglementlib.security.communication.session.Session;
-
-import java.io.Serial;
-
-/// 세션 관련 예외를 나타내는 클래스입니다.
-///
-/// 세션 생성, 참여자 관리, 상태 전환 등에서 발생할 수 있는
-/// 예외 상황을 처리합니다.
-///
-/// @author Q. T. Felix
-/// @see Session
-/// @since 1.1.0
-public class EntLibSessionException extends EntLibException {
-
- @Serial
- private static final long serialVersionUID = -4075244968782759826L;
-
- public EntLibSessionException(String message) {
- super(message);
- }
-
- public EntLibSessionException(Throwable cause) {
- super(cause);
- }
-
- public EntLibSessionException(String message, Throwable cause) {
- super(message, cause);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/session/EntLibSessionIllegalStateException.java b/src/main/java/space/qu4nt/entanglementlib/exception/session/EntLibSessionIllegalStateException.java
deleted file mode 100644
index 6a805ab..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/session/EntLibSessionIllegalStateException.java
+++ /dev/null
@@ -1,37 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.session;
-
-import space.qu4nt.entanglementlib.exception.EntLibException;
-import space.qu4nt.entanglementlib.security.communication.session.Session;
-
-import java.io.Serial;
-
-/// 세션 관련 예외를 나타내는 클래스입니다.
-///
-/// 세션 생성, 참여자 관리, 상태 전환 등에서 발생할 수 있는
-/// 예외 상황을 처리합니다.
-///
-/// @author Q. T. Felix
-/// @see Session
-/// @since 1.1.0
-public class EntLibSessionIllegalStateException extends EntLibException {
-
- @Serial
- private static final long serialVersionUID = 4840174130643612125L;
-
- public EntLibSessionIllegalStateException(String message) {
- super(message);
- }
-
- public EntLibSessionIllegalStateException(Throwable cause) {
- super(cause);
- }
-
- public EntLibSessionIllegalStateException(String message, Throwable cause) {
- super(message, cause);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/util/EntLibUtilityException.java b/src/main/java/space/qu4nt/entanglementlib/exception/util/EntLibUtilityException.java
deleted file mode 100644
index 3f9821c..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/util/EntLibUtilityException.java
+++ /dev/null
@@ -1,29 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.util;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.exception.EntLibUncheckedException;
-
-import java.io.Serial;
-
-public class EntLibUtilityException extends EntLibUncheckedException {
-
- @Serial
- private static final long serialVersionUID = -162263763510190731L;
-
- public EntLibUtilityException(Class i18nTargetClass, @NotNull String key) {
- super(i18nTargetClass, key);
- }
-
- public EntLibUtilityException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(i18nTargetClass, key, cause);
- }
-
- public EntLibUtilityException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(i18nTargetClass, key, cause, args);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/exception/util/EntLibUtilityIllegalArgumentException.java b/src/main/java/space/qu4nt/entanglementlib/exception/util/EntLibUtilityIllegalArgumentException.java
deleted file mode 100644
index 005e582..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/exception/util/EntLibUtilityIllegalArgumentException.java
+++ /dev/null
@@ -1,29 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.exception.util;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.exception.EntLibUncheckedException;
-
-import java.io.Serial;
-
-public class EntLibUtilityIllegalArgumentException extends EntLibUncheckedException {
-
- @Serial
- private static final long serialVersionUID = -162263763510190731L;
-
- public EntLibUtilityIllegalArgumentException(Class i18nTargetClass, @NotNull String key) {
- super(i18nTargetClass, key);
- }
-
- public EntLibUtilityIllegalArgumentException(Class i18nTargetClass, @NotNull String key, Throwable cause) {
- super(i18nTargetClass, key, cause);
- }
-
- public EntLibUtilityIllegalArgumentException(Class i18nTargetClass, @NotNull String key, Throwable cause, Object... args) {
- super(i18nTargetClass, key, cause, args);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/experimental/package-info.java b/src/main/java/space/qu4nt/entanglementlib/experimental/package-info.java
deleted file mode 100644
index 37a278a..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/experimental/package-info.java
+++ /dev/null
@@ -1,13 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-/// 해당 패키지는 얽힘 라이브러리 내에서 연구중이지만 사용 가능한 타입을
-/// 모아둔 패키지입니다. 해당 패키지 하위의 타입은 기본적으로 사용을
-/// 권장하지 않습니다. 사용 후 피드백을 적극적으로 받고, 픽스하기 위한
-/// 목적으로 사용되고 만들어집니다.
-///
-/// @author Q. T. Felix
-/// @since 1.0.0
-package space.qu4nt.entanglementlib.experimental;
\ No newline at end of file
diff --git a/src/main/java/space/qu4nt/entanglementlib/resource/ResourceCaller.java b/src/main/java/space/qu4nt/entanglementlib/resource/ResourceCaller.java
deleted file mode 100644
index 58ed30e..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/resource/ResourceCaller.java
+++ /dev/null
@@ -1,156 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.resource;
-
-import lombok.extern.slf4j.Slf4j;
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.InternalFactory;
-import space.qu4nt.entanglementlib.resource.control.PublicJSONFileSystemResourceBundleControl;
-import space.qu4nt.entanglementlib.resource.control.PublicYamlFileSystemResourceBundleControl;
-import space.qu4nt.entanglementlib.util.io.EntFile;
-import tools.jackson.core.JsonParser;
-import tools.jackson.databind.ObjectMapper;
-import tools.jackson.databind.ObjectReader;
-
-import java.io.IOException;
-import java.io.InputStream;
-import java.nio.charset.Charset;
-import java.nio.file.Files;
-import java.nio.file.Path;
-import java.nio.file.Paths;
-import java.util.Locale;
-import java.util.MissingResourceException;
-import java.util.ResourceBundle;
-
-/**
- * 리소스 번들의 소스를 관리하는 클래스입니다.
- *
- * @author Q. T. Felix
- * @since 1.0.0
- */
-@Slf4j
-public final class ResourceCaller {
-
- /**
- * 프로젝트가 사용하는 리소스 번들의 경로를 사용자 지정하고자 하는 경우에
- * 사용되는 메소드입니다.
- *
- * @param format 리소스 파일 포멧(확장자)
- * @param customDirStringPath 리소스 디렉토리
- * @param baseName 리소스 디렉토리에 포함된 리소스 (확장자 없는) 파일 이름
- * @param streamCharset 리소스 로드에 사용할 {@link Charset}
- * @return 지정된 경로의 파일로 정의된 {@link ResourceBundle}
- */
- public static ResourceBundle getCustomResourceBundle(final SupportedFormat format, final String customDirStringPath, final String baseName, Charset streamCharset) {
- try {
- Path path = Paths.get(customDirStringPath);
- Files.createDirectories(path);
- } catch (IOException e) {
- throw new RuntimeException(e);
- }
- ResourceBundle.Control ctrl =
- switch (format) {
- case YAML -> new PublicYamlFileSystemResourceBundleControl(customDirStringPath, streamCharset);
- case JSON -> new PublicJSONFileSystemResourceBundleControl(customDirStringPath, streamCharset);
- };
- ResourceBundle bundle = ResourceBundle.getBundle(baseName, Locale.getDefault(), ctrl);
- // NOTE: 어째서 파일은 있고 엔트리가 없어도 MissingResourceException 예외가 발생하는 것인가? null 체크가 의미 없는 것인가...?
- if (bundle == null)
- throw new MissingResourceException(baseName, customDirStringPath, null);
- if (bundle.getKeys().nextElement() == null)
- log.warn("No keys found in {}", baseName);
- return bundle;
- }
-
- /**
- * 프로젝트가 사용하는 리소스 번들의 경로를 사용자 지정된 디렉토리로 결정하고,
- * 리소스 파일을 사용자 지정하고자 하는 경우에 사용되는 메소드입니다.
- *
- * 디렉토리를 설정하기 위해 {@code ENTANGLEMENT_PUBLIC_DIR} 환경 변수에 사용자 지정된
- * 디렉토리 위치를 정의해야 합니다.
- *
- * @param baseName 리소스 디렉토리에 포함된 리소스 (확장자 없는) 파일 이름
- * @param streamCharset 리소스 로드에 사용할 {@link Charset}
- * @return 지정된 경로의 파일로 정의된 {@link ResourceBundle}
- */
- public static ResourceBundle getCustomResourceInPublic(final SupportedFormat format, final String baseName, Charset streamCharset) {
- return getCustomResourceBundle(format, InternalFactory.envEntanglementPublicDir(), baseName, streamCharset);
- }
-
- /**
- * 프로젝트가 사용하는 리소스 번들의 경로를 사용자 지정된 디렉토리 하위에서
- * 사용자 지정하고자 하는 경우에 사용되는 메소드입니다.
- *
- * 디렉토리를 설정하기 위해 {@code ENTANGLEMENT_PUBLIC_DIR} 환경 변수에 사용자 지정된
- * 디렉토리 위치를 정의해야 합니다.
- *
- * @param inPublicDirName 공개 디렉토리 내의 하위 디렉토리 이름
- * @param baseName 디렉토리 하위에 포함된 리소스 (확장자 없는) 파일 이름
- * @param streamCharset 리소스 로드에 사용할 {@link Charset}
- * @return 지정된 경로의 파일로 정의된 {@link ResourceBundle}
- */
- public static ResourceBundle getCustomResourceInPublicInnerDir(final SupportedFormat format, final String inPublicDirName, final String baseName, Charset streamCharset) {
- String path = Paths.get(InternalFactory.envEntanglementPublicDir()).resolve(inPublicDirName).toString();
- return getCustomResourceBundle(format, path, baseName, streamCharset);
- }
-
- /**
- * 지정된 공개 디렉토리 하위 파일을 Jackson 라이브러리를 사용하여 역직렬화합니다.
- * 이 메소드는 파일의 복합 보안 검증(트래버셜, 무결성)을 수행하지 않습니다.
- *
- * @param mapper 사용할 {@link ObjectMapper} 인스턴스
- * @param filename 디렉토리 하위에 포함된 역직렬화할 파일 이름
- * @param ref 역직렬화될 객체의 {@link Class} 타입
- * @param 역직렬화될 객체의 타입
- * @return 역직렬화된 객체
- * @throws IOException 읽기 작업 중 문제가 발생한 경우
- */
- public static T jacksonDeserializeInPublic(@NotNull ObjectMapper mapper, final @NotNull String filename, @NotNull Class ref)
- throws IOException {
- Path filePath = Paths.get(InternalFactory.envEntanglementPublicDir()).resolve(filename);
- try (InputStream is = EntFile.Unchecked.openStream(filePath)) {
- return deserializeWithStream(mapper, is, ref);
- }
- }
-
- /**
- * 지정된 공개 디렉토리 하위 디렉토리의 파일을 Jackson 라이브러리를 사용하여 역직렬화합니다.
- * 이 메소드는 파일의 복합 보안 검증(트래버셜, 무결성)을 수행하지 않습니다.
- *
- * @param mapper 사용할 {@link ObjectMapper} 인스턴스
- * @param inPublicDirName 공개 디렉토리 내의 하위 디렉토리 이름
- * @param filename 디렉토리 하위에 포함된 역직렬화할 파일 이름
- * @param ref 역직렬화될 객체의 {@link Class} 타입
- * @param 역직렬화될 객체의 타입
- * @return 역직렬화된 객체
- * @throws IOException 읽기 작업 중 문제가 발생한 경우
- */
- public static T jacksonDeserializeInPublicInnerDir(@NotNull ObjectMapper mapper, @NotNull String inPublicDirName, @NotNull String filename, @NotNull Class ref)
- throws IOException {
- Path filePath = Paths.get(InternalFactory.envEntanglementPublicDir()).resolve(inPublicDirName).resolve(filename);
- try (InputStream is = EntFile.Unchecked.openStream(filePath)) {
- return deserializeWithStream(mapper, is, ref);
- }
- }
-
- /**
- * {@link InputStream}에서 데이터를 읽어와 Jackson 라이브러리를 사용하여 역직렬화합니다.
- * 이 메소드는 스트림을 효율적으로 처리하며, 전체 내용을 메모리에 로드하지 않습니다.
- *
- * @param mapper 사용할 {@link ObjectMapper} 인스턴스
- * @param inputStream 역직렬화할 데이터의 입력 스트림
- * @param ref 역직렬화될 객체의 {@link Class} 타입
- * @param 역직렬화될 객체의 타입
- * @return 역직렬화된 객체
- */
- private static T deserializeWithStream(ObjectMapper mapper, InputStream inputStream, Class ref) {
- ObjectReader reader = mapper.readerFor(ref);
- // JsonParser가 InputStream을 소비함 (전체 로드 X)
- try (JsonParser parser = mapper.createParser(inputStream)) {
- return reader.readValue(parser);
- }
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/resource/ResourceHandler.java b/src/main/java/space/qu4nt/entanglementlib/resource/ResourceHandler.java
deleted file mode 100644
index d18c061..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/resource/ResourceHandler.java
+++ /dev/null
@@ -1,83 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.resource;
-
-import lombok.Getter;
-import lombok.Setter;
-import org.jetbrains.annotations.NotNull;
-
-import java.nio.charset.Charset;
-import java.util.*;
-
-public abstract class ResourceHandler extends ResourceBundle.Control {
-
- @Setter
- @Getter
- protected Charset streamCharset;
-
- private final List formats;
-
- public ResourceHandler(Charset streamCharset, final List formats) {
- this.streamCharset = streamCharset;
- this.formats = formats;
- }
-
- @Override
- public List getFormats(String baseName) {
- return formats;
- }
-
- /**
- * 중첩된 Map을 평평한 키-값 구조로 변환하는 헬퍼 메소드입니다.
- *
- * {@code YAML} 형식의 파일인 경우, 계층 구조를 받아 {@code .}으로
- * 구분하기 위해 사용됩니다.
- *
- * @param map 타겟 Map
- * @param prefix 접두사
- * @return 평평한 키-값 구조 Map
- */
- public Map flattenMap(Map map, String prefix) {
- Map flat = new HashMap<>();
- for (Map.Entry entry : map.entrySet()) {
- String key = prefix.isEmpty() ? entry.getKey() : prefix + "." + entry.getKey();
- Object value = entry.getValue();
- if (value instanceof Map) {
- @SuppressWarnings("unchecked")
- Map nestedMap = (Map) value;
- flat.putAll(flattenMap(nestedMap, key));
- } else {
- flat.put(key, value);
- }
- }
- return flat;
- }
-
- /**
- * YAML 데이터를 위한 커스텀 {@link ResourceBundle} 구현체 클래스입니다.
- *
- * @author Q. T. Felix
- * @since 1.0.0
- */
- public static class YamlResourceBundle extends ResourceBundle {
- private final Map map;
-
- public YamlResourceBundle(Map map) {
- this.map = map;
- }
-
- @Override
- protected Object handleGetObject(@NotNull String key) {
- return map.get(key);
- }
-
- @Override
- public @NotNull Enumeration getKeys() {
- return Collections.enumeration(map.keySet());
- }
- }
-
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/resource/SupportedFormat.java b/src/main/java/space/qu4nt/entanglementlib/resource/SupportedFormat.java
deleted file mode 100644
index 9b36828..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/resource/SupportedFormat.java
+++ /dev/null
@@ -1,11 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.resource;
-
-public enum SupportedFormat {
- YAML,
- JSON
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/resource/config/Configer.java b/src/main/java/space/qu4nt/entanglementlib/resource/config/Configer.java
deleted file mode 100644
index de80fa0..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/resource/config/Configer.java
+++ /dev/null
@@ -1,195 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.resource.config;
-
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
-import tools.jackson.databind.JavaType;
-import tools.jackson.databind.ObjectMapper;
-
-import java.util.Collections;
-import java.util.List;
-import java.util.ResourceBundle;
-
-/**
- * 구성 파일에서 값을 읽어오는 유틸리티 클래스입니다.
- *
- * @author Q. T. Felix
- * @since 1.0.0
- */
-public final class Configer {
-
- private static final ObjectMapper MAPPER = new ObjectMapper();
-
- /**
- * 구성에서 정수 값을 불러오는 메소드입니다.
- *
- * @param bundle 기반 리소스 번들
- * @param key 불러오고자 하는 값의 경로
- * @param def 키를 찾을 수 없는 경우의 반환값
- * @return 경로에 위치한 정수 값, 키를 찾을 수 없으면 전달된 기본 값
- */
- public static int getInt(final @NotNull ResourceBundle bundle, final String key, int def) {
- return bundle.containsKey(key) ? (int) bundle.getObject(key) : def;
- }
-
- /**
- * 구성에서 정수 값을 불러오는 메소드입니다.
- *
- * @param bundle 기반 리소스 번들
- * @param key 불러오고자 하는 값의 경로
- * @return 경로에 위치한 정수 값, 키를 찾을 수 없으면 {@code -1}
- */
- public static int getInt(final @NotNull ResourceBundle bundle, final String key) {
- return getInt(bundle, key, -1);
- }
-
- /**
- * 구성에서 {@code double} 실수 값을 불러오는 메소드입니다.
- *
- * @param bundle 기반 리소스 번들
- * @param key 불러오고자 하는 값의 경로
- * @param def 키를 찾을 수 없는 경우의 반환값
- * @return 경로에 위치한 {@code double} 실수 값, 키를 찾을 수 없으면 전달된 기본 값
- */
- public static double getDouble(final @NotNull ResourceBundle bundle, final String key, double def) {
- return bundle.containsKey(key) ? (double) bundle.getObject(key) : def;
- }
-
- /**
- * 구성에서 {@code double} 실수 값을 불러오는 메소드입니다.
- *
- * @param bundle 기반 리소스 번들
- * @param key 불러오고자 하는 값의 경로
- * @return 경로에 위치한 {@code double} 실수 값, 키를 찾을 수 없으면 {@code -1}
- */
- public static double getDouble(final @NotNull ResourceBundle bundle, final String key) {
- return getDouble(bundle, key, -1);
- }
-
- /**
- * 구성에서 {@code float} 실수 값을 불러오는 메소드입니다.
- *
- * @param bundle 기반 리소스 번들
- * @param key 불러오고자 하는 값의 경로
- * @param def 키를 찾을 수 없는 경우의 반환값
- * @return 경로에 위치한 {@code float} 실수 값, 키를 찾을 수 없으면 전달된 기본 값
- */
- public static float getFloat(final @NotNull ResourceBundle bundle, final String key, float def) {
- return bundle.containsKey(key) ? (float) bundle.getObject(key) : def;
- }
-
- /**
- * 구성에서 {@code float} 실수 값을 불러오는 메소드입니다.
- *
- * @param bundle 기반 리소스 번들
- * @param key 불러오고자 하는 값의 경로
- * @return 경로에 위치한 {@code float} 실수 값, 키를 찾을 수 없으면 {@code -1}
- */
- public static float getFloat(final @NotNull ResourceBundle bundle, final String key) {
- return getFloat(bundle, key, -1);
- }
-
- /**
- * 구성에서 논리 값을 불러오는 메소드입니다.
- *
- * @param bundle 기반 리소스 번들
- * @param key 불러오고자 하는 값의 경로
- * @return 경로에 위치한 논리 값, 키를 찾을 수 없으면 false
- */
- public static boolean getBoolean(final @NotNull ResourceBundle bundle, final String key) {
- return bundle.containsKey(key) && (boolean) bundle.getObject(key);
- }
-
- /**
- * 구성에서 문자열 값을 불러오는 메소드입니다.
- *
- * @param bundle 기반 리소스 번들
- * @param key 불러오고자 하는 값의 경로
- * @param def 키를 찾을 수 없는 경우의 반환값
- * @return 경로에 위치한 문자열 값, 키를 찾을 수 없으면 전달된 기본 값
- */
- @Nullable
- public static String getString(final @NotNull ResourceBundle bundle, final String key, String def) {
- return bundle.containsKey(key) ? bundle.getString(key) : def;
- }
-
- /**
- * 구성에서 문자열 값을 불러오는 메소드입니다.
- *
- * @param bundle 기반 리소스 번들
- * @param key 불러오고자 하는 값의 경로
- * @return 경로에 위치한 문자열 값, 키를 찾을 수 없으면 {@code null}
- */
- @Nullable
- public static String getString(final @NotNull ResourceBundle bundle, final String key) {
- return getString(bundle, key, null);
- }
-
- /**
- * 구성에서 오브젝트 배열을 불러오는 메소드입니다.
- * 사용되는 타입은 직접 지정해야 합니다.
- *
- * @param bundle 기반 리소스 번들
- * @param key 불러오고자 하는 값의 경로
- * @param elementClass 타입 지정
- * @param 사용자 정의 타입
- * @return 경로에 위치한 사용자 지정 타입 배열
- */
- public static List getObjectList(final @NotNull ResourceBundle bundle, final String key, @NotNull Class elementClass) {
- String json = bundle.getString(key);
- if (json.trim().isEmpty())
- return Collections.emptyList();
- JavaType type = MAPPER.getTypeFactory().constructCollectionType(List.class, elementClass);
- return MAPPER.readValue(json, type);
- }
-
- /**
- * 구성에서 {@code Enum} 타입 값을 불러오는 메소드입니다.
- *
- * @param bundle 기반 리소스 번들
- * @param key 불러오고자 하는 값의 경로
- * @param elementClass Enum 클래스 타입
- * @param def 키를 찾을 수 없거나 값이 유효하지 않은 경우의 반환값
- * @param Enum 타입
- * @return 경로에 위치한 Enum 값, 키를 찾을 수 없거나 유효하지 않으면 전달된 기본 값
- * @throws IllegalArgumentException 기본 값이 {@code null}이고 유효하지 않은 Enum 값일 경우 발생
- */
- @Nullable
- public static > T getEnumType(final @NotNull ResourceBundle bundle,
- final String key,
- @NotNull Class elementClass,
- final @Nullable T def) {
- if (bundle.containsKey(key)) {
- String enumName = bundle.getString(key);
- try {
- return Enum.valueOf(elementClass, enumName);
- } catch (IllegalArgumentException e) {
- if (def == null)
- throw new IllegalArgumentException("Invalid enum value for key: " + key + ", value: " + enumName, e);
- return def;
- }
- }
- return def;
- }
-
- /**
- * 구성에서 {@code Enum} 타입 값을 불러오는 메소드입니다.
- *
- * @param bundle 기반 리소스 번들
- * @param key 불러오고자 하는 값의 경로
- * @param elementClass Enum 클래스 타입
- * @param Enum 타입
- * @return 경로에 위치한 Enum 값, 키를 찾을 수 없거나 유효하지 않으면 {@code null}
- */
- @Nullable
- public static > T getEnumType(final @NotNull ResourceBundle bundle,
- final String key,
- @NotNull Class elementClass) {
- return getEnumType(bundle, key, elementClass, null);
- }
-
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/resource/config/ConfigerInstanceBased.java b/src/main/java/space/qu4nt/entanglementlib/resource/config/ConfigerInstanceBased.java
deleted file mode 100644
index f06e3fb..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/resource/config/ConfigerInstanceBased.java
+++ /dev/null
@@ -1,191 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.resource.config;
-
-import lombok.Getter;
-import lombok.Setter;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
-
-import java.util.List;
-import java.util.ResourceBundle;
-
-/**
- * 인스턴스 기반으로 구성 파일에서 값을 읽어오는 클래스입니다.
- *
- * 이 클래스를 상속하여 구성 리소스 번들을 등록하고 자유롭게 호출하여
- * 사용할 수도 있습니다
- *
- * @author Q. T. Felix
- * @since 1.0.0
- */
-@Getter
-@Setter
-public class ConfigerInstanceBased {
-
- private ResourceBundle bundle;
-
- /**
- * {@link ConfigerInstanceBased} 객체를 생성합니다.
- *
- * @param bundle 리소스 번들
- */
- protected ConfigerInstanceBased(@NotNull ResourceBundle bundle) {
- this.bundle = bundle;
- }
-
- /**
- * 주어진 리소스 번들로 {@link ConfigerInstanceBased} 인스턴스를 생성합니다.
- *
- * @param bundle 리소스 번들
- * @return ConfigerInstanceBased 인스턴스
- */
- public static ConfigerInstanceBased of(@NotNull ResourceBundle bundle) {
- return new ConfigerInstanceBased(bundle);
- }
-
- /**
- * 구성에서 정수 값을 불러오는 메소드입니다.
- *
- * @param key 불러오고자 하는 값의 경로
- * @return 경로에 위치한 정수 값
- */
- public int getInt(String key) {
- return Configer.getInt(bundle, key);
- }
-
- /**
- * 구성에서 정수 값을 불러오는 메소드입니다.
- *
- * @param key 불러오고자 하는 값의 경로
- * @param def 키를 찾을 수 없는 경우의 반환값
- * @return 경로에 위치한 정수 값, 키를 찾을 수 없으면 전달된 기본 값
- */
- public int getInt(String key, int def) {
- return Configer.getInt(bundle, key, def);
- }
-
- /**
- * 구성에서 {@code double} 실수 값을 불러오는 메소드입니다.
- *
- * @param key 불러오고자 하는 값의 경로
- * @return 경로에 위치한 {@code double} 실수 값
- */
- public double getDouble(String key) {
- return Configer.getDouble(bundle, key);
- }
-
- /**
- * 구성에서 {@code double} 실수 값을 불러오는 메소드입니다.
- *
- * @param key 불러오고자 하는 값의 경로
- * @param def 키를 찾을 수 없는 경우의 반환값
- * @return 경로에 위치한 {@code double} 실수 값, 키를 찾을 수 없으면 전달된 기본 값
- */
- public double getDouble(String key, double def) {
- return Configer.getDouble(bundle, key, def);
- }
-
- /**
- * 구성에서 {@code float} 실수 값을 불러오는 메소드입니다.
- *
- * @param key 불러오고자 하는 값의 경로
- * @return 경로에 위치한 {@code float} 실수 값
- */
- public float getFloat(String key) {
- return Configer.getFloat(bundle, key);
- }
-
- /**
- * 구성에서 {@code float} 실수 값을 불러오는 메소드입니다.
- *
- * @param key 불러오고자 하는 값의 경로
- * @param def 키를 찾을 수 없는 경우의 반환값
- * @return 경로에 위치한 {@code float} 실수 값, 키를 찾을 수 없으면 전달된 기본 값
- */
- public float getFloat(String key, float def) {
- return Configer.getFloat(bundle, key, def);
- }
-
- /**
- * 구성에서 논리 값을 불러오는 메소드입니다.
- *
- * @param key 불러오고자 하는 값의 경로
- * @return 경로에 위치한 논리 값
- */
- public boolean getBoolean(String key) {
- return Configer.getBoolean(bundle, key);
- }
-
- /**
- * 구성에서 문자열 값을 불러오는 메소드입니다.
- *
- * @param key 불러오고자 하는 값의 경로
- * @param def 키를 찾을 수 없는 경우의 반환값
- * @return 경로에 위치한 문자열 값, 키를 찾을 수 없으면 전달된 기본 값
- */
- public String getString(String key, String def) {
- return Configer.getString(bundle, key, def);
- }
-
- /**
- * 구성에서 문자열 값을 불러오는 메소드입니다.
- *
- * @param key 불러오고자 하는 값의 경로
- * @return 경로에 위치한 문자열 값
- */
- public String getString(String key) {
- return Configer.getString(bundle, key);
- }
-
- /**
- * 구성에서 문자열 리스트를 불러오는 메소드입니다.
- *
- * @param key 불러오고자 하는 값의 경로
- * @return 경로에 위치한 문자열 리스트
- */
- public List getStringList(String key) {
- return Configer.getObjectList(bundle, key, String.class);
- }
-
- /**
- * 구성에서 오브젝트 리스트를 불러오는 메소드입니다.
- *
- * @param key 불러오고자 하는 값의 경로
- * @param elementClass 요소의 클래스 타입
- * @param 요소의 타입
- * @return 경로에 위치한 오브젝트 리스트
- */
- public List getObjectList(String key, Class elementClass) {
- return Configer.getObjectList(bundle, key, elementClass);
- }
-
- /**
- * 구성에서 {@code Enum} 타입 값을 불러오는 메소드입니다.
- *
- * @param key 불러오고자 하는 값의 경로
- * @param elementClass Enum 클래스 타입
- * @param def 키를 찾을 수 없거나 값이 유효하지 않은 경우의 반환값
- * @param Enum 타입
- * @return 경로에 위치한 Enum 값, 키를 찾을 수 없거나 유효하지 않으면 전달된 기본 값
- */
- public > T getEnumType(String key, Class elementClass, final @Nullable T def) {
- return Configer.getEnumType(bundle, key, elementClass, def);
- }
-
- /**
- * 구성에서 Enum 타입 값을 불러오는 메소드입니다.
- *
- * @param key 불러오고자 하는 값의 경로
- * @param elementClass Enum 클래스 타입
- * @param Enum 타입
- * @return 경로에 위치한 Enum 값
- */
- public > T getEnumType(String key, Class elementClass) {
- return Configer.getEnumType(bundle, key, elementClass);
- }
-
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/resource/config/PublicConfigTree.java b/src/main/java/space/qu4nt/entanglementlib/resource/config/PublicConfigTree.java
deleted file mode 100644
index 3715999..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/resource/config/PublicConfigTree.java
+++ /dev/null
@@ -1,64 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.resource.config;
-
-import com.fasterxml.jackson.annotation.JsonInclude;
-import lombok.*;
-
-/**
- * {@code public} 디렉토리에 정의된 구성 파일 {@code configuration.json}을
- * 역/직렬화 하기 위해 사용되는 클래스입니다.
- *
- * @author Q. T. Felix
- * @since 1.0.0
- */
-@Getter
-@Setter
-@ToString
-@NoArgsConstructor
-@AllArgsConstructor
-@JsonInclude(JsonInclude.Include.NON_NULL)
-public final class PublicConfigTree {
-
- private String language;
- private Secure secure;
-
- @Getter
- @Setter
- @ToString
- @NoArgsConstructor
- @AllArgsConstructor
- @JsonInclude(JsonInclude.Include.NON_NULL)
- public static final class Secure {
- private boolean enabledExperimental;
- private TLS tls;
-
- @Getter
- @Setter
- @ToString
- @NoArgsConstructor
- @AllArgsConstructor
- @JsonInclude(JsonInclude.Include.NON_NULL)
- public static final class TLS {
- private String protocol;
- private Cert cert;
- private int maxHandshakeMessageSize;
-
- @Getter
- @Setter
- @ToString
- @NoArgsConstructor
- @AllArgsConstructor
- @JsonInclude(JsonInclude.Include.NON_NULL)
- public static final class Cert {
- private boolean enabledPQC;
- private String root;
- private String server;
- }
- }
- }
-
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/resource/config/PublicConfiguration.java b/src/main/java/space/qu4nt/entanglementlib/resource/config/PublicConfiguration.java
deleted file mode 100644
index c0ac515..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/resource/config/PublicConfiguration.java
+++ /dev/null
@@ -1,144 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.resource.config;
-
-import lombok.Getter;
-import lombok.Setter;
-import lombok.extern.slf4j.Slf4j;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
-import space.qu4nt.entanglementlib.resource.ResourceCaller;
-import space.qu4nt.entanglementlib.resource.language.SupportedLanguage;
-import space.qu4nt.entanglementlib.security.EntLibParameterSpec;
-import tools.jackson.databind.ObjectMapper;
-
-import java.io.IOException;
-import java.util.Objects;
-
-/**
- * {@code public} 디렉토리에 정의된 구성 파일 {@code configuration.json}을
- * 호출하는 클래스입니다.
- *
- * 이 클래스는 {@link space.qu4nt.entanglementlib.InternalFactory}에서
- * 정적 선언되고 할당값을 변경하지 않습니다.
- *
- * @author Q. T. Felix
- * @since 1.0.0
- */
-@Slf4j
-@Getter
-@Setter
-public final class PublicConfiguration {
-
- private PublicConfigTree publicConfigTree;
-
- private SupportedLanguage language;
- private boolean isEnabledExperimental;
- private String tlsProtocol;
- private boolean enabledPQC;
- private EntLibParameterSpec tlsRootCACertAlgorithm;
- private EntLibParameterSpec tlsServerCertAlgorithm;
- private int tlsMaxHandshakeMessageSize;
-
- /**
- * Jackson 라이브러리를 사용하여 얽힘 라이브러리의 구성 파일을 역직렬화한 후
- * 전역 변수에 할당하는 생성자입니다.
- *
- * @param mapper 역직렬화에 사용될 매퍼
- */
- public PublicConfiguration(final @NotNull ObjectMapper mapper) {
- try {
- this.publicConfigTree = ResourceCaller.jacksonDeserializeInPublic(
- mapper,
- "configuration.json",
- PublicConfigTree.class
- );
- } catch (IOException e) {
- throw new RuntimeException("역직렬화 예외", e);
- }
-
- validation();
- }
-
- private void validation() {
- Objects.requireNonNull(publicConfigTree, "public config");
-
- // 언어 기본: ko_KR
- try {
- this.language = SupportedLanguage.valueOf(this.publicConfigTree.getLanguage());
- } catch (IllegalArgumentException e) {
- this.language = SupportedLanguage.ko_KR;
- }
-
- // 데모 로직 활성화 여부
- this.isEnabledExperimental = this.publicConfigTree.getSecure().isEnabledExperimental();
-
- // tls protocol 기본: TLSv1.3
- @Nullable String tlsProtocol = this.publicConfigTree.getSecure().getTls().getProtocol();
- if (isNullOrEmpty(tlsProtocol)) {
- this.tlsProtocol = "TLSv1.3";
- } else if (tlsProtocol.trim().equalsIgnoreCase("TLSv1.1")) {
- log.warn("The TLSv1.1 protocol is not available in the EntanglementLib. Therefore, I set the protocol to the default value of 'TLSv1.3'.");
- this.tlsProtocol = "TLSv1.3";
- } else {
- this.tlsProtocol = tlsProtocol.trim();
- }
-
- // 루트 및 서버 인증서 생성 알고리즘 검증
- this.enabledPQC = this.publicConfigTree.getSecure().getTls().getCert().isEnabledPQC();
- // PQC = true인 경우 사용 가능한 알고리즘은 mldsa, slhdsa밖에 없음. 이 중에 찾으면 됌
- @Nullable String rootAlg = this.publicConfigTree.getSecure().getTls().getCert().getRoot();
- if (isNullOrEmpty(rootAlg)) {
-// this.tlsRootCACertAlgorithm = SLHDSAType.SLH_DSA_SHA2_256s;
- } else if (enabledPQC && (rootAlg.contains("slh-dsa"))) {
-// SLHDSAType.fromName(StringUtil.toLowerCase(rootAlg))
-// .ifPresent(slhdsaType -> this.tlsRootCACertAlgorithm = slhdsaType);
- } else if (enabledPQC && (rootAlg.contains("ml-dsa"))) {
-// MLDSAType.fromName(StringUtil.toLowerCase(rootAlg))
-// .ifPresent(mldsaType -> this.tlsRootCACertAlgorithm = mldsaType);
- } else {
- // TODO: 고전 알고리즘 로직
- }
-
- @Nullable String servAlg = this.publicConfigTree.getSecure().getTls().getCert().getServer();
- if (isNullOrEmpty(servAlg)) {
-// this.tlsServerCertAlgorithm = MLDSAType.ML_DSA_87;
- } else if (enabledPQC && (servAlg.contains("slh-dsa"))) {
-// SLHDSAType.fromName(StringUtil.toLowerCase(servAlg))
-// .ifPresent(slhdsaType -> this.tlsServerCertAlgorithm = slhdsaType);
- } else if (enabledPQC && (servAlg.contains("ml-dsa"))) {
-// MLDSAType.fromName(StringUtil.toLowerCase(servAlg))
-// .ifPresent(mldsaType -> this.tlsServerCertAlgorithm = mldsaType);
- } else {
- // TODO: 고전 알고리즘 로직
- }
-
- // 핸드셰이크 메시지 사이즈 기본: 131072
- int size = this.publicConfigTree.getSecure().getTls().getMaxHandshakeMessageSize();
- if (size < 1 || size > Integer.MAX_VALUE) {
- this.tlsMaxHandshakeMessageSize = 131072;
- } else {
- this.tlsMaxHandshakeMessageSize = size;
- }
- }
-
- @Override
- public String toString() {
- return """
- PublicConfiguration: {
- "language": "%s",
- "secure": {
- "enabledExperimental": %b
- }
- }""".formatted(
- language.name(),
- isEnabledExperimental);
- }
-
- private boolean isNullOrEmpty(final String value) {
- return value == null || value.isEmpty();
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/resource/control/PublicJSONFileSystemResourceBundleControl.java b/src/main/java/space/qu4nt/entanglementlib/resource/control/PublicJSONFileSystemResourceBundleControl.java
deleted file mode 100644
index 94ea15d..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/resource/control/PublicJSONFileSystemResourceBundleControl.java
+++ /dev/null
@@ -1,65 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.resource.control;
-
-import lombok.Getter;
-import lombok.Setter;
-import space.qu4nt.entanglementlib.InternalFactory;
-import space.qu4nt.entanglementlib.resource.ResourceHandler;
-import tools.jackson.core.type.TypeReference;
-import tools.jackson.databind.ObjectMapper;
-
-import java.io.IOException;
-import java.io.InputStream;
-import java.io.InputStreamReader;
-import java.nio.charset.Charset;
-import java.nio.file.Files;
-import java.nio.file.Path;
-import java.nio.file.Paths;
-import java.util.List;
-import java.util.Locale;
-import java.util.Map;
-import java.util.ResourceBundle;
-
-@Getter
-@Setter
-public class PublicJSONFileSystemResourceBundleControl extends ResourceHandler {
-
- private String customDirStringPath;
-
- public PublicJSONFileSystemResourceBundleControl(String customDirStringPath, Charset streamCharset) {
- super(streamCharset, List.of("json"));
- this.customDirStringPath = customDirStringPath == null ? InternalFactory.envEntanglementPublicDir() : customDirStringPath;
- }
-
- public PublicJSONFileSystemResourceBundleControl(Charset streamCharset) {
- this(null, streamCharset);
- }
-
- @Override
- public ResourceBundle newBundle(String baseName,
- Locale locale,
- String format,
- ClassLoader loader,
- boolean reload)
- throws IllegalAccessException, InstantiationException, IOException {
- if (!format.equals("json"))
- return super.newBundle(baseName, locale, format, loader, reload);
-
- String resourceName = baseName + ".json";
- final Path filePath = Paths.get(customDirStringPath + "/" + resourceName);
- try (InputStream stream = Files.newInputStream(filePath);
- InputStreamReader reader = new InputStreamReader(stream, streamCharset)) {
- ObjectMapper objectMapper = new ObjectMapper();
- Map map = objectMapper.readValue(reader, new TypeReference<>() {
- });
- Map flatMap = flattenMap(map, "");
- return new YamlResourceBundle(flatMap);
- } catch (IOException e) {
- return null;
- }
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/resource/control/PublicYamlFileSystemResourceBundleControl.java b/src/main/java/space/qu4nt/entanglementlib/resource/control/PublicYamlFileSystemResourceBundleControl.java
deleted file mode 100644
index 775ca1a..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/resource/control/PublicYamlFileSystemResourceBundleControl.java
+++ /dev/null
@@ -1,63 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.resource.control;
-
-import lombok.Getter;
-import lombok.Setter;
-import org.yaml.snakeyaml.Yaml;
-import space.qu4nt.entanglementlib.InternalFactory;
-import space.qu4nt.entanglementlib.resource.ResourceHandler;
-
-import java.io.IOException;
-import java.io.InputStream;
-import java.io.InputStreamReader;
-import java.nio.charset.Charset;
-import java.nio.file.Files;
-import java.nio.file.Path;
-import java.nio.file.Paths;
-import java.util.List;
-import java.util.Locale;
-import java.util.Map;
-import java.util.ResourceBundle;
-
-@Getter
-@Setter
-public class PublicYamlFileSystemResourceBundleControl extends ResourceHandler {
-
- private String customDirStringPath;
-
- public PublicYamlFileSystemResourceBundleControl(String customDirStringPath, Charset streamCharset) {
- super(streamCharset, List.of("yaml"));
- this.customDirStringPath = customDirStringPath == null ? InternalFactory.envEntanglementPublicDir() : customDirStringPath;
- }
-
- public PublicYamlFileSystemResourceBundleControl(Charset streamCharset) {
- this(null, streamCharset);
- }
-
- @Override
- public ResourceBundle newBundle(String baseName,
- Locale locale,
- String format,
- ClassLoader loader,
- boolean reload)
- throws IllegalAccessException, InstantiationException, IOException {
- if (!format.equals("yaml"))
- return super.newBundle(baseName, locale, format, loader, reload);
-
- String resourceName = baseName + ".yml";
- final Path filePath = Paths.get(customDirStringPath + "/" + resourceName);
- try (InputStream stream = Files.newInputStream(filePath);
- InputStreamReader reader = new InputStreamReader(stream, streamCharset)) {
- Yaml yaml = new Yaml();
- Map map = yaml.load(reader);
- Map flatMap = flattenMap(map, "");
- return new YamlResourceBundle(flatMap);
- } catch (IOException e) {
- return null;
- }
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/resource/language/Language.java b/src/main/java/space/qu4nt/entanglementlib/resource/language/Language.java
deleted file mode 100644
index 2179a37..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/resource/language/Language.java
+++ /dev/null
@@ -1,326 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.resource.language;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.InternalFactory;
-import space.qu4nt.entanglementlib.resource.ResourceCaller;
-import space.qu4nt.entanglementlib.resource.SupportedFormat;
-
-import java.nio.charset.StandardCharsets;
-import java.util.ResourceBundle;
-
-import static space.qu4nt.entanglementlib.util.StringUtil.placeholderFormat;
-
-/**
- * 다양한 국적의 언어를 간편하게 사용하기 위한 클래스입니다.
- *
- * 언어 파일은 멀티 모듈 프로젝트가 아닌 경우 다음의 형식으로 저장됩니다.
- *
- * class-SomeClass:
- * msg-field: "Hello, World!"
- * ...
- *
- * 멀티 모듈 프로젝트의 경우 다음의 형식으로 저장됩니다.
- *
- * module-a:
- * class-SomeClass:
- * msg-field: "Hello, Multi-World!"
- *
- * 이 경우 키 호출 양식을 주의하세요.
- *
- * 언어 파일은 {@code .yml} 또는 {@code .yaml} 형식으로 저장되며,
- * {@code messages_} 이름을 유지하세요. locale 플레이스 홀더는
- * ISO 3166-1 에 따른 국가 코드,
- * ISO 639-1
- * 에 따른 언어 코드 양식을 준수하세요.
- *
- * @author Q. T. Felix
- * @since 1.0.0
- */
-public final class Language {
-
- // MSG
-
- /**
- * 공용 리소스에서 입력받은 언어의 메시지 파일 속 메시지 키에 할당된 메시지를
- * 반환하는 메소드입니다.
- *
- * @param language 사용 가능한 언어 중 가져오고자 하는 언어 {@link SupportedLanguage}
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param def 메시지 파일 속 참조할 메시지의 키가 존재하지 않은 경우 반환할 메시지
- * @return 할당된 메시지
- */
- public static String msg(final SupportedLanguage language, String key, @NotNull String def) {
- final ResourceBundle bundle = ResourceCaller
- .getCustomResourceInPublicInnerDir(SupportedFormat.YAML, "lang", language.getFilename(), StandardCharsets.UTF_8);
- return msg(bundle, key, def);
- }
-
- /**
- * 공용 리소스에서 입력받은 언어의 메시지 파일 속 메시지 키에 할당된 메시지를
- * 반환하는 메소드입니다. 키를 찾을 수 없는 경우, 키 경로가 표시됩니다.
- *
- * @param language 사용 가능한 언어 중 가져오고자 하는 언어 {@link SupportedLanguage}
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @return 할당된 메시지, 찾을 수 없는 경우 키 경로 문자열
- */
- public static String msg(final SupportedLanguage language, String key) {
- return msg(language, key, key);
- }
-
- /**
- * 공용 리소스에서 설정된 기본 언어의 메시지 파일 속 메시지 키에 할당된 메시지를
- * 반환하는 메소드입니다. 만약 기본 언어를 세팅하지 않은 경우 {@code ENTANGLEMENT_DEFAULT_LANG}
- * 환경 변수에 할당된 언어를 불러옵니다.
- *
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param def 메시지 파일 속 참조할 메시지의 키가 존재하지 않은 경우 반환할 메시지
- * @return 할당된 메시지
- */
- public static String msg(@NotNull String key, @NotNull String def) {
- return msg(InternalFactory.getPublicConfig().getLanguage(),
- key, def);
- }
-
- /**
- * 공용 리소스에서 설정된 기본 언어의 메시지 파일 속 메시지 키에 할당된 메시지를
- * 반환하는 메소드입니다. 만약 기본 언어를 세팅하지 않은 경우 {@code ENTANGLEMENT_DEFAULT_LANG}
- * 환경 변수에 할당된 언어를 불러옵니다. 키를 찾을 수 없는 경우, 키 경로가 표시됩니다.
- *
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @return 할당된 메시지
- */
- public static String msg(@NotNull String key) {
- return msg(InternalFactory.getPublicConfig().getLanguage(),
- key, key);
- }
-
- /**
- * 입력받은 리소스 번들에서 메시지 키에 할당된 메시지를 반환하는 메소드입니다.
- *
- * @param bundle 리소스 번들
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param def 메시지 파일 속 참조할 메시지의 키가 존재하지 않은 경우 반환할 메시지
- * @return 할당된 메시지
- */
- public static String msg(@NotNull ResourceBundle bundle, String key, @NotNull String def) {
- if (bundle.containsKey(key))
- return bundle.getString(key);
- return def;
- }
-
- /**
- * 입력받은 리소스 번들에서 메시지 키에 할당된 메시지를 반환하는 메소드입니다.
- * 키를 찾을 수 없는 경우, 키 경로가 표시됩니다.
- *
- * @param bundle 리소스 번들
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @return 할당된 메시지, 찾을 수 없는 경우 키 경로 문자열
- */
- public static String msg(@NotNull ResourceBundle bundle, String key) {
- return msg(bundle, key, key);
- }
-
- // ARGS
-
- /**
- * 공용 리소스에서 입력받은 언어의 메시지 파일 속 메시지 키에 할당된 메시지(raw)를
- * 호출하여 플레이스홀더를 변환하여 반환하는 메소드입니다.
- *
- * @param language 사용 가능한 언어 중 가져오고자 하는 언어 {@link SupportedLanguage}
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param def 메시지 파일 속 참조할 메시지의 키가 존재하지 않은 경우 반환할 메시지
- * @param args 플레이스홀더 변경 인자
- * @return 할당 후 변환된 메시지
- */
- public static String args(final SupportedLanguage language, String key, @NotNull String def, Object... args) {
- // 기존 메소드를 호출하여 raw 메시지 가져오기
- String message = msg(language, key, def);
- if (args == null || args.length == 0)
- return message; // 인자가 없으면 그대로 반환
- return placeholderFormat(message, args);
- }
-
- /**
- * 공용 리소스에서 입력받은 언어의 메시지 파일 속 메시지 키에 할당된 메시지(raw)를
- * 호출하여 플레이스홀더를 변환하여 반환하는 메소드입니다. 키를 찾을 수 없는 경우,
- * 키 경로가 표시됩니다.
- *
- * @param language 사용 가능한 언어 중 가져오고자 하는 언어 {@link SupportedLanguage}
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param args 플레이스홀더 변경 인자
- * @return 할당 후 변환된 메시지, 키를 찾을 수 없는 경우 키 경로 문자열
- */
- public static String args(final SupportedLanguage language, String key, Object... args) {
- return args(language, key, key, args);
- }
-
- /**
- * 공용 리소스에서 입력받은 언어의 메시지 파일 속 메시지 키에 할당된 메시지(raw)를 호출하여 플레이스홀더를
- * 변환하여 반환하는 메소드입니다. 만약 기본 언어를 세팅하지 않은 경우 {@code ENTANGLEMENT_DEFAULT_LANG}
- * 환경 변수에 할당된 언어를 불러옵니다.
- *
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param def 메시지 파일 속 참조할 메시지의 키가 존재하지 않은 경우 반환할 메시지
- * @param args 플레이스홀더 변경 인자
- * @return 할당된 메시지
- */
- public static String args(@NotNull String key, @NotNull String def, Object... args) {
- return args(InternalFactory.getPublicConfig().getLanguage(),
- key, def, args);
- }
-
- /**
- * 공용 리소스에서 입력받은 언어의 메시지 파일 속 메시지 키에 할당된 메시지(raw)를 호출하여 플레이스홀더를
- * 변환하여 반환하는 메소드입니다. 만약 기본 언어를 세팅하지 않은 경우 {@code ENTANGLEMENT_DEFAULT_LANG}
- * 환경 변수에 할당된 언어를 불러옵니다. 키를 찾을 수 없는 경우, 키 경로가 표시됩니다.
- *
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param args 플레이스홀더 변경 인자
- * @return 할당된 메시지
- */
- public static String args(@NotNull String key, Object... args) {
- return args(InternalFactory.getPublicConfig().getLanguage(),
- key, args);
- }
-
- /**
- * 입력받은 리소스 번들에서 메시지 키에 할당된 메시지(raw)를 호출하여 플레이스홀더를
- * 변환하여 반환하는 메소드입니다.
- *
- * @param bundle 리소스 번들
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param def 메시지 파일 속 참조할 메시지의 키가 존재하지 않은 경우 반환할 메시지
- * @param args 플레이스홀더 변경 인자
- * @return 할당 후 변환된 메시지
- */
- public static String args(@NotNull ResourceBundle bundle, String key, @NotNull String def, Object... args) {
- String message = msg(bundle, key, def);
- if (args == null || args.length == 0)
- return message;
- return placeholderFormat(message, args);
- }
-
- /**
- * 입력받은 리소스 번들에서 메시지 키에 할당된 메시지(raw)를 호출하여 플레이스홀더를
- * 변환하여 반환하는 메소드입니다. 키를 찾을 수 없는 경우, 키 경로가 표시됩니다.
- *
- * @param bundle 리소스 번들
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param args 플레이스홀더 변경 인자
- * @return 할당 후 변환된 메시지, 키를 찾을 수 없는 경우 키 경로 문자열
- */
- public static String args(@NotNull ResourceBundle bundle, String key, Object... args) {
- return args(bundle, key, key, args);
- }
-
- // THROW
-
- /**
- * 공용 리소스에서 입력받은 언어의 메시지 파일 속 메시지 키에 할당된 메시지(raw)를 호출하여 예외와
- * 플레이스 홀더를 변환하여 반환하는 메소드입니다.
- *
- * @param language 사용 가능한 언어 중 가져오고자 하는 언어 {@link SupportedLanguage}
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param def 메시지 파일 속 참조할 메시지의 키가 존재하지 않은 경우 반환할 메시지
- * @param args 플레이스홀더 변경 인자
- * @return 할당 후 변환된 메시지
- */
- public static String thr(final SupportedLanguage language, String key, @NotNull String def, @NotNull Throwable cause, Object... args) {
- String message = args(language, key, def, args);
- // 예외 메시지 추가
- if (cause != null) {
- String causeMessage = cause.getMessage();
- if (causeMessage == null) {
- causeMessage = "unknown error";
- }
- message += " : " + causeMessage;
- }
- return message;
- }
-
- /**
- * 공용 리소스에서 입력받은 언어의 메시지 파일 속 메시지 키에 할당된 메시지(raw)를 호출하여 예외와
- * 플레이스 홀더를 변환하여 반환하는 메소드입니다. 키를 찾을 수 없는 경우, 키 경로가 표시됩니다.
- *
- * @param language 사용 가능한 언어 중 가져오고자 하는 언어 {@link SupportedLanguage}
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param args 플레이스홀더 변경 인자
- * @return 할당 후 변환된 메시지, 키를 찾을 수 없는 경우 키 경로 문자열
- */
- public static String thr(final SupportedLanguage language, String key, @NotNull Throwable cause, Object... args) {
- return thr(language, key, key, cause, args);
- }
-
- /**
- * 공용 리소스에서 입력받은 언어의 메시지 파일 속 메시지 키에 할당된 메시지(raw)를 호출하여 예외와
- * 플레이스 홀더를 변환하여 반환하는 메소드입니다. 만약 기본 언어를 세팅하지 않은 경우 {@code ENTANGLEMENT_DEFAULT_LANG}
- * 환경 변수에 할당된 언어를 불러옵니다.
- *
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param def 메시지 파일 속 참조할 메시지의 키가 존재하지 않은 경우 반환할 메시지
- * @param args 플레이스홀더 변경 인자
- * @return 할당된 메시지
- */
- public static String thr(@NotNull String key, @NotNull String def, @NotNull Throwable cause, Object... args) {
- return thr(InternalFactory.getPublicConfig().getLanguage(),
- key, def, cause, args);
- }
-
- /**
- * 공용 리소스에서 입력받은 언어의 메시지 파일 속 메시지 키에 할당된 메시지(raw)를 호출하여 예외와
- * 플레이스 홀더를 변환하여 반환하는 메소드입니다. 만약 기본 언어를 세팅하지 않은 경우 {@code ENTANGLEMENT_DEFAULT_LANG}
- * 환경 변수에 할당된 언어를 불러옵니다. 키를 찾을 수 없는 경우, 키 경로가 표시됩니다.
- *
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param args 플레이스홀더 변경 인자
- * @return 할당된 메시지
- */
- public static String thr(@NotNull String key, @NotNull Throwable cause, Object... args) {
- return thr(InternalFactory.getPublicConfig().getLanguage(),
- key, cause, args);
- }
-
- /**
- * 입력받은 리소스 번들에서 메시지 키에 할당된 메시지(raw)를 호출하여 예외와
- * 플레이스 홀더를 변환하여 반환하는 메소드입니다.
- *
- * @param bundle 리소스 번들
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param def 메시지 파일 속 참조할 메시지의 키가 존재하지 않은 경우 반환할 메시지
- * @param cause 예외
- * @param args 플레이스홀더 변경 인자
- * @return 할당 후 변환된 메시지
- */
- public static String thr(@NotNull ResourceBundle bundle, String key, @NotNull String def, @NotNull Throwable cause, Object... args) {
- String message = args(bundle, key, def, args);
- // 예외 메시지 추가
- if (cause != null) {
- String causeMessage = cause.getMessage();
- if (causeMessage == null) {
- causeMessage = "unknown error";
- }
- message += " : " + causeMessage;
- }
- return message;
- }
-
- /**
- * 입력받은 리소스 번들에서 메시지 키에 할당된 메시지(raw)를 호출하여 예외와
- * 플레이스 홀더를 변환하여 반환하는 메소드입니다. 키를 찾을 수 없는 경우, 키 경로가 표시됩니다.
- *
- * @param bundle 리소스 번들
- * @param key 메시지 파일 속 참조할 메시지의 키
- * @param cause 예외
- * @param args 플레이스홀더 변경 인자
- * @return 할당 후 변환된 메시지, 키를 찾을 수 없는 경우 키 경로 문자열
- */
- public static String thr(@NotNull ResourceBundle bundle, String key, @NotNull Throwable cause, Object... args) {
- return thr(bundle, key, key, cause, args);
- }
-
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/resource/language/LanguageInstanceBased.java b/src/main/java/space/qu4nt/entanglementlib/resource/language/LanguageInstanceBased.java
deleted file mode 100644
index 5bbe1c4..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/resource/language/LanguageInstanceBased.java
+++ /dev/null
@@ -1,117 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.resource.language;
-
-import lombok.Getter;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
-
-import java.util.Objects;
-import java.util.ResourceBundle;
-
-/**
- * 언어를 좀 더 간편하게 사용할 수 있도록 상수로써 선언할 수 있도록 해주는 클래스입니다.
- * 특정 클래스에서 {@link Language} 클래스를 통한 언어 호출이 잦은 경우 유용합니다.
- *
- * 이 클래스에선 {@code ENTANGLEMENT_DEFAULT_LANG} 환경 변수를 기반으로 동작합니다.
- *
- * @param 바인딩 타겟 타입 파라미터
- * @author Q. T. Felix
- * @see Language 기반 언어 클래스
- * @since 1.0.0
- */
-@Getter
-public class LanguageInstanceBased {
-
- private Class clazz;
- /**
- * 이 변수는 {@code null}일 수 있지만,
- * null이 아닌 경우 우선적으로 사용됩니다.
- */
- @Nullable
- private final ResourceBundle bundle;
-
- private LanguageInstanceBased(Class clazz) {
- this.clazz = clazz;
- this.bundle = null;
- }
-
- private LanguageInstanceBased(@NotNull ResourceBundle bundle, Class clazz) {
- this.clazz = clazz;
- this.bundle = bundle;
- }
-
- public static LanguageInstanceBased create(Class clazz) {
- return new LanguageInstanceBased<>(clazz);
- }
-
- /**
- * 전달받은 리소스 번들에서 언어 파일을 로드하기 위한 메소드입니다.
- *
- * 얽힘 라이브러리를 외부에서 사용하는 경우 이 라이브러리에 포함된 메시지 키를 사용하지 않고
- * 호출자 프로젝트에서 언어 파일을 새롭게 로드하고자 하는 경우 사용됩니다.
- *
- * @param bundle 리소스 번들
- * @param clazz 언어 파일에서 바인딩할 타입
- * @param 바인딩 타겟 타입 파라미터
- * @return 언어 인스턴스 {@link LanguageInstanceBased}
- */
- public static LanguageInstanceBased create(@NotNull ResourceBundle bundle, Class clazz) {
- return new LanguageInstanceBased<>(bundle, clazz);
- }
-
- public LanguageInstanceBased setClass(Class clazz) {
- this.clazz = clazz;
- return this;
- }
-
- public String msg(@Nullable String topKey, String lowKey) {
- Objects.requireNonNull(lowKey);
- String key = fixTopKey(topKey) + lowKey;
- if (bundle != null) {
- return Language.msg(bundle, key);
- }
- return Language.msg(key);
- }
-
- public String msg(String lowKey) {
- Objects.requireNonNull(lowKey);
- return msg(null, clazz.getSimpleName() + "." + lowKey);
- }
-
- public String args(@Nullable String topKey, String lowKey, Object... args) {
- Objects.requireNonNull(lowKey);
- String key = fixTopKey(topKey) + lowKey;
- if (bundle != null) {
- return Language.args(bundle, key, args);
- }
- return Language.args(key, args);
- }
-
- public String argsNonTopKey(String lowKey, Object... args) {
- Objects.requireNonNull(lowKey);
- return args(null, clazz.getSimpleName() + "." + lowKey, args);
- }
-
- public String thr(@Nullable String topKey, String lowKey, @NotNull Throwable cause, Object... args) {
- Objects.requireNonNull(lowKey);
- String key = fixTopKey(topKey) + lowKey;
- if (bundle != null) {
- return Language.thr(bundle, key, cause, args);
- }
- return Language.thr(key, cause, args);
- }
-
- public String thr(String lowKey, @NotNull Throwable cause, Object... args) {
- Objects.requireNonNull(lowKey);
- return thr(null, clazz.getSimpleName() + "." + lowKey, cause, args);
- }
-
- private String fixTopKey(String topKey) {
- return topKey == null ? "class-" : (topKey + ".class-");
- }
-
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/resource/language/SupportedLanguage.java b/src/main/java/space/qu4nt/entanglementlib/resource/language/SupportedLanguage.java
deleted file mode 100644
index a3b55a3..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/resource/language/SupportedLanguage.java
+++ /dev/null
@@ -1,36 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.resource.language;
-
-import lombok.Getter;
-
-/**
- * 현재 프로젝트가 지원하는 언어입니다. 새로운 언어를 추가하고자 하는 경우, {@code i18n}에 따라
- * 국적에 맞는 열거 상수를 추가한 뒤, 공용 리소스 디렉토리에 {@code messages_en_US.yml}와 같이
- * 언어 파일을 생성하세요.
- *
- * ISO 3166-1 에 따른 국가 코드,
- * ISO 639-1
- * 에 따른 언어 코드 양식을 준수하세요.
- *
- * @author Q. T. Felix
- * @since 1.0.0
- */
-@Getter
-public enum SupportedLanguage {
-
- /**
- * 한국어
- */
- ko_KR,
- /**
- * US English
- */
- en_US;
-
- private final String filename = "messages_" + name();
-
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/EntLibParameterSpec.java b/src/main/java/space/qu4nt/entanglementlib/security/EntLibParameterSpec.java
deleted file mode 100644
index 3746670..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/EntLibParameterSpec.java
+++ /dev/null
@@ -1,19 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security;
-
-import org.jetbrains.annotations.NotNull;
-
-import java.util.Objects;
-
-public interface EntLibParameterSpec {
-
- String getAlgorithmName();
-
- default boolean startsWith(@NotNull String prefix) {
- return Objects.requireNonNull(getAlgorithmName(), "normal algorithm name").startsWith(prefix);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/KeyDestroyHelper.java b/src/main/java/space/qu4nt/entanglementlib/security/KeyDestroyHelper.java
deleted file mode 100644
index 9e546c9..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/KeyDestroyHelper.java
+++ /dev/null
@@ -1,204 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security;
-
-import lombok.extern.slf4j.Slf4j;
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.resource.language.LanguageInstanceBased;
-import space.qu4nt.entanglementlib.util.wrapper.Hex;
-
-import javax.crypto.spec.SecretKeySpec;
-import javax.security.auth.DestroyFailedException;
-import java.lang.foreign.MemorySegment;
-import java.lang.reflect.Field;
-import java.lang.reflect.Modifier;
-import java.math.BigInteger;
-import java.util.Arrays;
-import java.util.Collections;
-import java.util.IdentityHashMap;
-import java.util.Set;
-
-/**
- * 키 데이터를 영소거(zeroing)하기 위한 몇 가지 도구를 제공하는 클래스입니다.
- * 소거된 키는 공격자가 배열 정보를 알 수 없도록 리플렉션을 통해 완전히 제거하고,
- * 소거 후 배열 사이즈를 {@code 0}으로 초기화합니다.
- *
- * @author Q. T. Felix
- * @since 1.0.0
- */
-@Slf4j
-public final class KeyDestroyHelper {
-
- private static final LanguageInstanceBased lang =
- LanguageInstanceBased.create(KeyDestroyHelper.class);
-
- /**
- * 리플렉션을 통해 전달받은 객체 타입의 필드를 영소거하는 메소드입니다.
- * 내부 인스턴스의 모든 필드를 검사하여 민감한 데이터({@code byte[]},
- * {@code char[]}, {@code SecretKey})가 해당됩니다.
- *
- * 단, {@link javax.crypto.SecretKey} 객체를 구현하는
- * {@link javax.crypto.spec.SecretKeySpec} 객체의 경우,
- * JPMS 보안 시스템이 강화되어 리플렉션으로도 접근할 수 없습니다.
- *
- * @param targetObject 소거할 내부 키 파라미터 객체
- * @deprecated 1.1.0 이상 버전부턴 모든 메모리 관련 기능이 {@code entlib-native}를 통해 구현됩니다.
- */
- @Deprecated
- public static void destroy(Object targetObject) {
- if (targetObject == null) return;
-
- // 순환 참조 방지를 위해 방문한 객체의 주소값을 저장 (IdentityHashMap 사용)
- Set visited = Collections.newSetFromMap(new IdentityHashMap<>());
- recursiveZeroing(targetObject, visited, false);
- }
-
- /**
- * 리플렉션을 통해 전달받은 객체 타입의 필드를 영소거하는 메소드입니다.
- * 얕은 소거(shallow)를 활성화하면 해당 객체의 필드만 소거하고 재귀적으로 탐색하지 않습니다.
- *
- * @param targetObject 소거할 내부 키 파라미터 객체
- * @param shallow 얕은 소거 여부, 재귀 탐색을 원치 않으면 true, 그렇지 않으면 false
- * @deprecated 1.1.0 이상 버전부턴 모든 메모리 관련 기능이 {@code entlib-native}를 통해 구현됩니다.
- */
- @Deprecated
- public static void destroy(Object targetObject, boolean shallow) {
- if (targetObject == null) return;
-
- Set visited = Collections.newSetFromMap(new IdentityHashMap<>());
- recursiveZeroing(targetObject, visited, shallow);
- }
-
- /**
- * @deprecated 1.1.0 이상 버전부턴 모든 메모리 관련 기능이 {@code entlib-native}를 통해 구현됩니다.
- */
- @Deprecated
- private static void recursiveZeroing(Object targetObject, Set visited, boolean shallow) {
- if (targetObject == null) return;
-
- // JPMS 보안 강화로 인해 리플렉션 불가능
- // TODO: 대칭 키 객체 소거 방안 찾기
- if (targetObject instanceof SecretKeySpec s) {
- try {
- s.destroy();
- } catch (DestroyFailedException e) {
- zeroing(s.getEncoded()); // 대안이 생기기 전 까진 복사본이라도 소거
- }
- return;
- }
-
- // 이미 방문한 객체인지 확인 (무한 루프 방지)
- if (visited.contains(targetObject)) return;
- visited.add(targetObject);
-
- Class currentClass = targetObject.getClass();
-
- // 탐색 제외 조건 (Java 내부 클래스나 원시 타입 래퍼 등은 내부를 탐색할 필요 없음)
- // 단, byte[]는 배열이므로 여기서 걸러지지 않도록 주의 (isArray 체크는 아래에서 함)
- if (isSkippingType(currentClass)) {
- return;
- }
-
- // 현재 클래스와 모든 부모 클래스의 필드를 탐색
- while (currentClass != null && currentClass != Object.class) {
- Field[] fields = currentClass.getDeclaredFields();
-
- for (Field field : fields) {
- try {
- // static 필드는 제외
- if (Modifier.isStatic(field.getModifiers())) continue;
-
- field.setAccessible(true);
- Object value = field.get(targetObject);
-
- if (value == null) continue;
-
- // 타겟 발견 소거 수행
- if (field.getType() == byte[].class) {
- zeroing((byte[]) value);
- field.set(targetObject, new byte[0]);
- log.debug(lang.argsNonTopKey("debug-byte-arr-field-zeroing-result", field.getName(), Hex.toHexString((byte[]) field.get(targetObject))));
- } else if (field.getType() == char[].class) {
- zeroing((char[]) value);
- field.set(targetObject, new char[0]);
- log.debug(lang.argsNonTopKey("debug-char-arr-field-zeroing-result", field.getName(), Arrays.toString((char[]) field.get(targetObject))));
- } else if (field.getType() == BigInteger.class) {
- field.set(targetObject, new BigInteger(0, new byte[0]));
- log.debug(lang.argsNonTopKey("debug-number-field-zeroing-result", field.getName(), field.get(targetObject)));
- } else if (field.getType() == Number.class) {
- field.set(targetObject, 0);
- log.debug(lang.argsNonTopKey("debug-number-field-zeroing-result", field.getName(), field.get(targetObject)));
- }
- // 배열만 재귀 탐색
- else if (!shallow && !field.getType().isPrimitive() && !field.getType().isArray()) {
- recursiveZeroing(value, visited, false);
- }
-
- } catch (IllegalAccessException e) {
- log.error(lang.msg("cannot-access-exc"), e);
- }
- }
- // 부모 클래스로 이동하여 필드 탐색 계속
- currentClass = currentClass.getSuperclass();
- }
- }
-
- // 탐색을 멈출 타입 정의 (String, Number 등 불변 객체거나 내부 필드가 의미 없는 경우)
- @Deprecated
- private static boolean isSkippingType(Class clazz) {
- if (clazz == null) return true;
- String name = clazz.getName();
- return clazz.isPrimitive() ||
- name.startsWith("java.lang.") ||
- name.startsWith("java.util.") ||
- name.startsWith("java.math.");
- }
-
- /**
- * 메모리에서 바이트 배열을 안전하게 영소거하는 메소드입니다.
- *
- * @param bytes 영소거할 바이트 배열
- */
- public static void zeroing(byte @NotNull [] bytes) {
- Arrays.fill(bytes, (byte) 0);
- }
-
- /**
- * 메모리에서 2차원 바이트 배열을 안전하게 영소거하는 메소드입니다.
- *
- * @param bytes2d 영소거할 2차원 바이트 배열
- */
- public static void zeroing(byte[][] bytes2d) {
- for (byte[] bytes : bytes2d)
- zeroing(bytes);
- }
-
- /**
- * 메모리에서 문자 배열을 안전하게 영소거하는 메소드입니다.
- *
- * @param chars 영소거할 문자 배열
- */
- public static void zeroing(char @NotNull [] chars) {
- Arrays.fill(chars, '\0');
- }
-
- /**
- * 메모리에서 2차원 바이트 배열을 안전하게 영소거하는 메소드입니다.
- *
- * @param chars2d 영소거할 2차원 바이트 배열
- */
- public static void zeroing(char[][] chars2d) {
- for (char[] chars : chars2d)
- zeroing(chars);
- }
-
- /// 네이티브 메모리에 할당된 데이터를 영소거하는 메소드입니다.
- ///
- /// @param memorySegment 영소거할 메모리 타겟
- public static void zeroing(final MemorySegment memorySegment) {
- memorySegment.fill((byte) 0);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/PostQuantumParameterSpec.java b/src/main/java/space/qu4nt/entanglementlib/security/PostQuantumParameterSpec.java
deleted file mode 100644
index 6cab221..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/PostQuantumParameterSpec.java
+++ /dev/null
@@ -1,19 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security;
-
-import org.jetbrains.annotations.NotNull;
-
-import java.util.Objects;
-
-public interface PostQuantumParameterSpec extends EntLibParameterSpec {
-
- @Override
- default boolean startsWith(@NotNull String prefix) {
- return Objects.requireNonNull(getAlgorithmName(), "pqc algorithm name").startsWith(prefix);
- }
-
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/auth/TOTP.java b/src/main/java/space/qu4nt/entanglementlib/security/auth/TOTP.java
deleted file mode 100644
index 9cffe54..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/auth/TOTP.java
+++ /dev/null
@@ -1,112 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.auth;
-
-import org.jetbrains.annotations.Range;
-import space.qu4nt.entanglementlib.security.crypto.Digest;
-
-import javax.crypto.Mac;
-import javax.crypto.spec.SecretKeySpec;
-import java.security.InvalidKeyException;
-import java.security.NoSuchAlgorithmException;
-import java.time.Instant;
-import java.util.Base64;
-
-/**
- * 상태를 가지지 않는 TOTP(Time-based One-Time Password) 2FA를 제공하는 클래스입니다.
- *
- * @author Q. T. Felix
- * @since 1.1.0
- */
-public final class TOTP {
-
- /**
- * 현재 시간을 기준으로 TOTP 코드를 생성하는 메소드입니다.
- *
- * @param digest 해시 알고리즘
- * @param digit TOTP 코드의 자릿수
- * @param timeStepSeconds 시간 간격(초)
- * @param secretKeyBase64 {@code Base64}로 인코딩된 비밀키
- * @return 생성된 TOTP 코드
- */
- public static String generateCurrentTotp(Digest digest, int digit, final long timeStepSeconds, String secretKeyBase64) {
- long currentTimeSeconds = Instant.now().getEpochSecond();
- long timeStep = currentTimeSeconds / timeStepSeconds;
-
- return computeTotp(digest, digit, secretKeyBase64, timeStep);
- }
-
- /**
- * 입력된 TOTP 코드를 검증하는 메소드입니다.
- * 네트워크 지연 등을 고려하여 현재 스텝과 이전 스텝까지 유효성을 확인합니다.
- *
- * @param digest 해시 알고리즘
- * @param digit TOTP 코드의 자릿수
- * @param timeStepSeconds 시간 간격(초)
- * @param secretKeyBase64 {@code Base64}로 인코딩된 비밀키
- * @param inputCode 검증할 TOTP 코드
- * @return 검증 성공 여부
- */
- public static boolean verifyTotp(Digest digest, int digit, final long timeStepSeconds, String secretKeyBase64, String inputCode) {
- long currentTimeSeconds = Instant.now().getEpochSecond();
- long currentTimeStep = currentTimeSeconds / timeStepSeconds;
-
- // 네트워크 지연 등을 고려해 현재 스텝과 바로 이전 스텝까지 유효하다고 판단
- for (int i = -1; i <= 0; i++) {
- String generated = computeTotp(digest, digit, secretKeyBase64, currentTimeStep + i);
- if (generated.equals(inputCode)) {
- return true;
- }
- }
- return false;
- }
-
- /**
- * 주어진 시간 스텝과 비밀키를 사용하여 TOTP 코드를 계산하는 내부 메소드입니다.
- *
- * @param digest 해시 알고리즘
- * @param digit TOTP 코드의 자릿수
- * @param secretKeyBase64 {@code Base64}로 인코딩된 비밀키
- * @param timeStep 시간 스텝
- * @return 계산된 TOTP 코드
- */
- private static String computeTotp(Digest digest,
- @Range(from = 6, to = Integer.MAX_VALUE) int digit,
- String secretKeyBase64,
- long timeStep) {
- try {
- byte[] secretKey = Base64.getDecoder().decode(secretKeyBase64);
-
- // TimeStep을 8바이트 배열로 변환
- byte[] data = new byte[8];
- for (int i = 8; i-- > 0; timeStep >>>= 8) {
- data[i] = (byte) timeStep;
- }
-
- final String alg = "Hmac" + digest.getName();
- Mac mac = Mac.getInstance(alg);
- mac.init(new SecretKeySpec(secretKey, alg));
- byte[] hash = mac.doFinal(data);
-
- // 동적 Truncation
- int offset = hash[hash.length - 1] & 0xF;
- long binary =
- ((hash[offset] & 0x7f) << 24) |
- ((hash[offset + 1] & 0xff) << 16) |
- ((hash[offset + 2] & 0xff) << 8) |
- (hash[offset + 3] & 0xff);
-
- long otp = binary % (long) Math.pow(10, digit);
-
- // 0 패딩
- return String.format("%0" + digit + "d", otp);
-
- } catch (NoSuchAlgorithmException | InvalidKeyException e) {
- throw new RuntimeException("TOTP Generation Error", e);
- }
- }
-
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/auth/package-info.java b/src/main/java/space/qu4nt/entanglementlib/security/auth/package-info.java
deleted file mode 100644
index b0ceff2..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/auth/package-info.java
+++ /dev/null
@@ -1,12 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-/**
- * 인증 수단을 관리하기 위한 도구를 제공하는 패키지입니다.
- *
- * @author Q. T. Felix
- * @since 1.1.0
- */
-package space.qu4nt.entanglementlib.security.auth;
\ No newline at end of file
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/README.md b/src/main/java/space/qu4nt/entanglementlib/security/communication/README.md
deleted file mode 100644
index 87b6708..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# 얽힘 라이브러리: 통신
-
-얽힘 라이브러리는 아주 다양한 통신 프로토콜을 통해 세션을 생성하고 개별 세션에 대해 전략적인 암호화 대응이 가능하도록 강력한 아키텍처를 제공합니다.
\ No newline at end of file
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/ConnectionState.java b/src/main/java/space/qu4nt/entanglementlib/security/communication/session/ConnectionState.java
deleted file mode 100644
index a84fcd3..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/ConnectionState.java
+++ /dev/null
@@ -1,25 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.communication.session;
-
-public enum ConnectionState {
-
- /// 참여자가 TCP 연결되었지만, 핸드셰이킹을 시작하진 않았습니다.
- CONNECTING,
-
- /// 참여자가 핸드셰이킹합니다. 이 과정에 키 교환을 수행할 수
- /// 있습니다.
- HANDSHAKING,
-
- /// 참여자의 보안 터널이 활성화되었습니다.
- ESTABLISHED,
-
- /// 참여자가 연결을 중단하고 있습니다.
- CLOSING,
-
- /// 참여자의 연결이 완전히 종료되었습니다.
- CLOSED
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/Participant.java b/src/main/java/space/qu4nt/entanglementlib/security/communication/session/Participant.java
deleted file mode 100644
index d44cc19..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/Participant.java
+++ /dev/null
@@ -1,129 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.communication.session;
-
-import lombok.Getter;
-
-import java.io.IOException;
-import java.net.SocketAddress;
-import java.nio.ByteBuffer;
-import java.nio.channels.SocketChannel;
-import java.util.Queue;
-import java.util.concurrent.ConcurrentLinkedQueue;
-import java.util.concurrent.atomic.AtomicReference;
-
-/// 세션 참여자는 반드시 다음 세 가지의 핵심 요소를 포함해야 합니다.
-///
-/// 1. 식별자(identity) - 누구인가?
-/// 2. 연결 방법(transport) - 어떻게 왔는가?
-/// 3. 보안 방법(security) - 어떻게 암호화되나?
-///
-/// 이 클래스는 이러한 정보를 안고 연결될 '참여자'의 기본 스키마를
-/// 제공하며, 논블로킹 I/O를 위한 인바운드/아웃바운드 버퍼링을 지원합니다.
-///
-/// @author Q. T. Felix
-/// @since 1.1.0
-@Getter
-public class Participant {
-
- // 식별자 정보
- private final String id;
- private final ParticipantRole role;
- private final long connectedAt;
-
- // 네트워크 컨텍스트
- private final SocketChannel channel;
- private final SocketAddress remoteAddress;
-
- // TCP 분할(Fragmentation) 및 부분 쓰기(Partial Write) 처리를 위한 버퍼
- // 대형 PQC 키 교환 시 필수적입니다.
- private final ByteBuffer inboundBuffer;
-
- // 스레드 안전성을 위해 ConcurrentLinkedQueue 사용 (App스레드 -> IO스레드)
- private final Queue outboundQueue;
-
- // 보안 컨텍스트
- private final ParticipantSecurityContext participantSecurityContext;
-
- // 참여자 연결 상태 매니지먼트
- private final AtomicReference state;
-
- public Participant(String id, ParticipantRole role, SocketChannel channel, int bufferSize, ParticipantSecurityContext participantSecurityContext) {
- this.id = id;
- this.role = role;
- this.channel = channel;
- this.remoteAddress = channel.socket().getRemoteSocketAddress();
- this.connectedAt = System.currentTimeMillis();
-
- // zero-copy 성능을 위한 직접 버퍼 할당
- this.inboundBuffer = ByteBuffer.allocateDirect(bufferSize);
-
- // ArrayDeque는 스레드 안전하지 않으므로 ConcurrentLinkedQueue로 변경
- this.outboundQueue = new ConcurrentLinkedQueue<>();
-
- this.participantSecurityContext = participantSecurityContext;
- this.state = new AtomicReference<>(ConnectionState.CONNECTING);
- }
-
- public boolean isSecure() {
- return state.get() == ConnectionState.ESTABLISHED;
- }
-
- public void transitionState(ConnectionState newState) {
- // TODO: 상태 전이 검증 로직 (예: CLOSED 상태에서는 변경 불가 등)
- this.state.set(newState);
- }
-
- /// 전송할 데이터를 아웃바운드 큐에 등록합니다.
- /// 실제 전송은 Selector의 OP_WRITE 이벤트 루프에서 처리됩니다.
- ///
- /// @param data 전송할 데이터가 담긴 ByteBuffer
- public void enqueueMessage(ByteBuffer data) {
- if (data != null && data.hasRemaining()) {
- outboundQueue.offer(data);
- }
- }
-
- /// 아웃바운드 큐에 쌓인 데이터를 채널로 전송을 시도합니다.
- /// 논블로킹 모드이므로 데이터가 전부 전송되지 않을 수 있습니다.
- ///
- /// @return true면 아직 보낼 데이터가 남음(OP_WRITE 유지 필요),
- /// false면 큐가 비었음(OP_WRITE 해제 가능)
- /// @throws IOException 채널 쓰기 중 오류 발생 시
- public boolean flushOutbound() throws IOException {
- ByteBuffer buffer;
-
- // 큐의 헤드(가장 먼저 들어온 데이터)를 확인
- while ((buffer = outboundQueue.peek()) != null) {
-
- // 채널에 쓰기 시도
- channel.write(buffer);
-
- // 1. Partial Write 발생: 채널 버퍼가 꽉 차서 데이터를 다 못 씀
- if (buffer.hasRemaining()) {
- // 루프 종료. 다음 OP_WRITE 이벤트 때 남은 부분부터 이어서 보냄
- return true;
- }
-
- // 2. Full Write 완료: 현재 버퍼를 다 썼으므로 큐에서 제거
- outboundQueue.poll();
- }
-
- // 큐가 비었음
- return false;
- }
-
- /// 아웃바운드 큐에 데이터가 있는지 확인합니다.
- public boolean hasOutboundData() {
- return !outboundQueue.isEmpty();
- }
-
- /// 리소스 정리 시 호출하여 메모리 누수를 방지합니다.
- public void cleanup() {
- outboundQueue.clear();
- // DirectBuffer는 GC가 처리하지만, 필요한 경우 명시적 해제 로직 추가 가능
- }
-}
\ No newline at end of file
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/ParticipantRole.java b/src/main/java/space/qu4nt/entanglementlib/security/communication/session/ParticipantRole.java
deleted file mode 100644
index a39d67b..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/ParticipantRole.java
+++ /dev/null
@@ -1,14 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.communication.session;
-
-public enum ParticipantRole {
-
- INITIATOR,
- RESPONDER,
- OBSERVER,
- CUSTOM
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/ParticipantSecurityContext.java b/src/main/java/space/qu4nt/entanglementlib/security/communication/session/ParticipantSecurityContext.java
deleted file mode 100644
index 598bf2b..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/ParticipantSecurityContext.java
+++ /dev/null
@@ -1,52 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.communication.session;
-
-import lombok.Getter;
-import space.qu4nt.entanglementlib.entlibnative.SensitiveDataContainer;
-
-import java.util.concurrent.atomic.AtomicLong;
-
-/// 세션 참여자의 암호화 컨텍스트를 관리하는 클래스입니다.
-///
-/// 얽힘 라이브러리 TLS 체계는 참여자가 세션에 접속할 때 이 컨텍스트를 가지고 있다고
-/// 예상합니다.
-///
-/// @author Q. T. Felix
-/// @see Session
-/// @since 1.1.0
-public class ParticipantSecurityContext {
-
- // 합의된 세션 키
- @Getter
- private volatile SensitiveDataContainer sessionKey;
-
- // AEAD의 논스 및 카운터
- // 수신 카운터
- private final AtomicLong readSequence = new AtomicLong(0);
- // 송신 카운터
- private final AtomicLong writeSequence = new AtomicLong(0);
-
- // 연결에 사용되는 특정 스트레티지(세션 기본값과 다를 경우)
- private String negotiatedStrategy;
-
- // 핸드셰이크 프레그먼트에 임시 저장
- private SensitiveDataContainer peerPublicKey;
-
- public ParticipantSecurityContext(SensitiveDataContainer sessionKey, String negotiatedStrategy, SensitiveDataContainer peerPublicKey) {
- this.sessionKey = sessionKey;
- this.negotiatedStrategy = negotiatedStrategy;
- this.peerPublicKey = peerPublicKey;
- }
-
- public long getNextWriteSequence() {
- return writeSequence.getAndIncrement();
- }
-
- public long getNextReadSequence() {
- return readSequence.getAndIncrement();
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/Session.java b/src/main/java/space/qu4nt/entanglementlib/security/communication/session/Session.java
deleted file mode 100644
index d363220..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/Session.java
+++ /dev/null
@@ -1,506 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.communication.session;
-
-import lombok.Getter;
-import lombok.extern.slf4j.Slf4j;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
-import space.qu4nt.entanglementlib.exception.session.EntLibSessionException;
-
-import java.util.*;
-import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.atomic.AtomicReference;
-import java.util.concurrent.locks.ReentrantReadWriteLock;
-import java.util.function.Consumer;
-import java.util.function.Predicate;
-
-/// 보안 통신 세션을 관리하는 클래스입니다.
-///
-/// 세션은 여러 참여자들이 보안 통신을 수행할 수 있는 논리적 컨텍스트를 제공합니다.
-/// 각 세션은 고유한 식별자, 세션 수준의 보안 컨텍스트, 그리고 참여자 목록을 관리합니다.
-///
-/// ## 주요 기능
-/// - 다수의 참여자 관리 (추가, 제거, 조회)
-/// - 세션 수준 보안 컨텍스트 관리
-/// - 세션 생명주기 관리 (생성, 활성, 종료)
-/// - 유연한 세션 설정 (최대 참여자 수, 타임아웃 등)
-/// - 스레드 안전 연산
-///
-/// ## 사용 예시
-/// ```java
-/// SessionConfig config = SessionConfig.builder()
-/// .maxParticipants(10)
-/// .sessionTimeout(Duration.ofMinutes(30))
-/// .build();
-///
-/// Session session = Session.create(config);
-/// session.addParticipant(participant);
-/// ```
-///
-/// @author Q. T. Felix
-/// @see Participant
-/// @see ParticipantSecurityContext
-/// @see SessionConfig
-/// @since 1.1.0
-@Slf4j
-@Getter
-public class Session {
-
- /// 세션 고유 식별자
- private final String sessionId;
-
- /// 세션 생성 시각 (Unix timestamp milliseconds)
- private final long createdAt;
-
- /// 세션 설정
- private final SessionConfig config;
-
- /// 세션 수준 보안 컨텍스트 (그룹 키, 공통 암호화 설정 등)
- private volatile SessionSecurityContext sessionSecurityContext;
-
- /// 세션 상태
- private final AtomicReference state;
-
- /// 참여자 저장소 (ID -> Participant)
- private final ConcurrentHashMap participants;
-
- /// 역할별 참여자 인덱스 (빠른 역할 기반 조회용)
- private final ConcurrentHashMap> participantsByRole;
-
- /// 참여자 목록 수정을 위한 읽기-쓰기 락
- private final ReentrantReadWriteLock participantsLock;
-
- /// 세션 이벤트 리스너
- private final List eventListeners;
-
- /// 마지막 활동 시각
- private volatile long lastActivityAt;
-
- //
- // factory - start
- //
-
- private Session(String sessionId, SessionConfig config) {
- this.sessionId = sessionId;
- this.createdAt = System.currentTimeMillis();
- this.lastActivityAt = this.createdAt;
- this.config = config;
-
- this.state = new AtomicReference<>(SessionState.CREATED);
- this.participants = new ConcurrentHashMap<>();
- this.participantsByRole = new ConcurrentHashMap<>();
- this.participantsLock = new ReentrantReadWriteLock();
- this.eventListeners = Collections.synchronizedList(new ArrayList<>());
-
- log.debug("세션 생성됨: {}", sessionId);
- }
-
- /// 기본 설정으로 새 세션을 생성합니다.
- ///
- /// @return 새로 생성된 세션
- public static Session create() {
- return create(SessionConfig.defaults());
- }
-
- /// 지정된 설정으로 새 세션을 생성합니다.
- ///
- /// @param config 세션 설정
- /// @return 새로 생성된 세션
- public static Session create(@NotNull SessionConfig config) {
- String sessionId = generateSessionId();
- return new Session(sessionId, config);
- }
-
- /// 지정된 ID와 설정으로 새 세션을 생성합니다.
- ///
- /// @param sessionId 세션 ID
- /// @param config 세션 설정
- /// @return 새로 생성된 세션
- public static Session create(@NotNull String sessionId, @NotNull SessionConfig config) {
- return new Session(sessionId, config);
- }
-
- private static String generateSessionId() {
- return UUID.randomUUID().toString();
- }
-
- //
- // factory - end
- //
-
- //
- // Participants - start
- //
-
- /// 세션에 참여자를 추가합니다.
- ///
- /// @param participant 추가할 참여자
- /// @return 추가 성공 여부
- /// @throws EntLibSessionException 세션이 활성 상태가 아니거나 최대 참여자 수 초과 시
- public boolean addParticipant(@NotNull Participant participant) throws EntLibSessionException {
- validateSessionActive();
-
- participantsLock.writeLock().lock();
- try {
- // 최대 참여자 수 확인
- if (config.getMaxParticipants() > 0 &&
- participants.size() >= config.getMaxParticipants()) {
- throw new EntLibSessionException("최대 참여자 수를 초과했습니다: " + config.getMaxParticipants());
- }
-
- // 중복 확인
- if (participants.containsKey(participant.getId())) {
- log.warn("이미 존재하는 참여자 ID: {}", participant.getId());
- return false;
- }
-
- // 참여자 추가
- participants.put(participant.getId(), participant);
-
- // 역할별 인덱스 업데이트
- participantsByRole
- .computeIfAbsent(participant.getRole(), k -> ConcurrentHashMap.newKeySet())
- .add(participant.getId());
-
- updateActivity();
- notifyListeners(listener -> listener.onParticipantJoined(this, participant));
-
- log.debug("참여자 추가됨: {} (역할: {})", participant.getId(), participant.getRole());
- return true;
- } finally {
- participantsLock.writeLock().unlock();
- }
- }
-
- /// 세션에서 참여자를 제거합니다.
- ///
- /// @param participantId 제거할 참여자 ID
- /// @return 제거된 참여자 (없으면 null)
- @Nullable
- public Participant removeParticipant(@NotNull String participantId) {
- participantsLock.writeLock().lock();
- try {
- Participant removed = participants.remove(participantId);
- if (removed != null) {
- // 역할별 인덱스에서도 제거
- Set roleSet = participantsByRole.get(removed.getRole());
- if (roleSet != null) {
- roleSet.remove(participantId);
- }
-
- updateActivity();
- notifyListeners(listener -> listener.onParticipantLeft(this, removed));
-
- log.debug("참여자 제거됨: {}", participantId);
- }
- return removed;
- } finally {
- participantsLock.writeLock().unlock();
- }
- }
-
- /// ID로 참여자를 조회합니다.
- ///
- /// @param participantId 참여자 ID
- /// @return 참여자 (없으면 null)
- @Nullable
- public Participant getParticipant(@NotNull String participantId) {
- return participants.get(participantId);
- }
-
- /// 특정 역할의 모든 참여자를 조회합니다.
- ///
- /// @param role 참여자 역할
- /// @return 해당 역할의 참여자 목록 (불변)
- @NotNull
- public List getParticipantsByRole(@NotNull ParticipantRole role) {
- participantsLock.readLock().lock();
- try {
- Set ids = participantsByRole.get(role);
- if (ids == null || ids.isEmpty()) {
- return Collections.emptyList();
- }
- return ids.stream()
- .map(participants::get)
- .filter(Objects::nonNull)
- .toList();
- } finally {
- participantsLock.readLock().unlock();
- }
- }
-
- /// 조건에 맞는 참여자들을 조회합니다.
- ///
- /// @param predicate 필터 조건
- /// @return 조건에 맞는 참여자 목록
- @NotNull
- public List findParticipants(@NotNull Predicate predicate) {
- participantsLock.readLock().lock();
- try {
- return participants.values().stream()
- .filter(predicate)
- .toList();
- } finally {
- participantsLock.readLock().unlock();
- }
- }
-
- /// 모든 참여자 목록을 반환합니다.
- ///
- /// @return 모든 참여자 목록 (불변)
- @NotNull
- public Collection getAllParticipants() {
- return Collections.unmodifiableCollection(participants.values());
- }
-
- /// 현재 참여자 수를 반환합니다.
- ///
- /// @return 참여자 수
- public int getParticipantCount() {
- return participants.size();
- }
-
- /// 세션에 참여자가 있는지 확인합니다.
- ///
- /// @param participantId 참여자 ID
- /// @return 존재 여부
- public boolean hasParticipant(@NotNull String participantId) {
- return participants.containsKey(participantId);
- }
-
- //
- // Participants - end
- //
-
- //
- // Session Status - start
- //
-
- /// 세션을 활성화합니다.
- ///
- /// @throws EntLibSessionException 세션이 이미 종료된 경우
- public void activate() throws EntLibSessionException {
- SessionState current = state.get();
- if (current == SessionState.CLOSED || current == SessionState.TERMINATED) {
- throw new EntLibSessionException("종료된 세션은 활성화할 수 없습니다.");
- }
-
- if (state.compareAndSet(SessionState.CREATED, SessionState.ACTIVE) ||
- state.compareAndSet(SessionState.SUSPENDED, SessionState.ACTIVE)) {
- updateActivity();
- notifyListeners(listener -> listener.onSessionStateChanged(this, current, SessionState.ACTIVE));
- log.info("세션 활성화됨: {}", sessionId);
- }
- }
-
- /// 세션을 일시 중단합니다.
- public void suspend() {
- SessionState current = state.get();
- if (current == SessionState.ACTIVE) {
- if (state.compareAndSet(SessionState.ACTIVE, SessionState.SUSPENDED)) {
- notifyListeners(listener -> listener.onSessionStateChanged(this, current, SessionState.SUSPENDED));
- log.info("세션 일시 중단됨: {}", sessionId);
- }
- }
- }
-
- /// 세션을 정상 종료합니다.
- /// 모든 참여자에게 종료를 알리고 리소스를 정리합니다.
- public void close() {
- SessionState current = state.get();
- if (current == SessionState.CLOSED || current == SessionState.TERMINATED) {
- return;
- }
-
- if (state.compareAndSet(current, SessionState.CLOSING)) {
- try {
- // 모든 참여자에게 종료 알림
- notifyListeners(listener -> listener.onSessionClosing(this));
-
- // 참여자 정리
- participantsLock.writeLock().lock();
- try {
- participants.values().forEach(p ->
- p.transitionState(ConnectionState.CLOSING));
- participants.clear();
- participantsByRole.clear();
- } finally {
- participantsLock.writeLock().unlock();
- }
-
- // 보안 컨텍스트 정리
- if (sessionSecurityContext != null) {
- sessionSecurityContext.clear();
- }
-
- state.set(SessionState.CLOSED);
- notifyListeners(listener -> listener.onSessionClosed(this));
- log.info("세션 종료됨: {}", sessionId);
- } catch (Exception e) {
- state.set(SessionState.TERMINATED);
- log.error("세션 종료 중 오류 발생: {}", sessionId, e);
- }
- }
- }
-
- /// 세션을 강제 종료합니다.
- public void terminate() {
- SessionState current = state.get();
- if (current != SessionState.TERMINATED) {
- state.set(SessionState.TERMINATED);
-
- participantsLock.writeLock().lock();
- try {
- participants.clear();
- participantsByRole.clear();
- } finally {
- participantsLock.writeLock().unlock();
- }
-
- if (sessionSecurityContext != null) {
- sessionSecurityContext.clear();
- }
-
- notifyListeners(listener -> listener.onSessionTerminated(this));
- log.warn("세션 강제 종료됨: {}", sessionId);
- }
- }
-
- /// 세션이 활성 상태인지 확인합니다.
- ///
- /// @return 활성 상태 여부
- public boolean isActive() {
- return state.get() == SessionState.ACTIVE;
- }
-
- /// 세션이 종료되었는지 확인합니다.
- ///
- /// @return 종료 여부
- public boolean isClosed() {
- SessionState current = state.get();
- return current == SessionState.CLOSED || current == SessionState.TERMINATED;
- }
-
- //
- // Session Status - end
- //
-
- //
- // SecurityContext - start
- //
-
- /// 세션 수준 보안 컨텍스트를 설정합니다.
- ///
- /// @param securityContext 설정할 보안 컨텍스트
- public void setSessionSecurityContext(@NotNull SessionSecurityContext securityContext) {
- this.sessionSecurityContext = securityContext;
- updateActivity();
- log.debug("세션 보안 컨텍스트 설정됨: {}", sessionId);
- }
-
- /// 세션의 모든 참여자가 보안 연결 상태인지 확인합니다.
- ///
- /// @return 모든 참여자가 보안 연결 상태면 true
- public boolean isFullySecure() {
- if (participants.isEmpty()) {
- return false;
- }
- return participants.values().stream().allMatch(Participant::isSecure);
- }
-
- //
- // SecurityContext - end
- //
-
- //
- // EventListener - start
- //
-
- /// 세션 이벤트 리스너를 등록합니다.
- ///
- /// @param listener 등록할 리스너
- public void addEventListener(@NotNull SessionEventListener listener) {
- eventListeners.add(listener);
- }
-
- /// 세션 이벤트 리스너를 제거합니다.
- ///
- /// @param listener 제거할 리스너
- public void removeEventListener(@NotNull SessionEventListener listener) {
- eventListeners.remove(listener);
- }
-
- private void notifyListeners(Consumer action) {
- for (SessionEventListener listener : eventListeners) {
- try {
- action.accept(listener);
- } catch (Exception e) {
- log.error("이벤트 리스너 실행 중 오류", e);
- }
- }
- }
-
- //
- // EventListener - end
- //
-
- //
- // Utility - start
- //
-
- private void validateSessionActive() throws EntLibSessionException {
- SessionState current = state.get();
- if (current != SessionState.ACTIVE && current != SessionState.CREATED) {
- throw new EntLibSessionException("세션이 활성 상태가 아닙니다: " + current);
- }
- }
-
- private void updateActivity() {
- this.lastActivityAt = System.currentTimeMillis();
- }
-
- /// 세션 유휴 시간을 반환합니다.
- ///
- /// @return 마지막 활동 이후 경과 시간 (밀리초)
- public long getIdleTime() {
- return System.currentTimeMillis() - lastActivityAt;
- }
-
- /// 세션 지속 시간을 반환합니다.
- ///
- /// @return 세션 생성 이후 경과 시간 (밀리초)
- public long getDuration() {
- return System.currentTimeMillis() - createdAt;
- }
-
- //
- // Utility - end
- //
-
- @Override
- public String toString() {
- return "Session{" +
- "sessionId='" + sessionId + '\'' +
- ", state=" + state.get() +
- ", participants=" + participants.size() +
- ", createdAt=" + createdAt +
- '}';
- }
-
- @Override
- public boolean equals(Object o) {
- if (this == o) return true;
- if (o == null || getClass() != o.getClass()) return false;
- Session session = (Session) o;
- return Objects.equals(sessionId, session.sessionId);
- }
-
- @Override
- public int hashCode() {
- return Objects.hash(sessionId);
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/SessionConfig.java b/src/main/java/space/qu4nt/entanglementlib/security/communication/session/SessionConfig.java
deleted file mode 100644
index 72080fd..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/SessionConfig.java
+++ /dev/null
@@ -1,163 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.communication.session;
-
-import lombok.Builder;
-import lombok.Getter;
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.security.crypto.KEMType;
-import space.qu4nt.entanglementlib.security.crypto.SignatureType;
-
-import java.time.Duration;
-
-/// 세션 설정을 담는 불변 클래스입니다.
-///
-/// 빌더 패턴을 사용하여 세션의 다양한 설정을 구성할 수 있습니다.
-///
-/// ## 사용 예시
-/// ```java
-/// SessionConfig config = SessionConfig.builder()
-/// .maxParticipants(10)
-/// .sessionTimeout(Duration.ofHours(1))
-/// .idleTimeout(Duration.ofMinutes(15))
-/// .kemType(KEMType.ML_KEM_768)
-/// .signatureType(SignatureType.ML_DSA_65)
-/// .build();
-/// ```
-///
-/// @author Q. T. Felix
-/// @see Session
-/// @since 1.1.0
-@Getter
-@Builder
-public class SessionConfig {
-
- /// 기본 최대 참여자 수 (0 = 무제한)
- public static final int DEFAULT_MAX_PARTICIPANTS = 0;
-
- /// 기본 세션 타임아웃 (24시간)
- public static final Duration DEFAULT_SESSION_TIMEOUT = Duration.ofHours(24);
-
- /// 기본 유휴 타임아웃 (30분)
- public static final Duration DEFAULT_IDLE_TIMEOUT = Duration.ofMinutes(30);
-
- /// 기본 인바운드 버퍼 크기 (64KB)
- public static final int DEFAULT_BUFFER_SIZE = 64 * 1024;
-
- /// 최대 참여자 수 (0 = 무제한)
- @Builder.Default
- private final int maxParticipants = DEFAULT_MAX_PARTICIPANTS;
-
- /// 세션 전체 타임아웃 (세션 생성 후 최대 유지 시간)
- @Builder.Default
- private final Duration sessionTimeout = DEFAULT_SESSION_TIMEOUT;
-
- /// 유휴 타임아웃 (마지막 활동 후 세션 종료까지 시간)
- @Builder.Default
- private final Duration idleTimeout = DEFAULT_IDLE_TIMEOUT;
-
- /// 참여자별 인바운드 버퍼 크기
- @Builder.Default
- private final int bufferSize = DEFAULT_BUFFER_SIZE;
-
- /// 세션에서 사용할 기본 KEM 알고리즘
- @Builder.Default
- private final KEMType defaultKemType = KEMType.ML_KEM_768;
-
- /// 세션에서 사용할 기본 서명 알고리즘
- @Builder.Default
- private final SignatureType defaultSignatureType = SignatureType.ML_DSA_65;
-
- /// 클래식 ECDH(X25519) 사용 여부 (하이브리드 모드용)
- @Builder.Default
- private final boolean useClassicEcdh = true;
-
- /// 자동 재연결 허용 여부
- @Builder.Default
- private final boolean allowReconnection = true;
-
- /// 재연결 허용 시간 (연결 끊김 후 재연결 가능 시간)
- @Builder.Default
- private final Duration reconnectionWindow = Duration.ofMinutes(5);
-
- /// 핸드셰이크 타임아웃
- @Builder.Default
- private final Duration handshakeTimeout = Duration.ofSeconds(30);
-
- /// 세션 이름 (선택적, 디버깅/로깅용)
- private final String sessionName;
-
- /// 세션 메타데이터 (사용자 정의 데이터)
- private final Object metadata;
-
- /// 기본 설정으로 SessionConfig를 생성합니다.
- ///
- /// @return 기본 설정의 SessionConfig
- @NotNull
- public static SessionConfig defaults() {
- return SessionConfig.builder().build();
- }
-
- /// 고보안 설정으로 SessionConfig를 생성합니다.
- /// [KEMType#X25519MLKEM768]과 [SignatureType#ML_DSA_87]을 사용하며,
- /// 짧은 타임아웃을 적용합니다.
- ///
- /// @return 고보안 설정의 SessionConfig
- @NotNull
- public static SessionConfig highSecurity() {
- return SessionConfig.builder()
- .defaultKemType(KEMType.X25519MLKEM768)
- .defaultSignatureType(SignatureType.ML_DSA_87)
- .sessionTimeout(Duration.ofHours(4))
- .idleTimeout(Duration.ofMinutes(10))
- .handshakeTimeout(Duration.ofSeconds(15))
- .allowReconnection(false)
- .build();
- }
-
- /// 경량 설정으로 SessionConfig를 생성합니다.
- /// ML-KEM-512와 ML-DSA-44를 사용하며, 긴 타임아웃을 적용합니다.
- ///
- /// @return 경량 설정의 SessionConfig
- @NotNull
- public static SessionConfig lightweight() {
- return SessionConfig.builder()
- .defaultKemType(KEMType.ML_KEM_512)
- .defaultSignatureType(SignatureType.ML_DSA_44)
- .sessionTimeout(Duration.ofHours(48))
- .idleTimeout(Duration.ofHours(2))
- .handshakeTimeout(Duration.ofSeconds(60))
- .build();
- }
-
- /// 세션 타임아웃을 밀리초 단위로 반환합니다.
- ///
- /// @return 세션 타임아웃 (밀리초)
- public long getSessionTimeoutMillis() {
- return sessionTimeout.toMillis();
- }
-
- /// 유휴 타임아웃을 밀리초 단위로 반환합니다.
- ///
- /// @return 유휴 타임아웃 (밀리초)
- public long getIdleTimeoutMillis() {
- return idleTimeout.toMillis();
- }
-
- /// 핸드셰이크 타임아웃을 밀리초 단위로 반환합니다.
- ///
- /// @return 핸드셰이크 타임아웃 (밀리초)
- public long getHandshakeTimeoutMillis() {
- return handshakeTimeout.toMillis();
- }
-
- /// 재연결 허용 시간을 밀리초 단위로 반환합니다.
- ///
- /// @return 재연결 허용 시간 (밀리초)
- public long getReconnectionWindowMillis() {
- return reconnectionWindow.toMillis();
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/SessionEventListener.java b/src/main/java/space/qu4nt/entanglementlib/security/communication/session/SessionEventListener.java
deleted file mode 100644
index 03bc23c..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/SessionEventListener.java
+++ /dev/null
@@ -1,82 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.communication.session;
-
-/// 세션 이벤트를 수신하는 리스너 인터페이스입니다.
-///
-/// 세션의 생명주기와 참여자 변경 이벤트를 처리할 수 있습니다.
-/// 모든 메소드는 기본 구현(no-op)을 제공하므로 필요한 이벤트만
-/// 선택적으로 오버라이드할 수 있습니다.
-///
-/// ## 사용 예시
-/// ```java
-/// session.addEventListener(new SessionEventListener() {
-/// @Override
-/// public void onParticipantJoined(Session session, Participant participant) {
-/// System.out.println("새 참여자: " + participant.getId());
-/// }
-/// });
-/// ```
-///
-/// @author Q. T. Felix
-/// @see Session
-/// @since 1.1.0
-public interface SessionEventListener {
-
- /// 참여자가 세션에 참여했을 때 호출됩니다.
- ///
- /// @param session 세션
- /// @param participant 참여한 참여자
- default void onParticipantJoined(Session session, Participant participant) {
- }
-
- /// 참여자가 세션에서 나갔을 때 호출됩니다.
- ///
- /// @param session 세션
- /// @param participant 나간 참여자
- default void onParticipantLeft(Session session, Participant participant) {
- }
-
- /// 세션 상태가 변경되었을 때 호출됩니다.
- ///
- /// @param session 세션
- /// @param oldState 이전 상태
- /// @param newState 새 상태
- default void onSessionStateChanged(Session session, SessionState oldState, SessionState newState) {
- }
-
- /// 세션이 종료 중일 때 호출됩니다.
- /// 정리 작업이 시작되기 전에 호출됩니다.
- ///
- /// @param session 세션
- default void onSessionClosing(Session session) {
- }
-
- /// 세션이 정상 종료되었을 때 호출됩니다.
- ///
- /// @param session 세션
- default void onSessionClosed(Session session) {
- }
-
- /// 세션이 강제 종료되었을 때 호출됩니다.
- ///
- /// @param session 세션
- default void onSessionTerminated(Session session) {
- }
-
- /// 세션 보안 컨텍스트가 변경되었을 때 호출됩니다.
- ///
- /// @param session 세션
- default void onSecurityContextChanged(Session session) {
- }
-
- /// 세션에서 오류가 발생했을 때 호출됩니다.
- ///
- /// @param session 세션
- /// @param throwable 발생한 오류
- default void onSessionError(Session session, Throwable throwable) {
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/SessionSecurityContext.java b/src/main/java/space/qu4nt/entanglementlib/security/communication/session/SessionSecurityContext.java
deleted file mode 100644
index 9935c32..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/SessionSecurityContext.java
+++ /dev/null
@@ -1,215 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.communication.session;
-
-import lombok.Getter;
-import lombok.extern.slf4j.Slf4j;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
-import space.qu4nt.entanglementlib.entlibnative.SensitiveDataContainer;
-import space.qu4nt.entanglementlib.exception.session.EntLibSessionIllegalStateException;
-import space.qu4nt.entanglementlib.security.crypto.KEMType;
-import space.qu4nt.entanglementlib.security.crypto.SignatureType;
-
-import java.util.concurrent.atomic.AtomicBoolean;
-import java.util.concurrent.atomic.AtomicLong;
-
-/// 세션 수준의 보안 컨텍스트를 관리하는 클래스입니다.
-///
-/// 이 클래스는 세션 전체에 적용되는 암호화 설정과 키 자료를 관리합니다.
-/// 개별 참여자의 [ParticipantSecurityContext]와 구분되며, 그룹 통신 시 공통으로
-/// 사용되는 보안 파라미터를 포함합니다.
-///
-/// ## 주요 구성 요소
-/// - 세션 마스터 키 (그룹 암호화용)
-/// - 협상된 암호화 알고리즘
-/// - 세션 수준 시퀀스 카운터
-///
-/// @author Q. T. Felix
-/// @see Session
-/// @see ParticipantSecurityContext
-/// @since 1.1.0
-@Slf4j
-@Getter
-public class SessionSecurityContext {
-
- /// 세션 마스터 키 (그룹 브로드캐스트 암호화용)
- private volatile SensitiveDataContainer sessionMasterKey;
-
- /// 세션 마스터 키 파생용 솔트
- private volatile SensitiveDataContainer masterKeySalt;
-
- /// 협상된 KEM 알고리즘
- private volatile KEMType negotiatedKemType;
-
- /// 협상된 서명 알고리즘
- private volatile SignatureType negotiatedSignatureType;
-
- /// 클래식 ECDH 사용 여부 (하이브리드 모드)
- private volatile boolean classicEcdhEnabled;
-
- /// 세션 수준 메시지 카운터 (리플레이 공격 방지)
- private final AtomicLong sessionMessageCounter;
-
- /// 마지막 키 갱신 시각
- private volatile long lastKeyRotationAt;
-
- /// 키 갱신 주기 (밀리초, 0이면 자동 갱신 안함)
- private volatile long keyRotationIntervalMillis;
-
- /// 컨텍스트 초기화 완료 여부
- private final AtomicBoolean initialized;
-
- /// 컨텍스트 정리 완료 여부
- private final AtomicBoolean cleared;
-
- public SessionSecurityContext() {
- this.sessionMessageCounter = new AtomicLong(0);
- this.initialized = new AtomicBoolean(false);
- this.cleared = new AtomicBoolean(false);
- this.lastKeyRotationAt = System.currentTimeMillis();
- this.keyRotationIntervalMillis = 0;
- }
-
- /// 세션 보안 컨텍스트를 초기화합니다.
- ///
- /// @param masterKey 세션 마스터 키
- /// @param salt 마스터 키 솔트
- /// @param kemType KEM 알고리즘
- /// @param signatureType 서명 알고리즘
- /// @param useClassicEcdh 클래식 ECDH 사용 여부
- public void initialize(
- @NotNull SensitiveDataContainer masterKey,
- @Nullable SensitiveDataContainer salt,
- @NotNull KEMType kemType,
- @NotNull SignatureType signatureType,
- boolean useClassicEcdh
- ) throws EntLibSessionIllegalStateException {
- if (cleared.get()) {
- throw new EntLibSessionIllegalStateException("정리된 보안 컨텍스트는 초기화할 수 없습니다.");
- }
-
- this.sessionMasterKey = masterKey;
- this.masterKeySalt = salt;
- this.negotiatedKemType = kemType;
- this.negotiatedSignatureType = signatureType;
- this.classicEcdhEnabled = useClassicEcdh;
- this.lastKeyRotationAt = System.currentTimeMillis();
-
- initialized.set(true);
- log.debug("세션 보안 컨텍스트 초기화됨: KEM={}, Sig={}, ClassicECDH={}",
- kemType, signatureType, useClassicEcdh);
- }
-
- /// 다음 세션 메시지 카운터 값을 반환하고 증가시킵니다.
- ///
- /// @return 현재 메시지 카운터 값
- public long getNextMessageCounter() {
- return sessionMessageCounter.getAndIncrement();
- }
-
- /// 현재 세션 메시지 카운터 값을 반환합니다.
- ///
- /// @return 현재 메시지 카운터 값
- public long getCurrentMessageCounter() {
- return sessionMessageCounter.get();
- }
-
- /// 키 갱신이 필요한지 확인합니다.
- ///
- /// @return 키 갱신 필요 여부
- public boolean needsKeyRotation() {
- if (keyRotationIntervalMillis <= 0) {
- return false;
- }
- return System.currentTimeMillis() - lastKeyRotationAt >= keyRotationIntervalMillis;
- }
-
- /// 세션 마스터 키를 갱신합니다.
- ///
- /// @param newMasterKey 새 마스터 키
- /// @param newSalt 새 솔트 (선택적)
- public void rotateKey(@NotNull SensitiveDataContainer newMasterKey,
- @Nullable SensitiveDataContainer newSalt) throws EntLibSessionIllegalStateException {
- if (!initialized.get())
- throw new EntLibSessionIllegalStateException("초기화되지 않은 보안 컨텍스트입니다.");
- if (cleared.get())
- throw new EntLibSessionIllegalStateException("정리된 보안 컨텍스트입니다.");
-
- // 기존 키 안전하게 정리
- SensitiveDataContainer oldKey = this.sessionMasterKey;
- SensitiveDataContainer oldSalt = this.masterKeySalt;
-
- this.sessionMasterKey = newMasterKey;
- this.masterKeySalt = newSalt;
- this.lastKeyRotationAt = System.currentTimeMillis();
-
- // 기존 키 안전하게 삭제
- if (oldKey != null)
- oldKey.close();
- if (oldSalt != null)
- oldSalt.close();
-
- log.debug("세션 마스터 키 갱신됨");
- }
-
- /// 키 갱신 주기를 설정합니다.
- ///
- /// @param intervalMillis 갱신 주기 (밀리초, 0이면 자동 갱신 안함)
- public void setKeyRotationInterval(long intervalMillis) {
- this.keyRotationIntervalMillis = intervalMillis;
- }
-
- /// 보안 컨텍스트가 초기화되었는지 확인합니다.
- ///
- /// @return 초기화 완료 여부
- public boolean isInitialized() {
- return initialized.get();
- }
-
- /// 보안 컨텍스트가 정리되었는지 확인합니다.
- ///
- /// @return 정리 완료 여부
- public boolean isCleared() {
- return cleared.get();
- }
-
- /// 보안 컨텍스트의 모든 민감한 데이터를 안전하게 정리합니다.
- ///
- /// 이 메소드 호출 후에는 컨텍스트를 더 이상 사용할 수 없습니다.
- public void clear() {
- if (cleared.compareAndSet(false, true)) {
- if (sessionMasterKey != null) {
- sessionMasterKey.close();
- sessionMasterKey = null;
- }
- if (masterKeySalt != null) {
- masterKeySalt.close();
- masterKeySalt = null;
- }
-
- sessionMessageCounter.set(0);
- initialized.set(false);
-
- log.debug("세션 보안 컨텍스트 정리됨");
- }
- }
-
- /// 보안 컨텍스트의 요약 정보를 반환합니다.
- ///
- /// @return 요약 문자열 (민감한 정보 제외)
- @Override
- public String toString() {
- return "SessionSecurityContext{" +
- "initialized=" + initialized.get() +
- ", cleared=" + cleared.get() +
- ", kemType=" + negotiatedKemType +
- ", signatureType=" + negotiatedSignatureType +
- ", classicEcdh=" + classicEcdhEnabled +
- ", messageCounter=" + sessionMessageCounter.get() +
- '}';
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/SessionState.java b/src/main/java/space/qu4nt/entanglementlib/security/communication/session/SessionState.java
deleted file mode 100644
index 4597753..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/session/SessionState.java
+++ /dev/null
@@ -1,32 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.communication.session;
-
-/// 세션의 생명주기 상태를 나타내는 열거형입니다.
-///
-/// @author Q. T. Felix
-/// @see Session
-/// @since 1.1.0
-public enum SessionState {
-
- /// 세션이 생성되었지만 아직 활성화되지 않았습니다.
- CREATED,
-
- /// 세션이 활성 상태입니다. 참여자가 참여하고 통신할 수 있습니다.
- ACTIVE,
-
- /// 세션이 일시 중단되었습니다. 새 참여자 참여가 차단됩니다.
- SUSPENDED,
-
- /// 세션이 종료 중입니다. 정리 작업이 진행 중입니다.
- CLOSING,
-
- /// 세션이 정상적으로 종료되었습니다.
- CLOSED,
-
- /// 세션이 오류로 인해 강제 종료되었습니다.
- TERMINATED
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/HandshakeMessage.java b/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/HandshakeMessage.java
deleted file mode 100644
index e1a44e5..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/HandshakeMessage.java
+++ /dev/null
@@ -1,157 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.communication.tls;
-
-/// TLS 핸드셰이크 메시지 타입을 정의하는 클래스입니다.
-///
-/// 포스트-퀀텀 TLS 핸드셰이크 프로토콜:
-/// 1. ClientHello: 클라이언트가 공개키와 지원 알고리즘 목록 전송
-/// 2. ServerHello: 서버가 자신의 공개키와 캡슐화된 공유 비밀 전송
-/// 3. Finished: 양측이 핸드셰이크 완료 확인
-///
-/// @author Q. T. Felix
-/// @see Server
-/// @since 1.1.0
-public final class HandshakeMessage {
-
- private HandshakeMessage() {
- }
-
- //
- // Message Types
- //
-
- /// 클라이언트 Hello 메시지
- /// 클라이언트가 연결 시작 시 전송하며, 공개키와 지원 알고리즘 포함
- public static final byte CLIENT_HELLO = 0x01;
-
- /// 서버 Hello 메시지
- /// 서버가 ClientHello에 응답하여 전송하며, 공개키와 캡슐화 결과 포함
- public static final byte SERVER_HELLO = 0x02;
-
- /// 인증서 메시지 (선택적)
- /// 서버 또는 클라이언트의 인증서 체인
- public static final byte CERTIFICATE = 0x03;
-
- /// 인증서 검증 메시지 (선택적)
- /// 인증서의 개인키 소유 증명
- public static final byte CERTIFICATE_VERIFY = 0x04;
-
- /// 핸드셰이크 완료 메시지
- /// 핸드셰이크 과정의 무결성 확인
- public static final byte FINISHED = 0x05;
-
- /// 키 업데이트 메시지
- /// 세션 중 키 갱신 요청
- public static final byte KEY_UPDATE = 0x06;
-
- /// 경고 메시지
- /// 오류 또는 경고 상황 알림
- public static final byte ALERT = 0x07;
-
- //
- // Alert Types
- //
-
- /// 경고 수준: 경고 (연결 유지)
- public static final byte ALERT_LEVEL_WARNING = 0x01;
-
- /// 경고 수준: 치명적 (연결 종료)
- public static final byte ALERT_LEVEL_FATAL = 0x02;
-
- //
- // Alert Descriptions
- //
-
- /// 정상 종료
- public static final byte ALERT_CLOSE_NOTIFY = 0x00;
-
- /// 예상치 못한 메시지
- public static final byte ALERT_UNEXPECTED_MESSAGE = 0x0A;
-
- /// 잘못된 MAC
- public static final byte ALERT_BAD_RECORD_MAC = 0x14;
-
- /// 핸드셰이크 실패
- public static final byte ALERT_HANDSHAKE_FAILURE = 0x28;
-
- /// 잘못된 인증서
- public static final byte ALERT_BAD_CERTIFICATE = 0x2A;
-
- /// 인증서 만료
- public static final byte ALERT_CERTIFICATE_EXPIRED = 0x2D;
-
- /// 알 수 없는 CA
- public static final byte ALERT_UNKNOWN_CA = 0x30;
-
- /// 프로토콜 버전 불일치
- public static final byte ALERT_PROTOCOL_VERSION = 0x46;
-
- /// 내부 오류
- public static final byte ALERT_INTERNAL_ERROR = 0x50;
-
- //
- // Protocol Version
- //
-
- /// 프로토콜 버전 1.0
- public static final byte VERSION_1_0 = 0x01;
-
- //
- // Key Exchange Algorithms
- //
-
- /// ML-KEM-512
- public static final byte KE_ML_KEM_512 = 0x01;
-
- /// ML-KEM-768
- public static final byte KE_ML_KEM_768 = 0x02;
-
- /// ML-KEM-1024
- public static final byte KE_ML_KEM_1024 = 0x03;
-
- /// X25519
- public static final byte KE_X25519 = 0x10;
-
- /// X25519 + ML-KEM-768 (하이브리드)
- public static final byte KE_X25519_ML_KEM_768 = 0x20;
-
- //
- // Utility Methods
- //
-
- /// 메시지 타입의 이름을 반환합니다.
- ///
- /// @param type 메시지 타입
- /// @return 메시지 타입 이름
- public static String getTypeName(byte type) {
- return switch (type) {
- case CLIENT_HELLO -> "ClientHello";
- case SERVER_HELLO -> "ServerHello";
- case CERTIFICATE -> "Certificate";
- case CERTIFICATE_VERIFY -> "CertificateVerify";
- case FINISHED -> "Finished";
- case KEY_UPDATE -> "KeyUpdate";
- case ALERT -> "Alert";
- default -> "Unknown(" + type + ")";
- };
- }
-
- /// 키 교환 알고리즘의 이름을 반환합니다.
- ///
- /// @param algorithm 알고리즘 식별자
- /// @return 알고리즘 이름
- public static String getKeyExchangeName(byte algorithm) {
- return switch (algorithm) {
- case KE_ML_KEM_512 -> "ML-KEM-512";
- case KE_ML_KEM_768 -> "ML-KEM-768";
- case KE_ML_KEM_1024 -> "ML-KEM-1024";
- case KE_X25519 -> "X25519";
- case KE_X25519_ML_KEM_768 -> "X25519+ML-KEM-768";
- default -> "Unknown(" + algorithm + ")";
- };
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/Server.java b/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/Server.java
deleted file mode 100644
index edbdfda..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/Server.java
+++ /dev/null
@@ -1,859 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.communication.tls;
-
-import lombok.Getter;
-import lombok.extern.slf4j.Slf4j;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
-import space.qu4nt.entanglementlib.entlibnative.SensitiveDataContainer;
-import space.qu4nt.entanglementlib.exception.secure.EntLibSecureIllegalArgumentException;
-import space.qu4nt.entanglementlib.exception.secure.EntLibSecureIllegalStateException;
-import space.qu4nt.entanglementlib.exception.secure.crypto.EntLibCryptoCipherProcessException;
-import space.qu4nt.entanglementlib.exception.server.EntLibServerIllegalStateException;
-import space.qu4nt.entanglementlib.exception.server.EntLibServerSecurityWarningException;
-import space.qu4nt.entanglementlib.exception.session.EntLibSessionException;
-import space.qu4nt.entanglementlib.security.communication.session.*;
-import space.qu4nt.entanglementlib.security.crypto.*;
-import space.qu4nt.entanglementlib.security.crypto.key.strategy.EntLibAsymmetricKeyStrategy;
-import space.qu4nt.entanglementlib.security.crypto.key.strategy.detail.MLKEMKeyStrategy;
-import space.qu4nt.entanglementlib.security.crypto.key.strategy.detail.X25519KeyStrategy;
-import space.qu4nt.entanglementlib.security.crypto.key.strategy.detail.X25519MLKEM768KeyStrategy;
-import space.qu4nt.entanglementlib.security.crypto.strategy.BlockCipherStrategy;
-import space.qu4nt.entanglementlib.security.crypto.strategy.CipherStrategy;
-import space.qu4nt.entanglementlib.security.crypto.strategy.NativeECDHStrategy;
-import space.qu4nt.entanglementlib.security.crypto.strategy.NativeKEMStrategy;
-import space.qu4nt.entanglementlib.util.wrapper.Pair;
-
-import java.io.Closeable;
-import java.io.IOException;
-import java.net.InetSocketAddress;
-import java.net.SocketAddress;
-import java.nio.ByteBuffer;
-import java.nio.channels.*;
-import java.util.Iterator;
-import java.util.Map;
-import java.util.Set;
-import java.util.UUID;
-import java.util.concurrent.*;
-import java.util.concurrent.atomic.AtomicBoolean;
-import java.util.concurrent.atomic.AtomicReference;
-
-/// PQC를 지원하는 TLS 서버 구현체입니다.
-///
-/// 이 서버는 NIO(Non-blocking I/O)를 사용하여 다수의 클라이언트 연결을
-/// 효율적으로 처리합니다. ML-KEM, X25519 등의 키 캡슐화 메커니즘을 통해
-/// 양자 내성 보안 통신을 제공합니다.
-///
-/// ## 주요 기능
-/// - NIO 기반 비동기 네트워크 처리
-/// - 세션 기반 연결 관리
-/// - 양자-내성 키 교환 (ML-KEM-512/768/1024)
-/// - 하이브리드 모드 (X25519 + ML-KEM)
-/// - 자동 핸드셰이크 타임아웃 처리
-///
-/// ## 사용 예시
-/// ```java
-/// ServerConfig config = ServerConfig.builder()
-/// .port(8443)
-/// .sessionConfig(SessionConfig.highSecurity())
-/// .build();
-///
-/// Server server = new Server(config);
-/// server.start();
-/// ```
-///
-/// @author Q. T. Felix
-/// @see Session
-/// @see NativeKEMStrategy
-/// @see NativeECDHStrategy
-/// @since 1.1.0
-@Slf4j
-public class Server implements Closeable {
-
- //
- // Constants
- //
-
- private static final int SELECT_TIMEOUT_MS = 100;
- private static final int HANDSHAKE_CHECK_INTERVAL_MS = 1000;
- private static final int MAX_HANDSHAKE_MSG_SIZE = 16 * 1024;
-
- //
- // Configuration
- //
-
- @Getter
- private final ServerConfig config;
-
- //
- // Network Components
- //
-
- private ServerSocketChannel serverChannel;
- private Selector selector;
-
- //
- // Server State
- //
-
- private final AtomicReference state;
- private final AtomicBoolean running;
-
- //
- // Session Management
- //
-
- /// 활성 세션 저장소 (세션 ID -> 세션)
- private final ConcurrentHashMap activeSessions;
-
- /// 채널별 참여자 매핑 (빠른 조회용)
- private final ConcurrentHashMap channelToParticipant;
-
- /// 참여자별 세션 매핑
- private final ConcurrentHashMap participantToSession;
-
- //
- // Security Components
- //
-
- /// 서버의 장기 키페어 (인증용)
- private SensitiveDataContainer serverPublicKey;
- private SensitiveDataContainer serverSecretKey;
-
- //
- // Thread Management
- //
-
- private Thread acceptThread;
- private Thread eventLoopThread;
- private ScheduledExecutorService scheduledExecutor;
-
- //
- // Event Listeners
- //
-
- private final CopyOnWriteArrayList eventListeners;
-
- //
- // Constructor
- //
-
- /// 지정된 설정으로 서버를 생성합니다.
- ///
- /// @param config 서버 설정
- public Server(@NotNull ServerConfig config) {
- this.config = config;
- this.state = new AtomicReference<>(ServerState.CREATED);
- this.running = new AtomicBoolean(false);
-
- this.activeSessions = new ConcurrentHashMap<>();
- this.channelToParticipant = new ConcurrentHashMap<>();
- this.participantToSession = new ConcurrentHashMap<>();
-
- this.eventListeners = new CopyOnWriteArrayList<>();
-
- log.debug("서버 인스턴스 생성됨: 포트 {}", config.getPort());
- }
-
- /// 기본 설정으로 서버를 생성합니다.
- ///
- /// @param port 서버 포트
- public Server(int port) {
- this(ServerConfig.builder().port(port).build());
- }
-
- //
- // Lifecycle Management
- //
-
- /// 서버를 시작합니다.
- ///
- /// @throws IOException 네트워크 오류 발생 시
- public void start() throws IOException {
- if (!state.compareAndSet(ServerState.CREATED, ServerState.STARTING)) {
- throw new IllegalStateException("서버가 이미 시작되었거나 종료된 상태입니다: " + state.get());
- }
-
- try {
- initializeServerKeys();
- initializeNetwork();
- initializeThreads();
-
- running.set(true);
- state.set(ServerState.RUNNING);
-
- notifyListeners(listener -> listener.onServerStarted(this));
- log.info("서버 시작됨: {}:{}", config.getBindAddress(), config.getPort());
- } catch (Throwable e) {
- state.set(ServerState.FAILED);
- cleanup();
- throw new IOException("서버 시작 실패", e);
- }
- }
-
- /// 서버를 정상 종료합니다.
- public void stop() {
- if (!running.compareAndSet(true, false)) {
- return;
- }
-
- state.set(ServerState.STOPPING);
- log.info("서버 종료 중...");
-
- try {
- // 모든 세션 종료
- activeSessions.values().forEach(Session::close);
-
- // 스레드 종료 대기
- if (scheduledExecutor != null) {
- scheduledExecutor.shutdown();
- scheduledExecutor.awaitTermination(5, TimeUnit.SECONDS);
- }
-
- // 네트워크 리소스 정리
- cleanup();
-
- state.set(ServerState.STOPPED);
- notifyListeners(listener -> listener.onServerStopped(this));
- log.info("서버 종료 완료");
- } catch (Exception e) {
- state.set(ServerState.FAILED);
- log.error("서버 종료 중 오류", e);
- }
- }
-
- @Override
- public void close() {
- stop();
- }
-
- //
- // Initialization
- //
-
- private void initializeServerKeys() throws Throwable {
- // 서버 장기 키페어 생성 (기본 KEM 타입 사용)
- KEMType kemType = config.getSessionConfig().getDefaultKemType();
- EntLibAsymmetricKeyStrategy keyStrategy =
- EntLibCryptoRegistry.getKeyStrategy(kemType, EntLibAsymmetricKeyStrategy.class);
-
- if (keyStrategy instanceof X25519MLKEM768KeyStrategy hybridKey) {
- X25519KeyStrategy x25519KeyStrategy = EntLibCryptoRegistry.getKeyStrategy(KEMType.X25519, X25519KeyStrategy.class);
- MLKEMKeyStrategy mlkem768KeyStrategy = EntLibCryptoRegistry.getKeyStrategy(KEMType.ML_KEM_768, MLKEMKeyStrategy.class);
- hybridKey.setX25519Key(x25519KeyStrategy);
- hybridKey.setMlkem768Key(mlkem768KeyStrategy);
- log.debug("X25519MLKEM768 하이브리드 알고리즘에 따른 개별 스트레티지 주입");
- }
-
- Pair keyPair = keyStrategy.generateKeyPair();
- this.serverPublicKey = keyPair.getFirst();
- this.serverSecretKey = keyPair.getSecond();
-
- log.debug("서버 키페어 생성 완료: {}", kemType);
- }
-
- private void initializeNetwork() throws IOException {
- // Selector 생성
- this.selector = Selector.open();
-
- // 서버 소켓 채널 설정
- this.serverChannel = ServerSocketChannel.open();
- serverChannel.configureBlocking(false);
- serverChannel.socket().setReuseAddress(true);
-
- // 바인드
- SocketAddress bindAddress = new InetSocketAddress(
- config.getBindAddress(),
- config.getPort()
- );
- serverChannel.bind(bindAddress, config.getBacklog());
-
- // Accept 이벤트 등록
- serverChannel.register(selector, SelectionKey.OP_ACCEPT);
-
- log.debug("네트워크 초기화 완료: {}", bindAddress);
- }
-
- private void initializeThreads() {
- // 이벤트 루프 스레드
- this.eventLoopThread = new Thread(this::eventLoop, "TLS-Server-EventLoop");
- eventLoopThread.setDaemon(true);
- eventLoopThread.start();
-
- // 스케줄러 (타임아웃 체크 등)
- this.scheduledExecutor = Executors.newSingleThreadScheduledExecutor(r -> {
- Thread t = new Thread(r, "TLS-Server-Scheduler");
- t.setDaemon(true);
- return t;
- });
-
- // 핸드셰이크 타임아웃 체크
- scheduledExecutor.scheduleAtFixedRate(
- this::checkHandshakeTimeouts,
- HANDSHAKE_CHECK_INTERVAL_MS,
- HANDSHAKE_CHECK_INTERVAL_MS,
- TimeUnit.MILLISECONDS
- );
-
- // 세션 타임아웃 체크
- scheduledExecutor.scheduleAtFixedRate(
- this::checkSessionTimeouts,
- 5000,
- 5000,
- TimeUnit.MILLISECONDS
- );
-
- log.debug("스레드 초기화 완료");
- }
-
- //
- // Event Loop
- //
-
- private void eventLoop() {
- log.debug("이벤트 루프 시작");
-
- while (running.get()) {
- try {
- int readyCount = selector.select(SELECT_TIMEOUT_MS);
-
- if (readyCount == 0) {
- continue;
- }
-
- Set selectedKeys = selector.selectedKeys();
- Iterator iterator = selectedKeys.iterator();
-
- while (iterator.hasNext()) {
- SelectionKey key = iterator.next();
- iterator.remove();
-
- try {
- if (!key.isValid()) {
- continue;
- }
-
- if (key.isAcceptable()) {
- handleAccept(key);
- } else if (key.isReadable()) {
- handleRead(key);
- } else if (key.isWritable()) {
- handleWrite(key);
- }
- } catch (CancelledKeyException e) {
- log.debug("취소된 키: {}", key);
- } catch (Exception e) {
- log.error("키 처리 중 오류", e);
- closeChannel(key);
- }
- }
- } catch (ClosedSelectorException e) {
- log.debug("Selector 종료됨");
- break;
- } catch (Exception e) {
- if (running.get()) {
- log.error("이벤트 루프 오류", e);
- }
- }
- }
-
- log.debug("이벤트 루프 종료");
- }
-
- //
- // Connection Handling
- //
-
- private void handleAccept(SelectionKey key) throws IOException {
- ServerSocketChannel serverCh = (ServerSocketChannel) key.channel();
- SocketChannel clientChannel = serverCh.accept();
-
- if (clientChannel == null) {
- return;
- }
-
- clientChannel.configureBlocking(false);
-
- // 참여자 생성
- String participantId = UUID.randomUUID().toString();
- ParticipantSecurityContext securityContext = new ParticipantSecurityContext(null, null, null);
- Participant participant = new Participant(
- participantId,
- ParticipantRole.RESPONDER,
- clientChannel,
- config.getSessionConfig().getBufferSize(),
- securityContext
- );
-
- // 채널 매핑
- channelToParticipant.put(clientChannel, participant);
-
- // 세션 생성 또는 기존 세션에 추가
- Session session = getOrCreateSession();
- try {
- session.addParticipant(participant);
- participantToSession.put(participantId, session);
- } catch (EntLibSessionException e) {
- log.error("참여자 추가 실패", e);
- clientChannel.close();
- channelToParticipant.remove(clientChannel);
- return;
- }
-
- // READ 이벤트 등록
- clientChannel.register(selector, SelectionKey.OP_READ, participant);
-
- // 핸드셰이크 시작
- participant.transitionState(ConnectionState.HANDSHAKING);
-
- notifyListeners(listener -> listener.onClientConnected(this, participant));
- log.debug("새 클라이언트 연결: {} ({})", participantId, clientChannel.getRemoteAddress());
- }
-
- private void handleRead(SelectionKey key) throws IOException {
- SocketChannel channel = (SocketChannel) key.channel();
- Participant participant = (Participant) key.attachment();
-
- if (participant == null) {
- participant = channelToParticipant.get(channel);
- }
-
- if (participant == null) {
- log.warn("알 수 없는 채널에서 읽기 이벤트");
- closeChannel(key);
- return;
- }
-
- ByteBuffer buffer = participant.getInboundBuffer();
- int bytesRead;
-
- try {
- bytesRead = channel.read(buffer);
- } catch (IOException e) {
- log.debug("읽기 오류: {}", e.getMessage());
- closeChannel(key);
- return;
- }
-
- if (bytesRead == -1) {
- // 연결 종료
- log.debug("클라이언트 연결 종료: {}", participant.getId());
- closeChannel(key);
- return;
- }
-
- if (bytesRead > 0) {
- buffer.flip();
-
- ConnectionState state = participant.getState().get();
- if (state == ConnectionState.HANDSHAKING) {
- processHandshake(participant, buffer);
- } else if (state == ConnectionState.ESTABLISHED) {
- processApplicationData(participant, buffer);
- }
-
- buffer.compact();
- }
- }
-
- private void handleWrite(SelectionKey key) throws IOException {
- Participant participant = (Participant) key.attachment();
- if (participant == null) {
- key.cancel();
- return;
- }
-
- // 큐에 있는 데이터를 채널로 밀어넣음
- boolean hasRemaining = participant.flushOutbound();
-
- // 더 이상 보낼 데이터가 없다면 OP_WRITE 관심 해제 (CPU 점유 방지)
- if (!hasRemaining) {
- key.interestOps(key.interestOps() & ~SelectionKey.OP_WRITE);
- }
- }
-
- //
- // Handshake Processing
- //
-
- private void processHandshake(Participant participant, ByteBuffer data) {
- try {
- // 간단한 핸드셰이크 프로토콜 구현
- // 1. 클라이언트 Hello (공개키 포함)
- // 2. 서버 Hello (캡슐화된 공유 비밀)
- // 3. 핸드셰이크 완료
-
- if (data.remaining() < 1) {
- return;
- }
-
- byte messageType = data.get();
-
- switch (messageType) {
- case HandshakeMessage.CLIENT_HELLO -> handleClientHello(participant, data);
- case HandshakeMessage.FINISHED -> handleClientFinished(participant, data);
- default -> log.warn("알 수 없는 핸드셰이크 메시지: {}", messageType);
- }
- } catch (Exception e) {
- log.error("핸드셰이크 처리 오류: {}", participant.getId(), e);
- closeParticipant(participant);
- }
- }
-
- private void handleClientHello(Participant participant, ByteBuffer data) throws Exception {
- // 클라이언트 공개키 읽기
- // 헤더(길이 필드) 확인 가능한지 체크
- if (data.remaining() < 4) return;
-
- // 포지션 이동 없이 길이만 확인(PEEK)
- data.mark();
- int keyLength = data.getInt();
-
- if (keyLength < 0 || keyLength > MAX_HANDSHAKE_MSG_SIZE) {
- throw new EntLibServerSecurityWarningException("핸드셰이크 상한선 초과",
- "클라이언트 헬로(handleClientHello) 과정에서 키 길이 '" + keyLength + "'를 전달받았지만 방어했습니다!\n" +
- "\t이는 단순 연산 오류일 수 있지만, 공격자의 악의적 소행일 가능성이 상대적으로 높습니다. 공격자는 다음의 공격을 시도했을 수 있습니다.\n" +
- "\t\t1. '" + Integer.MAX_VALUE + "' 이상의 데이터를 전송하여 2GB 이상의 (바이트) 배열을 할당하려 시도합니다.\n" +
- "\t\t2. 그럼, 서버 측은 수십 개의 연결만으로도 힙 메모리가 고갈되어 `OutOfMemoryError`로 서버가 다운될 수 있습니다.\n" +
- "\t예외적으로 전달받은 값이 '0' 미만일 수 있습니다만, 이 경우는 사실 말이 안 됩니다.\n" +
- "\t우선 어찌됐던 이 시도를 막아내었지만, 추가적인 보안 조치가 필요할 수 있습니다."
- );
- }
-
- // 전체 바디가 도착했는지 확인
- if (data.remaining() < keyLength) {
- data.reset(); // 포지션 원복
- return; // 다음 패킷 기다림
- }
-
- // 데이터 읽기(COMMIT)
- byte[] clientPublicKeyBytes = new byte[keyLength];
- data.get(clientPublicKeyBytes);
-
- // 공개키 저장
- SensitiveDataContainer clientPublicKey = new SensitiveDataContainer(keyLength);
- clientPublicKey.getMemorySegment().asByteBuffer().put(clientPublicKeyBytes);
-
- // KEM 캡슐화 수행
- KEMType kemType = config.getSessionConfig().getDefaultKemType();
- NativeKEMStrategy kemStrategy = EntLibCryptoRegistry.getAlgStrategy(kemType, NativeKEMStrategy.class);
-
- final SensitiveDataContainer encapResult = kemStrategy.encapsulate(clientPublicKey);
-
- // 공유 비밀 추출 및 세션 키 설정
- // encapResult는 (sharedSecret, ciphertext)를 포함
- // TODO: 실제 세션 키 설정 로직
-
- // 서버 Hello 응답 전송
- sendServerHello(participant, encapResult);
-
- log.debug("Client Hello 처리 완료: {}", participant.getId());
- }
-
- private void sendServerHello(Participant participant, SensitiveDataContainer encapResult) throws IOException {
- SocketChannel channel = participant.getChannel();
-
- // 메시지 구성: [타입(1)] + [서버 공개키 길이(4)] + [서버 공개키] + [캡슐화 결과 길이(4)] + [캡슐화 결과]
- int serverPkLength = (int) serverPublicKey.getMemorySegment().byteSize();
- int encapLength = (int) encapResult.getMemorySegment().byteSize();
-
- ByteBuffer response = ByteBuffer.allocate(1 + 4 + serverPkLength + 4 + encapLength);
- response.put(HandshakeMessage.SERVER_HELLO);
- response.putInt(serverPkLength);
-
- ByteBuffer pkBuffer = serverPublicKey.getMemorySegment().asByteBuffer();
- response.put(pkBuffer);
-
- response.putInt(encapLength);
- ByteBuffer encapBuffer = encapResult.getMemorySegment().asByteBuffer();
- response.put(encapBuffer);
-
- response.flip();
- channel.write(response);
-
- log.debug("Server Hello 전송: {}", participant.getId());
- }
-
- private void handleClientFinished(Participant participant, ByteBuffer data) {
- // 핸드셰이크 완료 처리
- participant.transitionState(ConnectionState.ESTABLISHED);
-
- notifyListeners(listener -> listener.onHandshakeCompleted(this, participant));
- log.info("핸드셰이크 완료: {}", participant.getId());
- }
-
- //
- // Application Data Processing
- //
-
- private void processApplicationData(Participant participant, ByteBuffer data) {
- // 암호화된 애플리케이션 데이터 처리
- // TODO: 실제 복호화 및 데이터 처리 로직
-
- notifyListeners(listener -> listener.onDataReceived(this, participant, data));
- }
-
- //
- // Session Management
- //
-
- private Session getOrCreateSession() {
- // 단일 세션 모드 (설정에 따라 다중 세션 지원 가능)
- if (config.isSingleSessionMode() && !activeSessions.isEmpty()) {
- return activeSessions.values().iterator().next();
- }
-
- Session session = Session.create(config.getSessionConfig());
- try {
- session.activate();
- } catch (EntLibSessionException e) {
- log.error("세션 활성화 실패", e);
- }
- activeSessions.put(session.getSessionId(), session);
- return session;
- }
-
- /// 특정 세션을 조회합니다.
- ///
- /// @param sessionId 세션 ID
- /// @return 세션 (없으면 null)
- @Nullable
- public Session getSession(@NotNull String sessionId) {
- return activeSessions.get(sessionId);
- }
-
- /// 모든 활성 세션을 반환합니다.
- ///
- /// @return 활성 세션 맵 (불변)
- @NotNull
- public Map getActiveSessions() {
- return Map.copyOf(activeSessions);
- }
-
- /// 현재 연결된 클라이언트 수를 반환합니다.
- ///
- /// @return 연결된 클라이언트 수
- public int getConnectedClientCount() {
- return channelToParticipant.size();
- }
-
- //
- // Timeout Management
- //
-
- private void checkHandshakeTimeouts() {
- long now = System.currentTimeMillis();
- long timeout = config.getSessionConfig().getHandshakeTimeoutMillis();
-
- channelToParticipant.forEach((_, participant) -> {
- if (participant.getState().get() == ConnectionState.HANDSHAKING) {
- long elapsed = now - participant.getConnectedAt();
- if (elapsed > timeout) {
- log.warn("핸드셰이크 타임아웃: {}", participant.getId());
- closeParticipant(participant);
- }
- }
- });
- }
-
- private void checkSessionTimeouts() {
- long now = System.currentTimeMillis();
-
- activeSessions.forEach((id, session) -> {
- // 세션 전체 타임아웃
- if (session.getDuration() > session.getConfig().getSessionTimeoutMillis()) {
- log.info("세션 타임아웃 (전체): {}", id);
- session.close();
- activeSessions.remove(id);
- return;
- }
-
- // 유휴 타임아웃
- if (session.getIdleTime() > session.getConfig().getIdleTimeoutMillis()) {
- log.info("세션 타임아웃 (유휴): {}", id);
- session.close();
- activeSessions.remove(id);
- }
- });
- }
-
- //
- // Cleanup
- //
-
- private void closeChannel(SelectionKey key) {
- try {
- SocketChannel channel = (SocketChannel) key.channel();
- Participant participant = channelToParticipant.remove(channel);
-
- if (participant != null) {
- closeParticipant(participant);
- }
-
- key.cancel();
- channel.close();
- } catch (IOException e) {
- log.debug("채널 종료 오류", e);
- }
- }
-
- private void closeParticipant(Participant participant) {
- participant.transitionState(ConnectionState.CLOSED);
- channelToParticipant.remove(participant.getChannel());
-
- Session session = participantToSession.remove(participant.getId());
- if (session != null) {
- session.removeParticipant(participant.getId());
- }
-
- try {
- participant.getChannel().close();
- } catch (IOException e) {
- log.debug("참여자 채널 종료 오류", e);
- }
-
- notifyListeners(listener -> listener.onClientDisconnected(this, participant));
- }
-
- private void cleanup() {
- try {
- if (serverChannel != null && serverChannel.isOpen()) {
- serverChannel.close();
- }
- if (selector != null && selector.isOpen()) {
- selector.close();
- }
-
- // 키 정리
- if (serverSecretKey != null) {
- serverSecretKey.close();
- }
- if (serverPublicKey != null) {
- serverPublicKey.close();
- }
-
- } catch (IOException e) {
- log.error("리소스 정리 오류", e);
- }
- }
-
- //
- // Data Transmission
- //
-
- /// 특정 참여자에게 데이터를 전송합니다.
- /// 데이터는 즉시 전송을 시도하며, 소켓 버퍼가 가득 찬 경우
- /// 참여자의 OutboundQueue에 적재되고 OP_WRITE 이벤트를 통해 비동기로 처리됩니다.
- ///
- /// @param participant 대상 참여자
- /// @param data 전송할 데이터
- /// @throws IOException 전송 오류 시
- public void send(@NotNull Participant participant, @NotNull ByteBuffer data) throws IOException, EntLibServerIllegalStateException, EntLibSecureIllegalArgumentException, EntLibSecureIllegalStateException, EntLibCryptoCipherProcessException {
- if (participant.getState().get() != ConnectionState.ESTABLISHED) {
- throw new EntLibServerIllegalStateException("연결이 설정되지 않은 참여자입니다!");
- }
-
- {
- final byte[] plaintext = new byte[data.remaining()];
- long writeSequence = participant.getParticipantSecurityContext().getNextWriteSequence();
- BlockCipherStrategy aes256GCM = EntLibCryptoRegistry.getAlgStrategy(CipherType.AES_256, BlockCipherStrategy.class)
- .setMode(Mode.AEAD_GCM)
- .setPadding(Padding.NO);
- aes256GCM.iv(CipherStrategy.calculateNonce(SensitiveDataContainer.generateSafeRandomBytes(12), writeSequence));
- SensitiveDataContainer enc = aes256GCM.encrypt(
- participant.getParticipantSecurityContext().getSessionKey(),
- data.get(plaintext),
- false);
- participant.enqueueMessage(enc.getSegmentDataToByteBuffer());
- } // 암호화 및 enqueue
-
- boolean hasRemaining = participant.flushOutbound();
-
- if (hasRemaining) {
- SelectionKey key = participant.getChannel().keyFor(selector);
- if (key != null && key.isValid()) {
- key.interestOps(key.interestOps() | SelectionKey.OP_WRITE);
- selector.wakeup();
- }
- }
- }
-
- /// 특정 세션의 모든 참여자에게 데이터를 브로드캐스트합니다.
- ///
- /// @param session 대상 세션
- /// @param data 전송할 데이터
- public void broadcast(@NotNull Session session, @NotNull ByteBuffer data) {
- session.getAllParticipants().forEach(participant -> {
- try {
- if (participant.isSecure()) {
- ByteBuffer copy = data.duplicate();
- send(participant, copy);
- }
- } catch (EntLibSecureIllegalArgumentException | EntLibCryptoCipherProcessException |
- EntLibSecureIllegalStateException | EntLibServerIllegalStateException | IOException e) {
- log.error("브로드캐스트 전송 오류: {}", participant.getId(), e);
- }
- });
- }
-
- //
- // Event Listener Management
- //
-
- /// 서버 이벤트 리스너를 등록합니다.
- ///
- /// @param listener 등록할 리스너
- public void addEventListener(@NotNull ServerEventListener listener) {
- eventListeners.add(listener);
- }
-
- /// 서버 이벤트 리스너를 제거합니다.
- ///
- /// @param listener 제거할 리스너
- public void removeEventListener(@NotNull ServerEventListener listener) {
- eventListeners.remove(listener);
- }
-
- private void notifyListeners(java.util.function.Consumer action) {
- for (ServerEventListener listener : eventListeners) {
- try {
- action.accept(listener);
- } catch (Exception e) {
- log.error("리스너 실행 오류", e);
- }
- }
- }
-
- //
- // Status Methods
- //
-
- /// 서버가 실행 중인지 확인합니다.
- ///
- /// @return 실행 중 여부
- public boolean isRunning() {
- return running.get() && state.get() == ServerState.RUNNING;
- }
-
- /// 서버 상태를 반환합니다.
- ///
- /// @return 서버 상태
- @NotNull
- public ServerState getState() {
- return state.get();
- }
-
- @Override
- public String toString() {
- return "Server{" +
- "port=" + config.getPort() +
- ", state=" + state.get() +
- ", sessions=" + activeSessions.size() +
- ", clients=" + channelToParticipant.size() +
- '}';
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/ServerConfig.java b/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/ServerConfig.java
deleted file mode 100644
index e52c83e..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/ServerConfig.java
+++ /dev/null
@@ -1,98 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.communication.tls;
-
-import lombok.Builder;
-import lombok.Getter;
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.security.communication.session.SessionConfig;
-
-/// TLS 서버 설정을 담는 불변 클래스입니다.
-///
-/// ## 사용 예시
-/// ```java
-/// ServerConfig config = ServerConfig.builder()
-/// .port(8443)
-/// .bindAddress("0.0.0.0")
-/// .backlog(128)
-/// .sessionConfig(SessionConfig.highSecurity())
-/// .build();
-/// ```
-///
-/// @author Q. T. Felix
-/// @see Server
-/// @see SessionConfig
-/// @since 1.1.0
-@Getter
-@Builder
-public class ServerConfig {
-
- /// 기본 포트
- public static final int DEFAULT_PORT = 8443;
-
- /// 기본 바인드 주소
- public static final String DEFAULT_BIND_ADDRESS = "0.0.0.0";
-
- /// 기본 백로그 크기
- public static final int DEFAULT_BACKLOG = 128;
-
- /// 서버 포트
- @Builder.Default
- private final int port = DEFAULT_PORT;
-
- /// 바인드 주소
- @Builder.Default
- private final String bindAddress = DEFAULT_BIND_ADDRESS;
-
- /// 연결 대기열 크기 (백로그)
- @Builder.Default
- private final int backlog = DEFAULT_BACKLOG;
-
- /// 세션 설정
- @Builder.Default
- private final SessionConfig sessionConfig = SessionConfig.defaults();
-
- /// 단일 세션 모드 여부 (모든 클라이언트가 하나의 세션 공유)
- @Builder.Default
- private final boolean singleSessionMode = false;
-
- /// 서버 이름 (디버깅/로깅용)
- private final String serverName;
-
- /// 기본 설정으로 ServerConfig를 생성합니다.
- ///
- /// @return 기본 설정의 ServerConfig
- @NotNull
- public static ServerConfig defaults() {
- return ServerConfig.builder().build();
- }
-
- /// 개발용 설정으로 ServerConfig를 생성합니다.
- ///
- /// @param port 서버 포트
- /// @return 개발용 설정의 ServerConfig
- @NotNull
- public static ServerConfig development(int port) {
- return ServerConfig.builder()
- .port(port)
- .sessionConfig(SessionConfig.lightweight())
- .singleSessionMode(true)
- .build();
- }
-
- /// 프로덕션용 고보안 설정으로 ServerConfig를 생성합니다.
- ///
- /// @param port 서버 포트
- /// @return 프로덕션용 고보안 설정의 ServerConfig
- @NotNull
- public static ServerConfig production(int port) {
- return ServerConfig.builder()
- .port(port)
- .backlog(256)
- .sessionConfig(SessionConfig.highSecurity())
- .build();
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/ServerEventListener.java b/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/ServerEventListener.java
deleted file mode 100644
index d7519d0..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/ServerEventListener.java
+++ /dev/null
@@ -1,88 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.communication.tls;
-
-import space.qu4nt.entanglementlib.security.communication.session.Participant;
-
-import java.nio.ByteBuffer;
-
-/// TLS 서버 이벤트를 수신하는 리스너 인터페이스입니다.
-///
-/// 서버의 생명주기, 클라이언트 연결, 핸드셰이크, 데이터 수신 등의
-/// 이벤트를 처리할 수 있습니다. 모든 메소드는 기본 구현(no-op)을
-/// 제공하므로 필요한 이벤트만 선택적으로 오버라이드할 수 있습니다.
-///
-/// ## 사용 예시
-/// ```java
-/// server.addEventListener(new ServerEventListener() {
-/// @Override
-/// public void onClientConnected(Server server, Participant participant) {
-/// System.out.println("클라이언트 연결: " + participant.getId());
-/// }
-///
-/// @Override
-/// public void onHandshakeCompleted(Server server, Participant participant) {
-/// System.out.println("핸드셰이크 완료: " + participant.getId());
-/// }
-/// });
-/// ```
-///
-/// @author Q. T. Felix
-/// @see Server
-/// @since 1.1.0
-public interface ServerEventListener {
-
- /// 서버가 시작되었을 때 호출됩니다.
- ///
- /// @param server 서버 인스턴스
- default void onServerStarted(Server server) {
- }
-
- /// 서버가 종료되었을 때 호출됩니다.
- ///
- /// @param server 서버 인스턴스
- default void onServerStopped(Server server) {
- }
-
- /// 새 클라이언트가 연결되었을 때 호출됩니다.
- /// 핸드셰이크 시작 전에 호출됩니다.
- ///
- /// @param server 서버 인스턴스
- /// @param participant 연결된 참여자
- default void onClientConnected(Server server, Participant participant) {
- }
-
- /// 클라이언트 연결이 종료되었을 때 호출됩니다.
- ///
- /// @param server 서버 인스턴스
- /// @param participant 연결이 종료된 참여자
- default void onClientDisconnected(Server server, Participant participant) {
- }
-
- /// 클라이언트와의 핸드셰이크가 완료되었을 때 호출됩니다.
- /// 이 시점부터 보안 통신이 가능합니다.
- ///
- /// @param server 서버 인스턴스
- /// @param participant 핸드셰이크가 완료된 참여자
- default void onHandshakeCompleted(Server server, Participant participant) {
- }
-
- /// 클라이언트로부터 데이터를 수신했을 때 호출됩니다.
- /// 핸드셰이크 완료 후 애플리케이션 데이터만 전달됩니다.
- ///
- /// @param server 서버 인스턴스
- /// @param participant 데이터를 보낸 참여자
- /// @param data 수신된 데이터 (복호화된 상태)
- default void onDataReceived(Server server, Participant participant, ByteBuffer data) {
- }
-
- /// 서버에서 오류가 발생했을 때 호출됩니다.
- ///
- /// @param server 서버 인스턴스
- /// @param throwable 발생한 오류
- default void onServerError(Server server, Throwable throwable) {
- }
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/ServerState.java b/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/ServerState.java
deleted file mode 100644
index 024cac3..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/communication/tls/ServerState.java
+++ /dev/null
@@ -1,32 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.communication.tls;
-
-/// TLS 서버의 생명주기 상태를 나타내는 열거형입니다.
-///
-/// @author Q. T. Felix
-/// @see Server
-/// @since 1.1.0
-public enum ServerState {
-
- /// 서버가 생성되었지만 아직 시작되지 않았습니다.
- CREATED,
-
- /// 서버가 시작 중입니다. 리소스를 초기화하고 있습니다.
- STARTING,
-
- /// 서버가 실행 중이며 클라이언트 연결을 수락할 준비가 되었습니다.
- RUNNING,
-
- /// 서버가 종료 중입니다. 연결을 정리하고 있습니다.
- STOPPING,
-
- /// 서버가 정상적으로 종료되었습니다.
- STOPPED,
-
- /// 서버가 오류로 인해 실패했습니다.
- FAILED
-}
diff --git a/src/main/java/space/qu4nt/entanglementlib/security/crypto/AbstractStrategyBundle.java b/src/main/java/space/qu4nt/entanglementlib/security/crypto/AbstractStrategyBundle.java
deleted file mode 100644
index 93f7352..0000000
--- a/src/main/java/space/qu4nt/entanglementlib/security/crypto/AbstractStrategyBundle.java
+++ /dev/null
@@ -1,167 +0,0 @@
-/*
- * Copyright © 2025-2026 Quant.
- * Under License "PolyForm Noncommercial License 1.0.0".
- */
-
-package space.qu4nt.entanglementlib.security.crypto;
-
-import org.jetbrains.annotations.NotNull;
-import space.qu4nt.entanglementlib.security.crypto.key.EntLibKey;
-import space.qu4nt.entanglementlib.security.crypto.strategy.EntLibCryptoStrategy;
-
-import java.util.Collections;
-import java.util.Map;
-import java.util.Set;
-import java.util.concurrent.ConcurrentHashMap;
-
-/// 암호화 스트레티지와 키 스트레티지를 함께 래핑하여 레지스트리에 등록하기 위한 추상 클래스입니다.
-///
-/// 이 클래스를 상속하는 번들은 생성 시 자동으로 전역 번들 목록에 등록되며,
-/// [EntLibCryptoRegistry]에서 모든 번들의 스트레티지를 수집하여 사용합니다.
-/// ## 사용법
-///
-/// ```java
-/// public final class AESStrategyBundle extends AbstractStrategyBundle {
-/// // 싱글톤 인스턴스 - static 블록에서 자동 등록
-/// private static final AESStrategyBundle INSTANCE = new AESStrategyBundle();
-/// private AESStrategyBundle() {}
-/// @Override
-/// protected void registerStrategies() {
-/// register(CipherType.AES_128, new AESStrategy(CipherType.AES_128));
-/// register(CipherType.AES_192, new AESStrategy(CipherType.AES_192));
-/// register(CipherType.AES_256, new AESStrategy(CipherType.AES_256));
-/// }
-/// }
-/// ```
-///
-/// @author Q. T. Felix
-/// @since 1.1.0
-public abstract class AbstractStrategyBundle implements RegistrableStrategy {
-
- /**
- * 등록된 모든 번들을 저장하는 전역 집합입니다.
- *
- * Thread-safe한 {@link Set}을 사용합니다.
- */
- private static final Set REGISTERED_BUNDLES = ConcurrentHashMap.newKeySet();
-
- /**
- * 이 번들이 관리하는 스트레티지 맵입니다.
- */
- private final Map algStrategies = new ConcurrentHashMap<>();
-
- private final Map keyStrategies = new ConcurrentHashMap<>();
-
- /**
- * 스트레티지가 이미 등록되었는지 여부를 나타내는 플래그입니다.
- */
- private volatile boolean initialized = false;
-
- /**
- * 기본 생성자입니다.
- *
- * 인스턴스 생성 시 자동으로 전역 번들 목록에 등록됩니다.
- */
- protected AbstractStrategyBundle() {
- REGISTERED_BUNDLES.add(this);
- }
-
- /**
- * 하위 클래스에서 구현하여 스트레티지들을 등록하는 메소드입니다.
- *
- * {@link #register(EntLibAlgorithmType, EntLibCryptoStrategy, EntLibKey)} 메소드를 사용하여 등록합니다.
- */
- protected abstract void registerStrategies();
-
- /**
- * 스트레티지를 내부 맵에 등록하는 메소드입니다.
- *
- * @param type 알고리즘 타입
- * @param algStrategy 등록할 알고리즘 스트레티지
- * @param keyStrategy 등록할 키 스트레티지
- */
- protected final void register(@NotNull EntLibAlgorithmType type,
- @NotNull EntLibCryptoStrategy algStrategy,
- @NotNull EntLibKey keyStrategy) {
- algStrategies.put(type, algStrategy);
- keyStrategies.put(type, keyStrategy);
- }
-
- /**
- * 이 번들의 모든 스트레티지를 반환하는 메소드입니다.
- *
- * 처음 호출 시 {@link #registerStrategies()}가 실행됩니다.
- *
- * @return 등록된 스트레티지 맵 (읽기 전용)
- */
- @Override
- public final Map getAlgStrategies() {
- if (!initialized) {
- synchronized (this) {
- if (!initialized) {
- registerStrategies();
- initialized = true;
- }
- }
- }
- return Collections.unmodifiableMap(algStrategies);
- }
-
- /**
- * 이 번들의 모든 키 스트레티지를 반환하는 메소드입니다.
- *
- * 처음 호출 시 {@link #registerStrategies()}가 실행됩니다.
- *
- * @return 등록된 스트레티지 맵 (읽기 전용)
- */
- @Override
- public final Map getKeyStrategies() {
- if (!initialized) {
- synchronized (this) {
- if (!initialized) {
- registerStrategies();
- initialized = true;
- }
- }
- }
- return Collections.unmodifiableMap(keyStrategies);
- }
-
- /**
- * 등록된 모든 번들에서 스트레티지를 수집하여 반환하는 메소드입니다.
- *
- * @return 모든 번들의 스트레티지를 합친 맵
- */
- public static Map collectAllAlgStrategies() {
- Map result = new ConcurrentHashMap<>();
- for (AbstractStrategyBundle bundle : REGISTERED_BUNDLES) {
- result.putAll(bundle.getAlgStrategies());
- }
- return result;
- }
-
- /**
- * 등록된 모든 번들에서 키 스트레티지를 수집하여 반환하는 메소드입니다.
- *
- * @return 모든 번들의 키 스트레티지를 합친 맵
- */
- public static Map collectAllKeyStrategies() {
- Map