# How Maven's Encryption (mvnenc) Works for Passwords: A Technical Deep Dive

> Explore how Maven's mvnenc encrypts passwords using AES-256-CBC. Learn about master keys, settings-security.xml, and transparent decryption for secure password management.

- Repository: [The Apache Software Foundation/maven](https://github.com/apache/maven)
- Tags: deep-dive
- Published: 2026-07-05

---

**Maven's `mvnenc` command-line tool encrypts passwords using AES-256-CBC with PKCS5Padding, storing a master key in [`settings-security.xml`](https://github.com/apache/maven/blob/main/settings-security.xml) and wrapping encrypted values in `{ENC}` tokens that `DefaultSettingsDecrypter` or Maven 4's `SecDispatcher` transparently decrypt at runtime.**

The `mvnenc` utility is Apache Maven's dedicated workstation-level password management solution, replacing the legacy *settings-security.xml* handling tied to Maven 3's `SecDispatcher`. According to the apache/maven source code, this tool operates as a specialized CLI invoker that validates goals and delegates cryptographic operations to specific goal implementations under `org.apache.maven.cling.invoker.mvnenc`.

## The Encryption Architecture and Entry Points

### The EncryptInvoker Entry Point

The `mvnenc` command resolves to `EncryptInvoker` at `org.apache.maven.cling.invoker.mvnenc.EncryptInvoker`. Its `execute()` method validates that exactly one goal is supplied (either `init`, `encrypt`, `decrypt`, or `diag`), then forwards the request to the corresponding `Goal` implementation.

```java
// From EncryptInvoker.java
public int execute(InvokerRequest request) throws Exception {
    // Validates single goal and dispatches to Init, Encrypt, Decrypt, or Diag
}

```

Exit codes are defined as constants in this class: `OK`, `ERROR`, `BAD_OPERATION`, and `CANCELED`.

### Command Parsing and Context Creation

Before cryptographic operations begin, `EncryptParser` parses the CLI into an `EncryptOptions` object. This value object holds:
- The selected goal
- Optional master-password file paths
- Flags like `--show-errors`

The `EncryptContext` class then bundles the `InvokerRequest`, parsed options, a JLine `Terminal`, and a `LineReader` for handling interactive password prompts without echoing to the console.

## The Four Core Goals: init, encrypt, decrypt, and diag

### Init: Generating the Master Encryption Key

The `Init` goal (`org.apache.maven.cling.invoker.mvnenc.goals.Init`) creates a random 256-bit AES key that serves as the master password for the workstation. This key is base64-encoded and written to `$HOME/.m2/.mvn/settings-security.xml` inside a `<master>{…}</master>` element.

This file is created once per workstation and is required before any password encryption can occur.

### Encrypt: Securing Passwords with AES-CBC

The `Encrypt` goal (`org.apache.maven.cling.invoker.mvnenc.goals.Encrypt`) handles the actual password protection:

1. **Input Collection**: Uses `ConsolePasswordPrompt` (JLine-based) to securely read clear-text passwords without terminal echo
2. **Cryptographic Processing**: Encrypts bytes using **AES-CBC/PKCS5Padding** with the master key
3. **Output Formatting**: Base64-encodes the ciphertext and wraps it in the `{ENC}` prefix

The resulting string (e.g., `{ENC}k3J9vE7c2Zp0+...`) can be safely stored in [`settings.xml`](https://github.com/apache/maven/blob/main/settings.xml) or other configuration files.

### Decrypt: Restoring Clear-Text Passwords

The `Decrypt` goal reverses the encryption process. It extracts the base64 payload from an `{ENC}` string, decrypts it using the same master key stored in [`settings-security.xml`](https://github.com/apache/maven/blob/main/settings-security.xml), and prints the original clear-text password to stdout.

### Diag: Runtime Diagnostics

The `Diag` goal displays which security implementation is active. It detects whether Maven 4's `SecDispatcher` is available or if the system will fall back to Maven 3's compatibility layer.

## Cryptographic Implementation and Fallback Strategy

The actual encryption/decryption logic delegates to Maven's **Settings security** component. When Maven 4's `SecDispatcher` is present, `mvnenc` uses it directly as the preferred path. If the dispatcher is unavailable (e.g., on older Java runtimes), the tool falls back to `org.apache.maven.settings.crypto.DefaultSettingsDecrypter`.

This fallback mechanism ensures backward compatibility while allowing Maven 4 to use modern security implementations. The diagnostic output from `mvnenc diag` indicates which path is active.

## Practical Workflow Examples

Initialize the master password store (run once per workstation):

```bash
mvnenc init

# Creates $HOME/.m2/.mvn/settings-security.xml

```

Encrypt a password interactively:

```bash
mvnenc encrypt
Password: ********

# Output: {ENC}k3J9vE7c2Zp0+...

```

Encrypt non-interactively for scripts:

```bash
echo "mySecret" | mvnenc encrypt -q
{ENC}k3J9vE7c2Zp0+...

```

Decrypt an existing value:

```bash
mvnenc decrypt -p "{ENC}k3J9vE7c2Zp0+..."
mySecret

```

Check which implementation is available:

```bash
mvnenc diag
Maven Encryption is configured.
Using Maven 4 SecDispatcher.

```

## Summary

- **`mvnenc`** is the dedicated CLI tool for Maven password management, replacing legacy Maven 3 security handling
- **Master key storage**: 256-bit AES key stored at `$HOME/.m2/.mvn/settings-security.xml`
- **Encryption algorithm**: AES-CBC with PKCS5Padding, base64-encoded and wrapped in `{ENC}` tokens
- **Core classes**: `EncryptInvoker`, `EncryptParser`, `EncryptContext`, and goal implementations (`Init`, `Encrypt`, `Decrypt`, `Diag`)
- **Fallback support**: Automatically uses `DefaultSettingsDecrypter` when Maven 4's `SecDispatcher` is unavailable
- **Security**: Password input uses JLine `ConsolePasswordPrompt` to prevent terminal echo

## Frequently Asked Questions

### Where does mvnenc store the master password?

The master password is stored in `$HOME/.m2/.mvn/settings-security.xml` as a base64-encoded 256-bit AES key inside a `<master>` element. This file should be protected with filesystem permissions and never committed to version control.

### What encryption algorithm does Maven use for password encryption?

Maven uses **AES-256-CBC with PKCS5Padding** (`AES/CBC/PKCS5Padding`). The ciphertext is base64-encoded and prefixed with `{ENC}` so that Maven's settings decrypter can automatically recognize and decrypt it during the build process.

### How does Maven 4 password encryption differ from Maven 3?

Maven 4 introduces the `SecDispatcher` API, which `mvnenc` prefers over the legacy `DefaultSettingsDecrypter` found in Maven 3. If the Maven 4 dispatcher is unavailable, the tool automatically falls back to the Maven 3 compatibility layer without user intervention.

### Can mvnenc encrypt passwords without interactive prompting?

Yes. You can pipe the password to `mvnenc encrypt` using standard input redirection: `echo "password" | mvnenc encrypt -q`. The `-q` (quiet) flag suppresses interactive prompts, making the tool suitable for CI/CD pipelines and automation scripts.