Skip to content

Commit afd11eb

Browse files
kcenonkcenon
committed
docs(security): add ISO/IEC 27001 control mapping
Publish docs/compliance/ISO_27001.md mapping the current codebase to ISO/IEC 27001:2022 Annex A controls (A.5.15, A.5.17, A.8.5, A.8.15, A.8.16, A.8.20, A.8.21, A.8.24, A.8.26, A.8.28) with source-code citations. Controls that depend on operator procedures are marked out of scope rather than claimed. Add a "Security Posture" section to README.md summarising the new default (USE_OPENSSL=ON) and linking to the compliance doc. Record the change under the Unreleased entry in docs/CHANGELOG.md. Relates to #569
1 parent 6ad9328 commit afd11eb

3 files changed

Lines changed: 280 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
- [Documentation](#documentation)
2222
- [CMake Integration](#cmake-integration)
2323
- [Production Quality](#production-quality)
24+
- [Security Posture](#security-posture)
2425
- [Performance Baselines](#performance-baselines)
2526
- [Contributing](#contributing)
2627
- [License](#license)
@@ -587,7 +588,8 @@ graph TD
587588
### Advanced Topics
588589
- 🏛️ [Architecture](docs/ARCHITECTURE.md) - System design and patterns
589590
- 📘 [API Reference](docs/API_REFERENCE.md) - Complete API documentation
590-
- 🔐 [Security Guide](SECURITY.md) - Security policy and reporting <!-- TODO: dedicated docs/advanced/SECURITY.md for TLS/SSL, RBAC, audit logging -->
591+
- 🔐 [Security Guide](SECURITY.md) - Security policy and reporting
592+
- 🛡️ [Security Posture](#security-posture) - TLS default, ISO/IEC 27001 mapping
591593
- 🔄 [Migration Guide](docs/advanced/MIGRATION.md) - Upgrading from previous versions
592594

593595
### Development
@@ -676,6 +678,26 @@ target_link_libraries(your_target PRIVATE database_system::database)
676678

677679
---
678680

681+
## Security Posture
682+
683+
**Secure defaults**: OpenSSL is enabled by default (`USE_OPENSSL=ON`). The
684+
`secure_connection` module therefore uses PBKDF2-HMAC-SHA256 for password
685+
hashing and AES-256-GCM for credential envelopes, and `security_credentials`
686+
defaults to `encryption_type::tls` with `verify_certificate=true`.
687+
688+
Passing `-DUSE_OPENSSL=OFF` is supported only for minimal embedded builds that
689+
cannot ship OpenSSL; CMake emits a `WARNING` in that case and the library falls
690+
back to placeholder crypto that is explicitly *not* production-grade.
691+
692+
**Standards mapping**: See [docs/compliance/ISO_27001.md](docs/compliance/ISO_27001.md)
693+
for a factual, source-cited mapping of implemented features to ISO/IEC 27001:2022
694+
Annex A controls (A.5.15, A.5.17, A.8.5, A.8.15, A.8.16, A.8.20, A.8.21, A.8.24,
695+
A.8.26, A.8.28). Out-of-scope controls are listed explicitly.
696+
697+
**Reporting vulnerabilities**: see [SECURITY.md](SECURITY.md).
698+
699+
---
700+
679701
## Performance Baselines
680702

681703
**See [docs/performance/BASELINE.md](docs/performance/BASELINE.md) for detailed baseline metrics**

‎docs/CHANGELOG.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,25 @@ category: "PROJ"
3838

3939
## [Unreleased] - 2026-01-23
4040

41+
### 🔐 **Security**
42+
43+
#### **Enable OpenSSL by default and publish ISO/IEC 27001 mapping (Issue #569)**
44+
- **`CMakeLists.txt`**: Introduced `USE_OPENSSL` option defaulting to `ON`. The
45+
`secure_connection` module now links OpenSSL (PBKDF2-HMAC-SHA256, AES-256-GCM)
46+
out of the box. `USE_OPENSSL=OFF` is still supported for minimal embedded
47+
builds but emits a CMake `WARNING` and drops the module to non-production
48+
placeholder crypto.
49+
- **New document**: `docs/compliance/ISO_27001.md` maps the current codebase to
50+
ISO/IEC 27001:2022 Annex A controls (A.5.15, A.5.17, A.8.5, A.8.15, A.8.16,
51+
A.8.20, A.8.21, A.8.24, A.8.26, A.8.28) with source-code citations. Out-of-
52+
scope controls are listed explicitly.
53+
- **`README.md`**: Added "Security Posture" section summarising the new default
54+
and linking to the compliance mapping.
55+
- **Note**: The default runtime TLS setting (`security_credentials::encryption =
56+
encryption_type::tls` with `verify_certificate = true`) was already in place;
57+
this change ensures the cryptographic primitives behind it are actually linked
58+
in the default build.
59+
4160
### 📚 **Documentation**
4261

4362
#### **Mark MongoDB and Redis Backends as Experimental (Issue #339)**

‎docs/compliance/ISO_27001.md‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
---
2+
doc_id: "DBS-COMPL-001"
3+
doc_title: "Database System - ISO/IEC 27001 Control Mapping"
4+
doc_version: "0.1.0"
5+
doc_date: "2026-04-19"
6+
doc_status: "Draft"
7+
project: "database_system"
8+
category: "COMPLIANCE"
9+
---
10+
11+
# ISO/IEC 27001 Control Mapping
12+
13+
> **Scope**: This document maps the current `database_system` codebase to a curated
14+
> subset of ISO/IEC 27001:2022 Annex A controls. It records the mechanism in code and
15+
> the exact source references, and it is intentionally conservative: controls that
16+
> depend on environment configuration, operator procedures, or components outside
17+
> this repository are marked as **Out of scope** or **Partial**.
18+
>
19+
> This is **not** a certification statement. It is evidence a reviewer or adopter can
20+
> cross-check against the source tree.
21+
22+
**Last updated**: 2026-04-19
23+
**Applies to**: `database_system` v1.0.0 and later, when built with `USE_OPENSSL=ON`
24+
(default since this release).
25+
26+
---
27+
28+
## Build-level Security Posture
29+
30+
| Setting | Default | Where | Effect |
31+
|---------|---------|-------|--------|
32+
| `USE_OPENSSL` CMake option | `ON` | `CMakeLists.txt` | Links OpenSSL, defines `DATABASE_HAS_OPENSSL`, enables PBKDF2-HMAC-SHA256 and AES-256-GCM in `secure_connection` |
33+
| `security_credentials::encryption` | `encryption_type::tls` | `database/security/secure_connection.h` | Default transport encryption type is TLS |
34+
| `security_credentials::verify_certificate` | `true` | `database/security/secure_connection.h` | Default rejects unverified server certificates |
35+
36+
Disabling `USE_OPENSSL` triggers a CMake `WARNING` and drops `secure_connection` to
37+
placeholder crypto — explicitly flagged as "NOT for production" in the source
38+
comment (`database/security/secure_connection.cpp`).
39+
40+
---
41+
42+
## A.5 — Organisational controls
43+
44+
### A.5.15 Access control
45+
46+
**Mechanism**: Role-Based Access Control (RBAC) via `access_control` class.
47+
- Roles with per-table allow/deny lists and per-operation permissions.
48+
- Session lifecycle (create, validate, terminate, expire).
49+
50+
**Source**: `database/security/secure_connection.h` (lines 193-254),
51+
`database/security/secure_connection.cpp`.
52+
53+
**Status**: Partial. The RBAC primitives are implemented and unit-tested, but
54+
enforcement at backend boundaries depends on the consuming application wiring
55+
`access_control::check_permission` into its query path.
56+
57+
### A.5.17 Authentication information
58+
59+
**Mechanism**: `credential_manager` stores credentials encrypted with the master
60+
key (AES-256-GCM when built with OpenSSL). Passwords are hashed via
61+
PBKDF2-HMAC-SHA256 (100,000 iterations) — see `secure_connection.cpp` fallback
62+
comment at line 211 (`Build with OpenSSL for PBKDF2-HMAC-SHA256 support.`).
63+
64+
**Source**: `credential_manager` in `database/security/secure_connection.h`
65+
(lines 99-127) and `.cpp`.
66+
67+
**Status**: Covered when `USE_OPENSSL=ON`. Without OpenSSL the fallback path is
68+
not suitable for production — documented in code and flagged at CMake time.
69+
70+
---
71+
72+
## A.8 — Technological controls
73+
74+
### A.8.2 Privileged access rights
75+
76+
**Mechanism**: Permission bitmask in `access_control::permission` distinguishes
77+
`admin` from data-plane permissions (`select`, `insert`, `update`,
78+
`delete_record`, `create`, `drop`, `alter`).
79+
80+
**Source**: `database/security/secure_connection.h` (lines 196-205).
81+
82+
**Status**: Partial (see A.5.15).
83+
84+
### A.8.3 Information access restriction
85+
86+
**Mechanism**: `access_control::check_table_access` and
87+
`query_security::validate_table_access` gate per-table access decisions.
88+
89+
**Source**: `database/security/secure_connection.h` (lines 171, 241).
90+
91+
**Status**: Partial. Enforcement is opt-in by the caller.
92+
93+
### A.8.5 Secure authentication
94+
95+
**Mechanism**: `authentication_method` enumerates `password`, `certificate`,
96+
`kerberos`, `oauth2`, `jwt`. Certificate-based and mutual-TLS are supported via
97+
`connection_security::perform_mutual_authentication` and
98+
`security_credentials::mutual_authentication`.
99+
100+
**Source**: `database/security/secure_connection.h` (lines 35-41, 64-66, 141).
101+
102+
**Status**: Covered (mechanism present); the actual auth provider is supplied
103+
by the consuming application or backend driver.
104+
105+
### A.8.15 Logging
106+
107+
**Mechanism**: `audit_logger` records database access, authentication events,
108+
and authorisation failures, with optional persistent file backing and a
109+
configurable retention window.
110+
111+
**Source**: `database/security/secure_connection.h` (lines 268-318),
112+
`database/security/secure_connection.cpp`.
113+
114+
**Status**: Covered for the events enumerated in `audit_logger`. Centralised
115+
log aggregation is out of scope for this repository.
116+
117+
### A.8.16 Monitoring activities
118+
119+
**Mechanism**: `security_monitor` performs brute-force detection, privilege-
120+
escalation monitoring, query-pattern analysis, and alert dispatch through a
121+
pluggable handler.
122+
123+
**Source**: `database/security/secure_connection.h` (lines 332-381).
124+
125+
**Status**: Covered at library level. Integration with a SIEM is the adopter's
126+
responsibility.
127+
128+
### A.8.20 Network security
129+
130+
**Mechanism**: TLS transport is the default encryption mode
131+
(`security_credentials::encryption = encryption_type::tls`).
132+
`connection_security::configure_tls` accepts CA bundle, client certificate, and
133+
client key; `set_cipher_suite` restricts allowed ciphers.
134+
135+
**Source**: `database/security/secure_connection.h` (lines 24-29, 55, 143-145).
136+
137+
**Status**: Covered. Cipher-suite selection and certificate management are the
138+
deployer's responsibility.
139+
140+
### A.8.21 Security of network services
141+
142+
**Mechanism**: `security_credentials::verify_certificate` defaults to `true`;
143+
`mutual_authentication` can be enabled to require a client certificate.
144+
145+
**Source**: `database/security/secure_connection.h` (lines 63-66).
146+
147+
**Status**: Covered (default-secure).
148+
149+
### A.8.23 Web filtering
150+
151+
**Status**: **Out of scope** — `database_system` is a database abstraction
152+
library and does not perform web filtering.
153+
154+
### A.8.24 Use of cryptography
155+
156+
**Mechanism**:
157+
- Password hashing: PBKDF2-HMAC-SHA256 with 100,000 iterations and a per-credential salt (OpenSSL `PKCS5_PBKDF2_HMAC`).
158+
- Symmetric encryption: AES-256-GCM (authenticated) for credential envelopes.
159+
- Random generation: OpenSSL `RAND_bytes` for salts and IVs.
160+
- Transport: TLS via the database driver (libpqxx, etc.) and/or `connection_security::configure_tls`.
161+
162+
**Source**: `database/security/secure_connection.cpp` (guarded by
163+
`DATABASE_HAS_OPENSSL`, lines 15-21 and the comments at 206-211, 278, 331).
164+
165+
**Status**: Covered when `USE_OPENSSL=ON` (default). Disabling OpenSSL reverts
166+
to placeholder crypto that is explicitly *not* A.8.24-compliant.
167+
168+
### A.8.25 Secure development lifecycle
169+
170+
**Mechanism**:
171+
- CI runs on Ubuntu (GCC/Clang), macOS, Windows (MSVC) with sanitizers
172+
(`asan`, `tsan`, `ubsan`), static analysis (`clang-tidy`, `cppcheck`), and
173+
coverage tracking.
174+
- CVE scan and SBOM generation are part of the pipeline (see
175+
`docs/contributing/CI_CD_GUIDE.md`).
176+
- Branch protection: `main` accepts only squash-merged PRs; CI must pass.
177+
178+
**Status**: Covered at process level. See `docs/contributing/CI_CD_GUIDE.md`
179+
and `.github/workflows/` for the concrete gates.
180+
181+
### A.8.26 Application security requirements
182+
183+
**Mechanism**: `query_security` provides SQL-injection detection,
184+
sanitisation, parameterisation helpers (`convert_to_prepared_statement`),
185+
and table-access validation.
186+
187+
**Source**: `database/security/secure_connection.h` (lines 160-179).
188+
189+
**Status**: Covered for the library-level surface. Application-level input
190+
validation is still required from the caller.
191+
192+
### A.8.28 Secure coding
193+
194+
**Mechanism**: All public synchronous APIs return `kcenon::common::Result<T>`
195+
(no exceptions across the public ABI); clang-tidy enforces snake_case and
196+
trailing-underscore conventions; RAII is used for all owned resources.
197+
198+
**Source**: `CLAUDE.md` "Key Patterns" section; header reviews in
199+
`database/core/` and `database/security/`.
200+
201+
**Status**: Covered at project policy level.
202+
203+
---
204+
205+
## A.5.30 / A.5.34 — Operational resilience & privacy
206+
207+
These controls depend heavily on deployment configuration (BCP, DPIA, data
208+
residency). They are tracked at the ecosystem level (`pacs_system`,
209+
`logger_system`) and are **Out of scope** for this repository in isolation.
210+
211+
---
212+
213+
## Controls explicitly out of scope
214+
215+
| Control | Reason |
216+
|---------|--------|
217+
| A.5.7 Threat intelligence | Handled by operator, not library |
218+
| A.6 People controls | Organisational, not code |
219+
| A.7 Physical controls | Organisational, not code |
220+
| A.8.6 Capacity management | Deployment concern |
221+
| A.8.9 Configuration management | Deployment/IaC concern |
222+
| A.8.22 Segregation of networks | Deployment/network concern |
223+
224+
---
225+
226+
## Change log for this document
227+
228+
| Date | Version | Change |
229+
|------|---------|--------|
230+
| 2026-04-19 | 0.1.0 | Initial mapping, issue #569. |
231+
232+
---
233+
234+
## See also
235+
236+
- [SECURITY.md](../../SECURITY.md) — vulnerability reporting
237+
- [FEATURES_POOLING_SECURITY.md](../FEATURES_POOLING_SECURITY.md) — security feature reference
238+
- [PRODUCTION_QUALITY.md](../PRODUCTION_QUALITY.md) — production-readiness posture

0 commit comments

Comments
 (0)