skip to content

Credential Encryption

2 roadmaps5 questions

Encrypting repository passwords against a master password in settings-security.xml and referencing the {encrypted} values from <server> entries. Comes up in any conversation about keeping credentials out of version control.

on this pageshow

explore

questions

5

Where does Maven store repository credentials, and what is the basic mechanism for keeping them out of plain text?

level: juniorimportance: must knowfreq 55%

answer

  1. ~/.m2/settings.xml <server>
  2. id must match repo id
  3. {encrypted} token
  4. master in settings-security.xml
  5. obfuscation not vault

basics

~20 s

Credentials go in ~/.m2/settings.xml inside a <server> entry (id, username, password). Maven can encrypt the password so settings.xml holds an {encrypted} value instead of the real one, decrypted at build time using a master password.

solid answer

~40 s

Maven reads server credentials from a <server> block in ~/.m2/settings.xml (the user-level settings), matched to a repository by a shared id. By default the password is plain text, which is risky if the file is shared or backed up. Maven's built-in password encryption lets you replace it with an {base64ciphertext} token. That ciphertext is decrypted using a separate master password held in ~/.m2/settings-security.xml. At build time Maven combines the two to recover the real password for HTTP(S) auth to the remote repository. Note this is obfuscation, not strong protection: the master file sits on the same machine. The point is to avoid copy-pasteable plaintext, not to defeat a determined local attacker.

code

xml · 9 lines
xml
<settings>
  <servers>
    <server>
      <id>nexus-releases</id>
      <username>deploy-bot</username>
      <password>{COQLCE6Du7v...}</password>
    </server>
  </servers>
</settings>

go deeper

for a junior

Knows credentials go in ~/.m2/settings.xml under <server> and can be encrypted.

for a middle

Knows the id-matching rule and the two-file (settings.xml + settings-security.xml) split.

for a senior

Frames it as obfuscation vs real secret management and avoids committing secrets.

for a principal

Drives org policy: vault/CI-injected secrets, no plaintext in repos, machine-scoped master files.

## What problem this solves When Maven downloads from a private repository (e.g. Nexus, Artifactory) or deploys artifacts, it needs a username and password. Those must live somewhere on the developer/CI machine. Storing them as plain text in a config file is dangerous because settings.xml is easy to share, commit, or back up by accident. ## Where credentials live Maven looks in **`~/.m2/settings.xml`** (the per-user settings file; there is also a global one in `$MAVEN_HOME/conf/settings.xml`). Credentials go in a `<server>` element under `<servers>`: - `<id>` — must exactly match the `<id>` of the `<repository>` / `<distributionManagement>` / `<mirror>` it authenticates. - `<username>` and `<password>`. ## The two-file encryption model Maven supports encrypting the password so the stored value is not readable: - **`~/.m2/settings-security.xml`** holds the **master password** (itself encrypted with a fixed internal key, or optionally tied to a relocated file). - **`~/.m2/settings.xml`** holds the **server password as ciphertext** wrapped in curly braces, e.g. `{COQLCE6...}`. At build time Maven decrypts the master password from settings-security.xml, uses it to decrypt the server password, and authenticates. ## Important caveat This is **obfuscation**, not real secret management. Both files sit on the same machine, so anyone with local read access can recover the password. It stops shoulder-surfing and accidental plaintext leaks; it does not replace a vault. ```xml <settings> <servers> <server> <id>nexus-releases</id> <username>deploy-bot</username> <password>{COQLCE6Du7v...}</password> </server> </servers> </settings> ```

  • Why must the <server> id match the repository id?
    Maven matches credentials to a remote by id; if they differ, Maven sends no auth and you get a 401/403.
  • Is encrypted settings.xml safe to commit to a shared repo?
    No. It is local obfuscation only; the master file on the same box can decrypt it. Use a real secret store or per-machine files.

saying these in an interview costs you the question

  • Thinking encryption makes the password cryptographically safe to publish
  • Putting credentials in the project pom.xml instead of settings.xml
  • Assuming the id is free-form and doesn't need to match the repository id

context

resolving links…

open as a page

Walk through the exact CLI steps to set up Maven password encryption from scratch.

level: middleimportance: must knowfreq 50%

basics

~10 s

First run mvn --encrypt-master-password to create the master, paste its output into ~/.m2/settings-security.xml. Then run mvn --encrypt-password for each server password and paste the {token} into the <server><password> in settings.xml.

open as a page

What is the difference between the master password and a server password, and how do they relate cryptographically?

level: middleimportance: should knowfreq 35%

basics

~10 s

The master password is the single key, stored encrypted in settings-security.xml. Server passwords are the actual repo secrets in settings.xml, each encrypted using the master. The master decrypts every server password.

open as a page

How should repository credentials be handled in CI, and where does Maven's built-in encryption fall short?

level: seniorimportance: should knowfreq 40%

basics

~20 s

In CI, inject secrets from the platform's secret store into environment variables and reference them from settings.xml, instead of relying on Maven's file-based encryption, which is only local obfuscation and awkward to manage on ephemeral runners.

open as a page

A deploy fails with 401 Unauthorized even though credentials are encrypted in settings.xml. How do you diagnose it?

level: seniorimportance: should knowfreq 30%

basics

~20 s

Check that the <server> id exactly matches the repository id, that settings-security.xml exists and contains the master, that the encrypted token wasn't corrupted by shell quoting, and that the password itself is still valid on the server.

open as a page