Security Model¶
The mConfig modules function as a library, running within the application’s context and process environment.
mConfig operates with the application's inherent access rights and does not attempt to "guard" secrets from the application itself. Instead, it delegates the primary security boundary to the underlying execution environment (e.g., OS, Kubernetes, or Cloud IAM roles), maintaining the same level of security as the host process.
What mConfig protects against, and what not¶
mConfig prevents accidental disclosure of secret values: in logs, toString(), tool output,
exports and diagnostic dumps (see Where secret values may appear).
mConfig does not protect secrets in process memory. Whoever can read the memory of the process - a heap dump, a debugger, an agent attached to the JVM, other code running in the same process, the operating-system user the process runs as - can read the secrets the application has loaded. Erasing (see Memory wiping) shortens the time a value is held, which limits what a later heap dump contains; it is no protection against an attacker with access to the running process. Protecting secrets from the process itself takes handles instead of values, such as keys kept in an HSM or a KMS.
Secrets¶
Bridging Modern and Legacy security¶
Ideally, an application never handles raw secrets, but operates via handles only. This is the model of the JCE (Java Cryptography Extension) and of Hardware Security Modules (HSMs): keys stay in a hardware enclave and are used in a controlled manner, without ever entering application memory. Many common tasks, however - sending a bearer token to an API, a password to a database driver - require the actual secret value.
mConfig acts as bridge for both:
- High Security: Manage IDs and handles for HSM/KMS providers.
- Practical Utility: fetch and provide plaintext tokens or passwords for legacy interfaces, with the exposure limited as described below.
mConfig Secrets Handling¶
mConfig secrets are treated differently than standard configuration to reduce their exposure footprint:
- Masking: secret values are replaced by
[REDACTED]in logs,toString()and tool output. - Transport: the network sources use TLS. The Vault and Kubernetes modules send the Kubernetes
ServiceAccount token only to an
httpsaddress, unless insecure transport is explicitly allowed for development. The Kubernetes modules switch certificate checks off only with a separate opt-in that can be set in code only, for tests. Other credentials, such as a static Vault token, go to the address you configure: configure anhttpsaddress. - Memory: secret values are handed out as
SecretValue, a mutable byte buffer that the application can wipe witherase(), instead of an immutableString. - Late-bound decryption: in the configuration, a secret is a reference. It is resolved -
fetched, and decrypted where its source keeps it encrypted - only when the application requests
the value (
getSecret()), and the visible bytes can be erased right after use. Status: this is the model the secrets handling is built for. The storages shipped today still fetch their secrets when the configuration is built; fetching on request (lazy fetch) is scheduled for 0.9.1.
Strings are immutable and stay on the heap until garbage collected, so a password kept as a
String cannot be wiped. A SecretValue can. This works only as far as the value was never a
String along the way: values read from text formats (.properties, JSON, YAML, …) pass through
the format parser as Strings, and environment variables are Strings in the JVM from the start.
The buffer reduces the exposure; it does not remove it.
Dynamic Updates¶
Vault and AWS Secrets Manager are polled for changes (pollInterval; default 60 s for Vault, 5 min
for AWS, where API calls have costs; 0 disables polling). The Kubernetes module watches the
ConfigMaps and Secrets it reads. Changed values replace the old ones without a process restart, so
rotated credentials are picked up.
Memory wiping¶
When a Configuration is closed via close(), mConfig calls erase() on its configuration
layers. The in-memory and default layers and the environment-variable, Vault, AWS Secrets Manager
and Kubernetes storages wipe the secret buffers they hold. Layers read from files do not wipe
yet; complete wipe-on-close is planned for 0.9.1.
With the storages shipped with mConfig, each getSecret() returns a new copy, so wiping it with
erase() after use affects only the application's copy, never the stored value. A third-party
secrets provider (see Where secrets come from)
should do the same.
Secret and Sensitive¶
mConfig distinguishes two kinds of confidentiality. They are related, but they are protected for different reasons and therefore handled differently.
- SECRET — cryptographic secrets and credentials: private keys, symmetric keys, API tokens, passwords, license IDs. If one leaks, a system is compromised.
- SENSITIVE — information that must not become visible where it does not belong, typically personal data under GDPR and comparable regimes: names, e-mail addresses, postal addresses, user IDs, IP addresses. If one leaks, a person is harmed and a reporting obligation may follow.
The two overlap: most SECRET entries are also SENSITIVE, but far from every SENSITIVE entry is SECRET. A per-user API token is both a credential and personal data. A customer's e-mail address is personal data and no credential at all. The two markers are therefore independent, not a severity scale — an entry may carry either, both, or neither, and when both are set the protections add up.
The distinction in one sentence¶
SECRET minimises exposure in time. SENSITIVE minimises exposure in scope.
A credential is dangerous for as long as it exists in readable form, so mConfig wraps it, keeps it out of the JVM String pool, and wipes it once it is no longer needed. Personal data is not made safe by wiping it — the application legitimately needs it for its normal working life — but it must not spread into logs, exports, diagnostic dumps, or documentation.
This is why SENSITIVE deliberately does not use the SecretValue machinery. Forcing personal
data through a wipeable byte buffer would be counterproductive: the application would convert it
straight back into a String to use it, and nothing would be gained.
Confidentiality never hides the location¶
What gets suppressed is the value. Where the value is stored always remains traceable.
mConfig can tell you, for any entry, which scope and which concrete location it came from —
getScope(), getLocation() and getURI() on a ConfigEntry answer this regardless of whether
the entry is SECRET, SENSITIVE, or neither. That property is deliberate and is kept intact by
every confidentiality mechanism in the library.
This matters most precisely for the data that is most protected:
- Data subjects can exercise their rights. Finding, correcting, and erasing personal data (GDPR Art. 15-17) is only possible if one can determine where the data is held. A redaction that also hid the storage location would obstruct the very obligations SENSITIVE exists to serve.
- Owners keep authority over their data. If a value comes from "somewhere" and its origin cannot be determined, part of the ownership over it is lost.
- Credentials can be rotated and revoked. Knowing which store holds a secret is a precondition for replacing or removing it.
So a redacted log line or diagnostic dump still names the key, the scope, and the storage location of a protected entry — it withholds only the value itself. Location traceability across a ten-tier hierarchy of heterogeneous sources is a distinguishing property of mConfig, and confidentiality markers do not trade it away.
Where secret values may appear¶
Secrets are often stored in plain text on purpose: in a configuration file readable only by the service account, in the registry, in a Kubernetes Secret. Their protection is the access control of that storage — file permissions, ACLs, the login to a network service. mConfig respects this and draws one line:
- The storage the value came from is the value's home. When a secret is replaced with a new value in the same scope, mConfig writes the new value to the same location, if that location is writeable, and replaces it there. The other secrets stored there stay as they are.
- Every other context is outside that access control. A newly created file
(
ConfigMapper.saveTo()), console output, logs, diagnostic dumps, event messages: whoever reads these was not necessarily allowed to read the original storage. Secret values do not go there.
In practice:
| Path | Secret value |
|---|---|
writing back to the source location (put(), mconfig set) |
kept intact; this is its home |
ConfigMapper.saveTo() to a new file |
left out; the omitted keys are reported as a WARNING config event (EXPORT_SECRETS_OMITTED) |
CLI output (get, show, monitor, validate, set echo), all formats |
replaced by the marker [REDACTED] |
toString(), logs |
replaced by the marker [REDACTED] |
| parse error reports (log line, PARSE event) | the parser's quote of the content is left out where it may be a secret; see Parse errors |
mconfig get <key> --reveal |
shown: an explicit request for one value |
getSecret(), typed getters, ConfigUtil.copy…ToJavaProperties() |
returned to the application: an in-process request |
Key, scope and location stay visible in all of these.
A string marker, in every output format. A redacted value is shown as the string
[REDACTED] — in text, CSV, JSON, YAML and TOML alike — and never as null or by omitting the key
from tool output. A null reads as "not set", which is wrong exactly when someone is checking
whether a secret is configured; and if such output is ever re-used as a configuration file, a
null silently falls back to a lower-priority value, while a marker fails visibly. TOML has no
null anyway. The JSON, YAML and TOML output of mconfig get additionally carries
"secret": true.
Explicit reveal for a single value. Seeing a secret in plain text takes an explicit request for
exactly that value: mconfig get <key> --reveal. Listing and monitoring commands have no such
option. Whoever can read the source may see the value; the tool does not add a second gate, but it
does not hand out values unasked either.
Files written by saveTo() leave secrets out rather than writing a marker: a marker written
into a configuration file would become the value when the file is read back. To copy a
configuration including its secrets, copy the original storage under its own access control.
This follows established practice: summary views redact with a string marker and keep the key
(Spring Boot Actuator shows ******, Terraform <sensitive>, CI logs ***, kubectl describe
secret only byte counts), while plain text is given out only on an explicit request for the value,
guarded by the access control of the source (kubectl get secret, the Vault and AWS command line
tools). Consistent behaviour with these tools is intended: no surprises for operators who know them.
Parse errors¶
When content cannot be parsed, no value has been read yet, so there is nothing to redact - but the
parser's own message often quotes the content it failed on, e.g. Unrecognized token 's3cr3t' or
the YAML line with a ^ marker below it. Since 0.8.17 mConfig always reports configuration,
location, format, error type, line, column and the key at the error position (if the parser can tell
it), and adds the parser's message only where the content cannot be a secret value.
The message is left out in these cases:
| Case | Why the content may be secret | Schema needed? |
|---|---|---|
the schema marks the entry at the error position SECRET |
declared secret | yes |
the schema marks an entry above or below the error position SECRET (e.g. error in db, secret db/password) |
the broken structure may contain the secret | yes |
the parser cannot tell the position (SnakeYAML; errors before the first key), and the schema has any SECRET entry |
the error may be anywhere, the secret included | yes |
| the content comes from a Kubernetes Secret | secret by its source | no |
the configuration is a bootstrap configuration of a cloud module (vault, aws, zookeeper, kubernetes: read through getRestrictedConfig()) |
holds credentials such as a Vault token, typically without a schema | no |
In all other cases - no schema, or a schema without SECRET entries near the error - the parser's
message is shown, escaped like all outside text. A secret in a file whose schema does not mark it
SECRET is not recognised; mark it.
Reading from a secret store can fail outside the format parsers too, e.g. when a client library cannot handle a response, and its message may then quote the response. Such failures are reported without the message:
- Vault: error type, plus the HTTP status where the client knows it.
- Kubernetes Secrets: error type only. An HTTP error answer of the API server (e.g. 403) is reported with its status and the server's error text, which describes the request, not the Secret.
- AWS Secrets Manager: with the AWS SDK's message, which carries the service's error text, not the secret; a secret that is not a flat JSON object falls back to the raw value without a report.
LOG_PARSE_ERROR_DETAILS, set in code, adds the parser's message in every
case. It is meant for development: with it, a broken line holding a secret value goes into the log.
Comparison¶
| Aspect | SECRET | SENSITIVE |
|---|---|---|
| Reason for protection | security: compromise of a system | privacy: harm to a person, regulatory obligation |
| Typical content | keys, tokens, passwords, license IDs | names, e-mail and postal addresses, user IDs, IP addresses |
| Value representation | changed: SecretValue, avoids String |
unchanged: ordinary typed value |
| Access | getSecret(), then erase() after use |
ordinary getString() and other typed getters |
| Lifetime in memory | as short as possible | the application's normal working lifetime |
Logs and toString() |
redacted | redacted |
| Export, diagnostics, dumps | value never in plain text | value suppressed |
| Storage location | always traceable | always traceable |
| Rotation | meaningful; sources may rotate credentials | not a meaningful concept |
| Erasure request | not applicable | applicable (e.g. GDPR Art. 17) |
| Primary audience | security / threat model | data protection officer, legal, data inventory |
Where the marking comes from¶
A SECRET marking has two possible origins:
- the configuration schema, via
"SECRET": true, and - the configuration source itself — Vault, AWS Secrets Manager and the Kubernetes modules deliver entries that are secret by their nature, with no schema involved.
A SENSITIVE marking currently has one origin: the configuration schema. No storage backend carries a notion of personal data today.
Storage suitability¶
Not every storage place is a fit for every kind of information. A storage module may decline to hold SECRET data, and may equally decline to hold SENSITIVE data, on the grounds that this storage place is not safe for the type of information being handled.
The rule for secrets: a secret is only ever written to a location that is acceptable for secrets, and never moved to a place less protected than its home. If no acceptable location exists, the write is refused rather than moved further.
The mechanism is the normal write path. A write stays in the scope it was made for and goes through that scope's locations in priority order. A storage declines a location by not offering a writeable layer there, or by not creating one; the write then moves on to the next location of the scope. A storage can also refuse a single entry when it is written - the entry tells whether it is secret. Such a refusal currently ends the write with an error instead of moving on, which is the safe behaviour under the rule above.
The storages shipped today do not decline secrets: they treat a secret like any other value of the location, protected by the location's own access control.
Suitability is decided per storage type. Finer granularity — different handling for different sub-paths within one storage, such as branches of the Windows registry — is a possible later refinement and is not part of the model today.
Implementation status¶
Be aware of what is in place and what is not:
| Marker | Status |
|---|---|
SECRET |
implemented, via the schema field "SECRET": true and via secret-aware sources |
SENSITIVE |
defined but not yet enforced: it can be described here and reasoned about, but marking an entry does not yet cause redaction or export suppression |
Do not rely on SENSITIVE for compliance until it is enforced. Until then, an entry whose
disclosure would be damaging should be marked SECRET, accepting the stricter handling.
Next Steps¶
For practical examples on how to use secrets in your application, see Handling Secrets. For the schema fields that carry these markings, see Configuration Schemas.