Jasypt Encryption with Spring Boot: Secure Your Properties Like a Pro

Every Spring Boot application I've worked on in the last decade has one thing in common: somewhere, somehow, a plaintext password ends up in a properties file. I've seen it happen at startups and Fortune 500s alike. It's the kind of shortcut that works until it doesn't — until a config file gets accidentally committed to a public repo, or a disgruntled employee walks out with a dump of production secrets. That's where Jasypt (Java Simplified Encryption) comes in. It's a battle-tested library that lets you encrypt sensitive properties in your application.yml or application.properties, and decrypt them at runtime using a master password. With Spring Boot 3.x and Jasypt 3.0.5, you can annotate your configuration class with @EnableEncryptableProperties and keep your secrets encrypted at rest. The master password itself should never live in your codebase — inject it via environment variables, a secrets vault, or a startup argument. In this tutorial, I'll walk you through setting up Jasypt step by step, share a real production incident where encrypted properties saved our bacon, and point out the common mistakes I've seen developers make. By the end, you'll have a secure, production-ready configuration that won't leak secrets even if your repo goes public.

1. Setting Up Jasypt with Spring Boot 3.x

Let's get our hands dirty. First, add the Jasypt Spring Boot starter to your pom.xml. I'm using version 3.0.5 which is the latest stable release compatible with Spring Boot 3.x. If you're on Gradle, the artifact is the same. The key dependency is com.github.ulisesbocchio:jasypt-spring-boot-starter:3.0.5. This starter automatically registers a custom property source that intercepts encrypted values wrapped in ENC(...) and decrypts them using the configured master password. You don't need any extra configuration beans — just add the dependency and set jasypt.encryptor.password in your application.properties or as an environment variable. I strongly recommend using an environment variable like JASYPT_ENCRYPTOR_PASSWORD rather than hardcoding it. In production, we inject this via Kubernetes secrets or AWS Secrets Manager. Don't forget to also set the algorithm — the default is weak. Use jasypt.encryptor.algorithm=PBEWithHMACSHA512AndAES_256 for proper security. Also set jasypt.encryptor.iv-generator-classname=org.jasypt.iv.RandomIvGenerator to ensure each encryption produces a different ciphertext.

<dependency>
    <groupId>com.github.ulisesbocchio</groupId>
    <artifactId>jasypt-spring-boot-starter</artifactId>
    <version>3.0.5</version>
</dependency>

<!-- In application.properties -->
jasypt.encryptor.password=${JASYPT_ENCRYPTOR_PASSWORD}
jasypt.encryptor.algorithm=PBEWithHMACSHA512AndAES_256
jasypt.encryptor.iv-generator-classname=org.jasypt.iv.RandomIvGenerator
jasypt.encryptor.key-obtention-iterations=1000

2. What the Official Docs Won't Tell You

The official Jasypt documentation is decent for basic setup, but it glosses over some critical gotchas. First, the default encryption algorithm is weak — PBEWithMD5AndDES. The docs mention you can change it, but they don't scream that using the default is a security risk. Second, if you set jasypt.encryptor.password in application.properties, it's visible in plaintext in your config file. That defeats the purpose. The docs should emphasize using environment variables or system properties. Third, the Jasypt CLI tool (jasypt-1.9.3-dist.zip) has a bug where it uses a different iteration count than the Spring Boot starter by default. If you encrypt with the CLI using default settings, the Spring Boot app won't decrypt it. You must explicitly pass -iterations=1000 on the CLI to match the starter's default. Fourth, there's no built-in mechanism for key rotation. If you change the master password, all encrypted values become undecryptable. You need to re-encrypt everything. Fifth, the @EnableEncryptableProperties annotation is required only if you're not using the starter — the starter auto-configures it. Many developers add it unnecessarily and wonder why it still works without it.

# Encrypt a value with matching parameters (critical!)
java -cp jasypt-1.9.3.jar org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI \
  input="mydbpassword" \
  password="myMasterKey" \
  algorithm=PBEWithHMACSHA512AndAES_256 \
  iterations=1000 \
  ivGeneratorClassName=org.jasypt.iv.RandomIvGenerator

# Output: ENC(encryptedBase64StringHere)

3. Encrypting Properties with Jasypt CLI and Java API

You have two main ways to encrypt values: the Jasypt CLI tool or programmatically via the Java API. For one-off encryption (like setting up a new environment), the CLI is fine. But for automated pipelines, use the Java API. Let's look at both. First, download jasypt-1.9.3-dist.zip from the official site. Unzip it and use the CLI as shown. The encrypted output will be wrapped in ENC(...). Paste that into your application.properties. For the Java API, add the jasypt core dependency (not the starter) to your build. Then create a simple encryptor using StandardPBEStringEncryptor. Set the same algorithm, password, iteration count, and IV generator. Call encrypt() on your plaintext. This approach is ideal for a CI/CD pipeline where you want to encrypt secrets at build time. I've used this in Jenkins pipelines where the master password is passed as a build secret. One gotcha: the encrypted string is Base64-encoded and can be quite long. Make sure your properties file format supports multi-line values if needed. Also, be aware that encrypting the same plaintext twice with the same password produces different ciphertexts (thanks to the random IV). That's a feature, not a bug.

import org.jasypt.encryption.pbe.StandardPBEStringEncryptor;
import org.jasypt.iv.RandomIvGenerator;

public class JasyptEncryptor {
    public static void main(String[] args) {
        StandardPBEStringEncryptor encryptor = new StandardPBEStringEncryptor();
        encryptor.setPassword(System.getenv("JASYPT_ENCRYPTOR_PASSWORD"));
        encryptor.setAlgorithm("PBEWithHMACSHA512AndAES_256");
        encryptor.setIvGenerator(new RandomIvGenerator());
        encryptor.setKeyObtentionIterations(1000);
        
        String plaintext = "mydbpassword";
        String encrypted = encryptor.encrypt(plaintext);
        System.out.println("ENC(" + encrypted + ")");
    }
}

4. Configuring Spring Boot to Decrypt at Runtime

Once you have encrypted properties, Spring Boot needs to decrypt them when the application starts. The Jasypt starter does this automatically by registering a custom PropertySource that intercepts values matching the ENC(...) pattern. But you need to ensure the master password is available at startup. The best practice is to set it as an environment variable or system property. In your application.properties, you reference it as ${JASYPT_ENCRYPTOR_PASSWORD}. Never put the actual password there. The decryption happens during the application context initialization phase, before your beans are created. This means if the master password is wrong, the application will fail to start with a DecryptionException. That's good — you want fast failure. However, if you have optional properties that might be encrypted or not, you need to handle that carefully. The starter also supports multiple encryptors via a custom bean. For example, you might have different master passwords for different environments. You can define multiple StringEncryptor beans and reference them in your properties using jasypt.encryptor.bean=myEncryptor. This is advanced usage but useful for multi-tenant apps.

# application.properties
jasypt.encryptor.password=${JASYPT_ENCRYPTOR_PASSWORD}
jasypt.encryptor.algorithm=PBEWithHMACSHA512AndAES_256
jasypt.encryptor.iv-generator-classname=org.jasypt.iv.RandomIvGenerator
jasypt.encryptor.key-obtention-iterations=1000

# Encrypted properties
db.password=ENC(9aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abcdefghijklmnop)
api.key=ENC(xYz1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOP)

5. Testing Encrypted Properties in Integration Tests

Testing encrypted properties is tricky because your test environment needs access to the master password. The naive approach is to hardcode a test password in application-test.properties. That works but it's not secure if the test config gets committed. A better approach: use a dedicated test master password that's different from production. Store it in a test environment variable or in a local .env file that's gitignored. In your test configuration, you can also use @TestPropertySource to set the master password inline. But be careful — if you do that, the password is visible in your test code. For integration tests that need to verify decryption works, I recommend using Spring Boot's testing support with @SpringBootTest and setting jasypt.encryptor.password in the test properties. You can also write a unit test that directly tests the decryption logic using StandardPBEStringEncryptor. This isolates the encryption logic from the Spring context. Another common scenario: testing that your application handles decryption failure gracefully. For example, if the master password is wrong, you want a meaningful error message, not a cryptic stack trace. Write a test that sets an invalid password and asserts that the application context fails to load with a specific exception.

@SpringBootTest
@ActiveProfiles("test")
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
class JasyptIntegrationTest {

    @Value("${db.password}")
    private String dbPassword;

    @Test
    void testDecryptedProperty() {
        assertEquals("testdbpassword", dbPassword);
    }

    @Test
    void testDecryptionFailure() {
        // Simulate wrong password by setting system property
        System.setProperty("jasypt.encryptor.password", "wrongpassword");
        assertThrows(DecryptionException.class, () -> {
            // Trigger context refresh
        });
    }
}

6. Advanced Configuration: Multiple Encryptors and Custom Resolvers

Sometimes you need different encryption keys for different properties. For example, database credentials might use one master password, while API keys for a third-party service use another. Jasypt supports this via multiple StringEncryptor beans. You define each encryptor with a unique bean name, then in your properties file, you specify which encryptor to use with the jasypt.encryptor.bean property. But you can also use a custom prefix/suffix instead of the default ENC(...). This is useful if you have legacy systems that use different delimiters. To do this, implement EncryptablePropertyDetector and EncryptablePropertyResolver interfaces. The detector tells Jasypt whether a property value is encrypted (e.g., starts with 'ENC('). The resolver extracts the encrypted value and delegates to the encryptor. I've used this pattern to support both Jasypt-encrypted values and values encrypted by a legacy system using a different format. Another advanced feature is using Jasypt with Spring Cloud Config. If you're using a config server, you can encrypt values at rest in the Git repository and decrypt them in the client application. This adds a layer of security for distributed systems.

@Configuration
public class MultipleEncryptorsConfig {

    @Bean("dbEncryptor")
    public StringEncryptor dbEncryptor() {
        StandardPBEStringEncryptor encryptor = new StandardPBEStringEncryptor();
        encryptor.setPassword(System.getenv("DB_ENCRYPTOR_PASSWORD"));
        encryptor.setAlgorithm("PBEWithHMACSHA512AndAES_256");
        encryptor.setIvGenerator(new RandomIvGenerator());
        encryptor.setKeyObtentionIterations(1000);
        return encryptor;
    }

    @Bean("apiEncryptor")
    public StringEncryptor apiEncryptor() {
        StandardPBEStringEncryptor encryptor = new StandardPBEStringEncryptor();
        encryptor.setPassword(System.getenv("API_ENCRYPTOR_PASSWORD"));
        encryptor.setAlgorithm("PBEWithHMACSHA512AndAES_256");
        encryptor.setIvGenerator(new RandomIvGenerator());
        encryptor.setKeyObtentionIterations(1000);
        return encryptor;
    }
}

7. Performance Considerations and Caching

Decryption is not free. Each time Spring Boot resolves a property that's encrypted, Jasypt performs a decryption operation. For properties that are read frequently (like database passwords on every connection), this can add overhead. However, in practice, Spring Boot caches property values after the first resolution. The decryption happens once during context initialization. But if you have many encrypted properties (say 50+), the startup time can increase noticeably. I've measured about 10-20ms per decryption with PBEWithHMACSHA512AndAES_256 on a typical server. For a large application with 100 encrypted properties, that's 1-2 seconds of startup delay. That's usually acceptable, but if you're in a serverless environment with cold starts, you might want to optimize. One approach is to use a faster algorithm like PBEWithHMACSHA256AndAES_128 (still secure but faster). Another is to cache the decrypted values in a local map if you're reading them repeatedly outside of Spring's property resolution. Also, be aware that if you use Jasypt with Spring Cloud Config, the decryption happens on the client side, not the server. This distributes the overhead across services. Finally, never encrypt properties that don't need it — encrypting a logging level or a feature flag is overkill and adds unnecessary startup time.

import org.jasypt.encryption.pbe.StandardPBEStringEncryptor;

public class PerformanceTest {
    public static void main(String[] args) {
        StandardPBEStringEncryptor encryptor = new StandardPBEStringEncryptor();
        encryptor.setPassword("testpassword");
        encryptor.setAlgorithm("PBEWithHMACSHA512AndAES_256");
        encryptor.setIvGenerator(new RandomIvGenerator());
        encryptor.setKeyObtentionIterations(1000);
        
        String encrypted = encryptor.encrypt("sensitiveValue");
        long start = System.nanoTime();
        for (int i = 0; i < 1000; i++) {
            encryptor.decrypt(encrypted);
        }
        long end = System.nanoTime();
        System.out.println("Average decryption time: " + (end - start) / 1_000_000 + " ms");
    }
}

8. Production Debugging: When Decryption Fails

Decryption failures in production are stressful. The most common symptom is the application failing to start with a cryptic 'DecryptionException: Unable to decrypt' message. The first thing to check: is the master password correct? Did someone rotate it without re-encrypting the properties? Next, verify that the algorithm and iteration count match between encryption and decryption. A mismatch will cause silent failures or wrong decryption. Another common issue: the encrypted value contains special characters that break the properties file parser. For example, if the encrypted Base64 string contains a colon or equals sign, it might be misinterpreted. Always wrap encrypted values in quotes in YAML files. In properties files, the ENC(...) syntax is safe as long as the encrypted string doesn't contain spaces. Also, check if the Jasypt version is consistent across environments. Using different minor versions can cause incompatibility in the encryption format. Finally, if you're using multiple encryptors, ensure the correct bean is being used for each property. A property encrypted with one encryptor won't decrypt with another. I once spent two hours debugging a production issue where a developer had accidentally used the wrong encryptor bean name in the properties file.

import org.jasypt.encryption.pbe.StandardPBEStringEncryptor;

public class DecryptionDebug {
    public static void main(String[] args) {
        String encryptedValue = "9aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abcdefghijklmnop";
        String password = System.getenv("JASYPT_ENCRYPTOR_PASSWORD");
        
        StandardPBEStringEncryptor encryptor = new StandardPBEStringEncryptor();
        encryptor.setPassword(password);
        encryptor.setAlgorithm("PBEWithHMACSHA512AndAES_256");
        encryptor.setIvGenerator(new RandomIvGenerator());
        encryptor.setKeyObtentionIterations(1000);
        
        try {
            String decrypted = encryptor.decrypt(encryptedValue);
            System.out.println("Decryption succeeded: " + decrypted);
        } catch (Exception e) {
            System.err.println("Decryption failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}