屬性解密：屬性源優(yōu)先級(jí)與解密層實(shí)踐)
寫在最前面系統(tǒng)屬性這層?xùn)|西平時(shí)誰都不會(huì)特意去看它可一旦里面塞了加密值問題就會(huì)變得很別扭——配置文件里寫明文的那套經(jīng)驗(yàn)全失效了。前段時(shí)間我接手一個(gè)項(xiàng)目運(yùn)維在啟動(dòng)腳本里用-D傳了一串加密后的數(shù)據(jù)庫口令結(jié)果 Spring 容器起來之后拿到的還是密文連接池直接報(bào)認(rèn)證失敗。后來折騰了大半天才把整條鏈路捋順?biāo)餍园堰^程整理一下從屬性源的優(yōu)先級(jí)、解密層的插入位置到幾個(gè)幾乎必踩的坑一次說清楚。這篇內(nèi)容適合已經(jīng)寫過 Spring Boot、但沒系統(tǒng)研究過屬性加載鏈路的朋友也適合正在給老項(xiàng)目補(bǔ)安全加固的同學(xué)照著做。1. 系統(tǒng)屬性在 Spring Boot 屬性鏈路里的真實(shí)位置1.1 一次 setProperty 之后值究竟被誰讀走了System.setProperty(key, value)寫進(jìn)去的東西本質(zhì)上是 JVM 全局的一張Properties表底層是Hashtable進(jìn)程內(nèi)所有線程共享生命周期跟 JVM 一致。Spring Boot 在啟動(dòng)早期會(huì)把這張表包裝成一個(gè)PropertySource名字固定叫systemProperties塞進(jìn)MutablePropertySources里。你后面寫的Value(${xxx})、ConfigurationProperties、environment.getProperty(xxx)最終都會(huì)順著這條鏈一路找下來。關(guān)鍵在于包裝這兩個(gè)字。Spring 拿到的不是你原始那張Properties而是一個(gè)只讀視圖getProperty每次調(diào)用都會(huì)實(shí)時(shí)去問 JVM。也就是說你在容器啟動(dòng)之后調(diào)System.setPropertyenvironment.getProperty是能立刻讀到新值的。但已經(jīng)完成綁定的 Bean、已經(jīng)解析完的占位符不會(huì)自動(dòng)刷新這一點(diǎn)后面會(huì)專門講。理解這一層很重要。很多人以為系統(tǒng)屬性就是環(huán)境變量的小名其實(shí)兩者在 Spring Boot 里是兩個(gè)獨(dú)立的屬性源名字分別是systemProperties和systemEnvironment優(yōu)先級(jí)也不一樣系統(tǒng)屬性排在環(huán)境變量前面。這個(gè)順序直接決定了你的加密值會(huì)不會(huì)被別的配置蓋掉。1.2 屬性源優(yōu)先級(jí)決定了你的加密值會(huì)被誰覆蓋Spring Boot 的屬性源是有明確順序的靠前的優(yōu)先。下面這張表是我實(shí)際排查時(shí)整理的只列了日常最常撞上的幾層優(yōu)先級(jí)屬性源典型來源1命令行參數(shù)--app.secret.xxx...2SPRING_APPLICATION_JSON環(huán)境變量里的 JSON3Servlet 相關(guān)參數(shù)少見4JNDI少見5systemProperties-Dkeyvalue、System.setProperty6systemEnvironment操作系統(tǒng)環(huán)境變量7random.*隨機(jī)值8外部配置文件jar 同級(jí)的application.yml9jar 內(nèi)配置文件classpath:/application.yml10PropertySource代碼里聲明的11默認(rèn)值SpringApplication.setDefaultProperties從這個(gè)順序能看出來兩件事。第一系統(tǒng)屬性天然壓過application.yml你在配置文件里寫同名 key 是蓋不住它的這是好事方便運(yùn)維用啟動(dòng)參數(shù)覆蓋。第二命令行參數(shù)又壓過系統(tǒng)屬性所以如果有人用--app.secret.xxx明文啟動(dòng)你的加密邏輯就白做了——這一點(diǎn)在做兜底校驗(yàn)時(shí)值得加一條判斷。還有個(gè)容易忽略的細(xì)節(jié)Profile 相關(guān)的配置文件application-prod.yml排在同名非 Profile 文件前面但它們整體都排在系統(tǒng)屬性之后。所以只要 key 對(duì)得上系統(tǒng)屬性永遠(yuǎn)贏。這也解釋了為什么有些團(tuán)隊(duì)喜歡把所有敏感配置都通過-D注入而不是寫進(jìn)配置文件。1.3 三個(gè)必須提前想清楚的時(shí)間點(diǎn)做加解密之前有三個(gè)時(shí)間點(diǎn)必須先確認(rèn)否則代碼寫得再漂亮也不生效。設(shè)置時(shí)間點(diǎn)System.setProperty是在SpringApplication.run()之前、之中還是之后調(diào)的之前最穩(wěn)Spring 能完整讀到之中取決于具體階段之后只能保證environment.getProperty讀到已經(jīng)綁定的 Bean 拿不到。解密層插入時(shí)間點(diǎn)解密邏輯必須插在所有讀取動(dòng)作之前。Spring Boot 提供了EnvironmentPostProcessor、ApplicationContextInitializer、BeanFactoryPostProcessor三個(gè)常見鉤子它們的執(zhí)行階段完全不同選錯(cuò)了就會(huì)出現(xiàn)配置文件里的能解密、系統(tǒng)屬性里的不能這種詭異現(xiàn)象。占位符解析時(shí)間點(diǎn)Value的占位符由PropertySourcesPlaceholderConfigurer在 Bean 實(shí)例化階段解析晚于環(huán)境準(zhǔn)備。所以只要在環(huán)境準(zhǔn)備階段把屬性源包一層Value就能拿到解密值。我見過最典型的翻車方式是在某個(gè)PostConstruct方法里調(diào)System.setProperty塞密鑰然后指望Value能讀到。結(jié)果 Bean 初始化順序稍微一變讀到的就是 null。這類問題排查起來極其費(fèi)勁因?yàn)椴粓?bào)錯(cuò)只是值不對(duì)。2. 方案選型三種落地路徑的邊界與取舍2.1 路徑一在設(shè)置源頭就地解密最直接的做法是在main方法里、SpringApplication.run之前把系統(tǒng)屬性里的加密值解密后重新setProperty回去。代碼大概長這樣public static void main(String[] args) { decryptSystemProperties(); SpringApplication.run(DemoApplication.class, args); } private static void decryptSystemProperties() { Properties props System.getProperties(); for (String name : props.stringPropertyNames()) { String raw props.getProperty(name); if (raw ! null raw.startsWith(enc:v1:)) { System.setProperty(name, AesGcmCipher.decrypt(raw)); } } }這段代碼的優(yōu)勢(shì)是簡單、無框架依賴、執(zhí)行時(shí)機(jī)絕對(duì)早。缺點(diǎn)是它會(huì)把解密后的明文回寫到 JVM 系統(tǒng)屬性里任何能讀System.getProperties()的代碼包括某些診斷工具都能看到明文。另外它只處理系統(tǒng)屬性配置文件里的加密值管不著如果你的項(xiàng)目兩種來源都有就得維護(hù)兩套邏輯。這條路徑適合什么場(chǎng)景我總結(jié)下來是項(xiàng)目規(guī)模小、敏感配置全部走啟動(dòng)參數(shù)、團(tuán)隊(duì)不想引入額外依賴。反過來說如果配置文件里也有加密值或者需要按環(huán)境切換密鑰版本就別選它了后期會(huì)很難受。2.2 路徑二用 Jasypt 兜住所有屬性源Jasypt 的 Spring Boot Starter 是這類需求里出場(chǎng)率最高的方案。它的思路是提供一個(gè)EncryptablePropertySourceConverter在容器 refresh 之前把所有PropertySource逐個(gè)包一層讀取時(shí)遇到ENC(...)包裹的值就解密。配置成本很低加個(gè)依賴、配個(gè)密鑰就行。它對(duì)系統(tǒng)屬性同樣有效因?yàn)閟ystemProperties也在被包裝的名單里。我實(shí)測(cè)過-Dapp.secret.db-passwordENC(xxx)這種寫法Spring 讀出來是解密后的值。具體流程是EnableEncryptablePropertiesBeanFactoryPostProcessor在BeanFactory后置處理階段觸發(fā)屬性源轉(zhuǎn)換此時(shí)Environment已經(jīng)準(zhǔn)備好了所以Value和ConfigurationProperties都能拿到明文。但 Jasypt 有幾個(gè)需要提前知道的邊界。它的密鑰本身要通過jasypt.encryptor.password配置這個(gè)值如果也從系統(tǒng)屬性來就得保證包裝之前已經(jīng)就位它的默認(rèn)算法是PBEWITHHMACSHA512ANDAES_256需要 BouncyCastle 支持JDK 版本低的項(xiàng)目要額外引依賴它對(duì)值的前綴匹配是ENC(開頭、)結(jié)尾如果你的密文里恰好包含這個(gè)模式會(huì)被二次解密產(chǎn)生莫名其妙的錯(cuò)誤。還有一個(gè)隱蔽的問題Jasypt 的包裝發(fā)生在BeanFactory后置處理階段比EnvironmentPostProcessor晚。如果某個(gè)EnvironmentPostProcessor在更早的階段就要讀加密屬性比如決定加載哪個(gè)配置文件那時(shí)候還是密文。這種情況雖然少見但一旦碰上就很難定位。2.3 路徑三自己包裝 PropertySource第三種是自己寫一個(gè)EnvironmentPostProcessor在環(huán)境準(zhǔn)備階段遍歷所有屬性源把需要處理的那幾個(gè)替換成解密包裝器。這種做法可控性最高能精確控制包裝哪些源、能自定義密文前綴、能支持密鑰版本、能在解密失敗時(shí)給出明確日志。代價(jià)是要自己寫代碼大概一百多行包括一個(gè)加解密工具類、一個(gè)PropertySource包裝器、一個(gè)EnvironmentPostProcessor實(shí)現(xiàn)和注冊(cè)文件。聽著多其實(shí)拆開看每一塊都不復(fù)雜后面第三章會(huì)給出完整實(shí)現(xiàn)。這條路徑適合對(duì)安全有明確要求、或者需要和現(xiàn)有密鑰管理流程對(duì)接的項(xiàng)目。比如你的密鑰來自某個(gè)配置中心需要在啟動(dòng)時(shí)拉取那用自定義處理器就比 Jasypt 靈活得多。2.4 三條路徑的橫向?qū)Ρ染S度源頭就地解密Jasypt Starter自定義 PropertySource實(shí)現(xiàn)成本極低低中覆蓋配置文件否是是覆蓋系統(tǒng)屬性是是是密鑰版本支持需自己實(shí)現(xiàn)弱強(qiáng)明文殘留會(huì)回寫系統(tǒng)屬性不回寫不回寫執(zhí)行時(shí)機(jī)最早較晚可調(diào)排查難度低中中選型上我的建議是新項(xiàng)目、配置來源統(tǒng)一走啟動(dòng)參數(shù)的選路徑一夠用且省事已經(jīng)在用 Spring Boot 且只想快速補(bǔ)上的選 Jasypt對(duì)密鑰輪換、審計(jì)日志有要求的老老實(shí)實(shí)寫自定義處理器。三條路徑也可以混用比如配置文件走 Jasypt、系統(tǒng)屬性走源頭解密但混用會(huì)讓排查變復(fù)雜不建議。3. 手寫一個(gè)能識(shí)別系統(tǒng)屬性的解密層3.1 先寫一個(gè)靠譜的 AES-GCM 工具類算法選擇上我不推薦再用PBEWithMD5AndDES這個(gè)在 Jasypt 老版本里是默認(rèn)值強(qiáng)度已經(jīng)不夠看了。直接上AES/GCM/NoPadding帶認(rèn)證標(biāo)簽?zāi)芡瑫r(shí)防篡改。public final class AesGcmCipher { private static final String TRANSFORMATION AES/GCM/NoPadding; private static final int IV_LENGTH 12; private static final int TAG_LENGTH_BIT 128; private static final String PREFIX enc:v1:; private static final SecureRandom RANDOM new SecureRandom(); private AesGcmCipher() { } public static String encrypt(String plain, SecretKey key) throws Exception { byte[] iv new byte[IV_LENGTH]; RANDOM.nextBytes(iv); Cipher cipher Cipher.getInstance(TRANSFORMATION); cipher.init(Cipher.ENCRYPT_MODE, key, new GCMParameterSpec(TAG_LENGTH_BIT, iv)); byte[] cipherText cipher.doFinal(plain.getBytes(StandardCharsets.UTF_8)); ByteBuffer buffer ByteBuffer.allocate(iv.length cipherText.length); buffer.put(iv).put(cipherText); return PREFIX Base64.getUrlEncoder().withoutPadding() .encodeToString(buffer.array()); } public static String decrypt(String encoded, SecretKey key) throws Exception { if (encoded null || !encoded.startsWith(PREFIX)) { return encoded; } byte[] all Base64.getUrlDecoder() .decode(encoded.substring(PREFIX.length())); ByteBuffer buffer ByteBuffer.wrap(all); byte[] iv new byte[IV_LENGTH]; buffer.get(iv); byte[] cipherText new byte[buffer.remaining()]; buffer.get(cipherText); Cipher cipher Cipher.getInstance(TRANSFORMATION); cipher.init(Cipher.DECRYPT_MODE, key, new GCMParameterSpec(TAG_LENGTH_BIT, iv)); return new String(cipher.doFinal(cipherText), StandardCharsets.UTF_8); } }幾個(gè)點(diǎn)值得說明。Base64.getUrlEncoder()用的是 URL 安全字符集把和/換成了-和_這樣密文丟進(jìn)啟動(dòng)腳本、環(huán)境變量、URL 查詢串都不會(huì)被轉(zhuǎn)義。我就吃過這個(gè)虧標(biāo)準(zhǔn) Base64 里的在某個(gè) CI 平臺(tái)的變量傳遞環(huán)節(jié)被轉(zhuǎn)成了空格解密直接報(bào)填充異常查了兩小時(shí)。前綴enc:v1:有兩個(gè)作用一是避免誤傷普通值二是為密鑰輪換預(yù)留版本號(hào)。以后換密鑰就上enc:v2:解密時(shí)按版本選對(duì)應(yīng)密鑰老數(shù)據(jù)不用一次性全刷。IV 長度選 12 字節(jié)是 GCM 的推薦值性能最好。認(rèn)證標(biāo)簽 128 位是標(biāo)準(zhǔn)配置別為了省幾個(gè)字節(jié)改成 96 位收益微乎其微。3.2 包裝屬性源時(shí)的關(guān)鍵選擇Enumerable 不能丟寫包裝器的時(shí)候有個(gè)坑必須提前避開如果你把一個(gè)EnumerablePropertySource包裝成普通的PropertySourcegetPropertyNames()就返回不了了。后果是ConfigurationProperties的寬松綁定失效、Environment.getProperty的下標(biāo)查找失效、actuator 的/env端點(diǎn)看不到這些屬性。所以包裝類要按源的類型分兩種實(shí)現(xiàn)或者直接寫一個(gè)繼承EnumerablePropertySource的版本public class DecryptingPropertySource extends EnumerablePropertySourcePropertySource? { private final SecretResolver resolver; private final PredicateString keyFilter; public DecryptingPropertySource(String name, PropertySource? source, SecretResolver resolver, PredicateString keyFilter) { super(name, source); this.resolver resolver; this.keyFilter keyFilter; } Override public Object getProperty(String name) { Object value source.getProperty(name); if (value instanceof String str keyFilter.test(name)) { return resolver.resolve(str); } return value; } Override public String[] getPropertyNames() { if (source instanceof EnumerablePropertySource? enumerable) { return enumerable.getPropertyNames(); } return new String[0]; } Override public boolean containsProperty(String name) { return source.containsProperty(name); } }SecretResolver負(fù)責(zé)真正的解密內(nèi)部加一層ConcurrentHashMap緩存同一個(gè)密文只解一次。啟動(dòng)階段屬性可能被讀幾百次緩存能省下不少開銷。public class SecretResolver { private final MapString, SecretKey keys; private final MapString, String cache new ConcurrentHashMap(); public SecretResolver(MapString, SecretKey keys) { this.keys keys; } public String resolve(String raw) { if (raw null || !raw.startsWith(enc:)) { return raw; } return cache.computeIfAbsent(raw, this::doResolve); } private String doResolve(String raw) { String version raw.substring(4, raw.indexOf(:, 4)); SecretKey key keys.get(version); if (key null) { throw new IllegalStateException(未找到密鑰版本: version); } try { return AesGcmCipher.decrypt(raw, key); } catch (Exception e) { throw new IllegalStateException(屬性解密失敗請(qǐng)檢查密鑰與密文是否匹配, e); } } }注意異常信息里不要帶明文也不要帶完整密文。帶上密鑰版本號(hào)就夠了生產(chǎn)日志里泄露密文等于泄露了一半信息。3.3 EnvironmentPostProcessor 的注冊(cè)和生效時(shí)機(jī)處理器本身很簡單核心是遍歷屬性源、替換、保持順序public class DecryptingEnvironmentPostProcessor implements EnvironmentPostProcessor, Ordered { Override public void postProcessEnvironment(ConfigurableEnvironment environment, SpringApplication application) { SecretResolver resolver SecretKeyLoader.load(environment); MutablePropertySources sources environment.getPropertySources(); ListString names new ArrayList(); for (PropertySource? ps : sources) { names.add(ps.getName()); } PredicateString filter name - name.startsWith(app.secret.) || name.startsWith(spring.datasource.); for (String name : names) { PropertySource? original sources.get(name); if (original null || original instanceof DecryptingPropertySource) { continue; } sources.replace(name, new DecryptingPropertySource(name, original, resolver, filter)); } } Override public int getOrder() { return Ordered.LOWEST_PRECEDENCE; } }getOrder()返回LOWEST_PRECEDENCE是有講究的。Spring Boot 2.4 之后配置文件通過ConfigDataEnvironmentPostProcessor加載它的 order 很靠前。如果你的處理器 order 太小執(zhí)行時(shí)application.yml還沒進(jìn)屬性源列表就漏掉了。設(shè)成最低優(yōu)先級(jí)能保證所有配置文件都加載完之后再統(tǒng)一包裝。迭代時(shí)要先收集名字快照不能在遍歷MutablePropertySources的同時(shí)調(diào)用replace會(huì)拋ConcurrentModificationException。這個(gè)坑我在第一次寫的時(shí)候踩過啟動(dòng)直接掛掉。SecretKeyLoader負(fù)責(zé)從環(huán)境變量或外部密鑰文件讀取主密鑰。這里要強(qiáng)調(diào)一點(diǎn)密鑰絕不能和密文放在同一個(gè)屬性源里。密文在啟動(dòng)參數(shù)、密鑰在環(huán)境變量這是最低要求再好一點(diǎn)是密鑰從掛載的 secret 文件讀只有特定用戶可讀。3.4 Spring Boot 3.x 的注冊(cè)差異與兼容寫法Spring Boot 2.x 的注冊(cè)文件是META-INF/spring.factoriesorg.springframework.boot.env.EnvironmentPostProcessor\ com.example.config.DecryptingEnvironmentPostProcessorSpring Boot 3.x 改成了META-INF/spring/org.springframework.boot.env.EnvironmentPostProcessor.imports內(nèi)容直接寫類名一行一個(gè)com.example.config.DecryptingEnvironmentPostProcessor如果項(xiàng)目要同時(shí)兼容 2.x 和 3.x兩個(gè)文件都放內(nèi)容各寫各的格式。Spring Boot 3 會(huì)優(yōu)先讀 imports 文件找不到再回退到spring.factories放兩份不會(huì)沖突。另外 3.x 對(duì)spring.factories的很多擴(kuò)展點(diǎn)都做了遷移如果你還依賴其他擴(kuò)展點(diǎn)建議一次性檢查一遍別只改了這一處。3.5 讓 Value、ConfigurationProperties、Environment 三條讀取路徑都走通包裝完之后要驗(yàn)證三條路徑是不是都拿到明文。Value走的是PropertySourcesPlaceholderConfigurer它讀的是Environment的propertySources包裝后的源直接生效沒問題。ConfigurationProperties走的是ConfigurationPropertySources這是一個(gè)在環(huán)境準(zhǔn)備末尾 attach 上去的視圖。因?yàn)樗?attach 時(shí)持有的是MutablePropertySources的引用遍歷是動(dòng)態(tài)的所以后包裝也生效。但要注意 attach 的時(shí)機(jī)在你的處理器之后——Ordered.LOWEST_PRECEDENCE恰好能保證這一點(diǎn)。environment.getProperty(key)直接遍歷propertySources同樣生效。有一個(gè)例外是PropertySource注解引入的屬性源。它的加載時(shí)機(jī)在ConfigurationClassPostProcessor階段晚于EnvironmentPostProcessor所以不會(huì)被包裝到。如果這個(gè)源里也有加密值需要單獨(dú)處理比如在BeanFactoryPostProcessor里再包一次或者干脆把加密值挪到application.yml里。4. 從加密一個(gè)值到項(xiàng)目跑起來的完整實(shí)操4.1 生成 256 位密鑰并加密目標(biāo)值密鑰生成用 KeyGenerator 就行別自己拼字節(jié)數(shù)組KeyGenerator generator KeyGenerator.getInstance(AES); generator.init(256, new SecureRandom()); SecretKey key generator.generateKey(); String base64Key Base64.getEncoder().encodeToString(key.getEncoded()); System.out.println(主密鑰: base64Key);256 位 AES 在 JDK 8u161 之后默認(rèn)就支持不需要額外裝策略文件。如果你的運(yùn)行環(huán)境是很老的 JDK 8 小版本跑的時(shí)候會(huì)拋InvalidKeyException: Illegal key size那就得升級(jí) JDK 或者裝無限強(qiáng)度策略文件。這個(gè)報(bào)錯(cuò)信息很明確一看就知道原因。拿到密鑰之后加密目標(biāo)值SecretKey key new SecretKeySpec(Base64.getDecoder().decode(base64Key), AES); String encrypted AesGcmCipher.encrypt(Pssw0rd-2024, key); System.out.println(encrypted);輸出大概長這樣enc:v1:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx長度 60 到 80 個(gè)字符之間具體取決于明文長度。4.2 啟動(dòng)腳本里注入系統(tǒng)屬性的幾種寫法Linux 下用-D傳參java -Dapp.secret.db-passwordenc:v1:xxxxx \ -Dspring.profiles.activeprod \ -jar demo.jar注意值里的特殊字符。雖然用了 URL 安全 Base64理論上只有字母數(shù)字和-_但前綴里有個(gè)冒號(hào)在 YAML 或某些腳本里冒號(hào)后面跟空格會(huì)被當(dāng)成分隔符。所以建議整個(gè)值用單引號(hào)包起來別圖省事。容器環(huán)境里更推薦用環(huán)境變量避免命令行參數(shù)被ps看到env: - name: APP_SECRET_DB_PASSWORD valueFrom: secretKeyRef: name: app-secret key: db-password環(huán)境變量名APP_SECRET_DB_PASSWORD會(huì)被 Spring Boot 的寬松綁定映射成app.secret.db-password所以你的代碼里照常寫Value(${app.secret.db-password})就行。這個(gè)映射規(guī)則是全大寫、下劃線轉(zhuǎn)點(diǎn)、點(diǎn)轉(zhuǎn)短橫線。搞清楚這條規(guī)則很多環(huán)境變量明明設(shè)了卻讀不到的問題就迎刃而解了。如果值里必須帶加密前綴環(huán)境變量這種方式反而更安全因?yàn)椴恍枰?jīng)過 shell 解析。4.3 寫個(gè)測(cè)試驗(yàn)證解密鏈路真的生效測(cè)試這塊有個(gè)坑SpringBootTest會(huì)緩存ApplicationContext如果第一個(gè)測(cè)試類啟動(dòng)時(shí)系統(tǒng)屬性還沒設(shè)后面再設(shè)也不會(huì)重新加載。所以要么用DirtiesContext要么在BeforeAll里設(shè)置并確保測(cè)試類順序。SpringBootTest DirtiesContext(classMode DirtiesContext.ClassMode.AFTER_CLASS) class SecretPropertyTest { static final String KEY 測(cè)試用密鑰的Base64; BeforeAll static void setUp() throws Exception { SecretKey key new SecretKeySpec(Base64.getDecoder().decode(KEY), AES); System.setProperty(app.secret.db-password, AesGcmCipher.encrypt(Pssw0rd-2024, key)); System.setProperty(APP_SECRET_KEY, KEY); } AfterAll static void tearDown() { System.clearProperty(app.secret.db-password); System.clearProperty(APP_SECRET_KEY); } Value(${app.secret.db-password}) String dbPassword; Autowired Environment environment; Test void 系統(tǒng)屬性應(yīng)被解密讀取() { assertThat(dbPassword).isEqualTo(Pssw0rd-2024); assertThat(environment.getProperty(app.secret.db-password)) .isEqualTo(Pssw0rd-2024); } }AfterAll里清理系統(tǒng)屬性這一步別省。系統(tǒng)屬性是 JVM 級(jí)別的測(cè)試跑完不清理會(huì)影響同一個(gè) JVM 里的其他測(cè)試類癥狀是單跑通過、全跑失敗特別難查。4.4 長度、性能與緩存的實(shí)際測(cè)算密文長度可以精確算出來。明文n字節(jié)GCM 加密后是n 16字節(jié)認(rèn)證標(biāo)簽加上 12 字節(jié) IV總共n 28字節(jié)。Base64 URL 無填充編碼后的長度是ceil((n 28) * 4 / 3)再減去填充再加上 7 個(gè)字符的前綴。拿一個(gè) 12 字符的口令舉例12 28 40字節(jié)Base64 后約 54 字符加前綴總共 61 字符。這個(gè)長度對(duì)啟動(dòng)參數(shù)和環(huán)境變量來說毫無壓力。性能方面AES-GCM 在現(xiàn)代 CPU 上有硬件加速指令單次加解密在微秒級(jí)。真正影響啟動(dòng)時(shí)間的是屬性被讀取的次數(shù)——一個(gè)中等規(guī)模的應(yīng)用啟動(dòng)時(shí)屬性讀取可能上萬次。所以緩存是必須的用ConcurrentHashMap以密文為 key 緩存明文命中率接近 100%。我實(shí)測(cè)過一個(gè)有 8 個(gè)加密屬性的項(xiàng)目加了緩存之后解密耗時(shí)從 40 毫秒降到 3 毫秒以內(nèi)。要提醒一句緩存里存的是明文內(nèi)存 dump 能看到。如果對(duì)內(nèi)存安全有極高要求可以考慮用char[]并在用完后清零但這會(huì)把代碼復(fù)雜度拉高不少一般業(yè)務(wù)系統(tǒng)不必做到這個(gè)程度。5. 踩坑實(shí)錄那些配置看著對(duì)但就是不生效的情況5.1 值被配置文件覆蓋的排查順序最常見的問題是系統(tǒng)屬性設(shè)了但讀出來還是配置文件里的值。排查順序我一般是這樣的第一步看 key 是否完全一致。系統(tǒng)屬性里的點(diǎn)號(hào)、短橫線、大小寫都有講究。app.secret.dbPassword和app.secret.db-password在寬松綁定下是同一個(gè)但在environment.getProperty里是兩個(gè)不同的 key。用Value時(shí)尤其容易搞混。第二步看屬性源順序有沒有被人為改過。有些項(xiàng)目啟動(dòng)時(shí)會(huì)調(diào)用environment.getPropertySources().addFirst(...)塞自定義源把系統(tǒng)屬性擠下去了。這種情況在引入了某些配置中心客戶端的項(xiàng)目里很常見。第三步看是不是加密前綴沒匹配上。比如你的密文是ENC(xxx)格式但處理器只認(rèn)enc:v1:那就原樣返回了原始字符串看著像沒解密。第四步看處理器有沒有真的被注冊(cè)。spring.factories里類名寫錯(cuò)一個(gè)字母就靜默不加載不報(bào)任何錯(cuò)?？梢栽谔幚砥骼锎蛞恍?info 日志啟動(dòng)時(shí)確認(rèn)一下。5.2 解密異常與亂碼的定位方法解密報(bào)錯(cuò)無非幾類。AEADBadTagException說明密鑰不對(duì)或者密文被改過這是 GCM 的認(rèn)證失敗屬于最明確的一類。IllegalBlockSizeException通常是密文被截?cái)啾热鐐鬏斶^程中丟了字符。IllegalArgumentException: Illegal base64 character說明 Base64 解碼失敗基本可以斷定是特殊字符被轉(zhuǎn)義了。亂碼問題多數(shù)出在編碼上。加密時(shí)用 UTF-8 取字節(jié)解密時(shí)也必須用 UTF-8 還原中間任何一步用了平臺(tái)默認(rèn)編碼都可能出問題。特別是在 Windows 上開發(fā)、Linux 上部署的場(chǎng)景默認(rèn)編碼不一樣很容易踩。還有一種隱蔽情況屬性值本身就是空字符串。System.setProperty(key, )設(shè)進(jìn)去之后environment.getProperty返回的是空串而不是 null某些框架會(huì)把空串當(dāng)成未配置處理走了默認(rèn)值分支。如果加密后的值恰好解出空串行為會(huì)很怪。建議在解密之后加一句判空把空串轉(zhuǎn)成 null 或者直接拋異常。5.3 常見問題速查表現(xiàn)象可能原因處理方式讀到的是密文原文處理器未注冊(cè)或 order 太靠前檢查注冊(cè)文件order 設(shè) LOWEST_PRECEDENCE讀到的是配置文件的值屬性源被 addFirst 覆蓋檢查是否有自定義源插到最前面啟動(dòng)報(bào) InvalidKeyExceptionJDK 版本低不支持 256 位升級(jí) JDK 或裝無限強(qiáng)度策略報(bào) AEADBadTagException密鑰不匹配或密文損壞核對(duì)密鑰版本檢查傳輸過程報(bào) Illegal base64 character密文中特殊字符被轉(zhuǎn)義改用 URL 安全 Base64ConfigurationProperties 綁不上包裝時(shí)丟了 Enumerable包裝類繼承 EnumerablePropertySource測(cè)試單跑通過全跑失敗系統(tǒng)屬性污染AfterAll 里清理系統(tǒng)屬性環(huán)境變量設(shè)了但讀不到命名映射規(guī)則不匹配全大寫、下劃線分詞5.4 密鑰管理和日志里的安全紅線有幾個(gè)紅線是必須守住的。密鑰不能出現(xiàn)在代碼倉庫里包括測(cè)試代碼。測(cè)試用的密鑰要單獨(dú)生成只用于測(cè)試環(huán)境而且要明確標(biāo)注僅測(cè)試使用。密鑰不能和密文在同一個(gè)屬性源。如果兩部分都在application.yml里那加密等于沒做任何一個(gè)能看配置文件的人都能解密。日志里不能打印解密后的值。很多框架在 debug 級(jí)別會(huì)打印屬性綁定的過程如果你的屬性名比較敏感比如帶password要確認(rèn)這些日志不會(huì)上線。異常堆棧里不能帶明文。Cipher.doFinal拋異常時(shí)不會(huì)帶明文但如果你自己包裝異常時(shí)把原值拼進(jìn) message那就漏了。前面給的SecretResolver里我只帶了密鑰版本就是這個(gè)考慮。還有一點(diǎn)容易被忽略actuator 的/env和/configprops端點(diǎn)默認(rèn)會(huì)做脫敏脫敏規(guī)則是匹配password、secret、key、token這類關(guān)鍵詞。如果你的屬性名叫app.datasource.credential不在這份名單里就會(huì)被原樣展示。這個(gè)名單可以自定義但更穩(wěn)妥的做法是直接限制這些端點(diǎn)的訪問權(quán)限。6. 上線前的加固清單6.1 actuator 端點(diǎn)的脫敏處理Spring Boot 的脫敏靠SanitizingFunction實(shí)現(xiàn)2.6 之后可以自定義。默認(rèn)規(guī)則只覆蓋常見關(guān)鍵詞業(yè)務(wù)自定義的屬性名很容易漏。Bean public SanitizingFunction customSanitizer() { return property - { String name property.getName().toLowerCase(); if (name.contains(credential) || name.contains(passwd) || name.contains(private)) { return property.withValue(******); } return property; }; }這段代碼注冊(cè)到容器后/env端點(diǎn)里匹配到的值都會(huì)顯示成星號(hào)。注意這只是展示層面的保護(hù)屬性值在內(nèi)存里仍然是明文別把它當(dāng)成加密手段。更徹底的做法是把 actuator 端點(diǎn)限制在內(nèi)網(wǎng)訪問或者干脆在生產(chǎn)環(huán)境只暴露health和info。配置項(xiàng)management.endpoints.web.exposure.include設(shè)成health,info就夠用了。6.2 密鑰輪換與多版本密鑰的共存設(shè)計(jì)密鑰輪換是安全實(shí)踐里的常規(guī)操作但在配置加密這個(gè)場(chǎng)景下很容易做砸。核心思路是解密時(shí)支持多個(gè)版本加密時(shí)只用最新版本。前面給的enc:v1:前綴就是為此設(shè)計(jì)的。輪換時(shí)先生成 v2 密鑰把SecretResolver的 keys 映射表里同時(shí)放 v1 和 v2重新加密所有敏感值并替換成enc:v2:前綴確認(rèn)沒有 v1 的密文殘留之后再把 v1 從映射表里移除。這個(gè)過程可以分多次發(fā)布完成不需要一次性切換。第一版發(fā)布只加 v2 密鑰的支持密文還是 v1第二版發(fā)布把密文換成 v2第三版發(fā)布移除 v1 密鑰。每次發(fā)布都可回滾風(fēng)險(xiǎn)可控。要注意的是如果密鑰來自外部服務(wù)輪換時(shí)要考慮服務(wù)的可用性。密鑰服務(wù)掛了會(huì)導(dǎo)致應(yīng)用完全起不來所以本地最好有一份降級(jí)密鑰或者把密鑰緩存到本地文件。6.3 測(cè)試環(huán)境與生產(chǎn)環(huán)境的隔離測(cè)試環(huán)境的密鑰和生產(chǎn)環(huán)境必須完全不同這是基本要求。但實(shí)際項(xiàng)目里經(jīng)常出現(xiàn)測(cè)試密鑰硬編碼在代碼里、生產(chǎn)環(huán)境復(fù)用的情況。我的做法是把密鑰來源做成可配置的通過app.secret.key-source指定可選值是env、file、vault。測(cè)試環(huán)境用env配合 CI 的變量注入生產(chǎn)環(huán)境用file掛載只讀的密鑰文件。這樣同一份代碼在不同環(huán)境走不同路徑不需要改代碼。同時(shí)要在啟動(dòng)時(shí)加一條校驗(yàn)如果檢測(cè)到當(dāng)前是生產(chǎn) Profile 但密鑰來源是env且密鑰長度不足直接啟動(dòng)失敗。寧可起不來也別帶著弱密鑰跑起來。另外測(cè)試環(huán)境的數(shù)據(jù)最好也是脫敏的。有些團(tuán)隊(duì)為了圖省事把生產(chǎn)數(shù)據(jù)導(dǎo)到測(cè)試庫密碼還是同一套這種時(shí)候加密配置就形同虛設(shè)了。我個(gè)人在實(shí)際操作中的體會(huì)是配置加密這件事真正的難點(diǎn)不在算法而在讓所有人都按同一套規(guī)則來。代碼里寫得再完善運(yùn)維在啟動(dòng)腳本里直接寫明文整條鏈路就破了。所以落地的時(shí)候除了技術(shù)方案最好再配一條啟動(dòng)校驗(yàn)檢測(cè)到關(guān)鍵屬性沒有加密前綴時(shí)打一條 WARN 日志慢慢把習(xí)慣糾正過來。踩過幾次坑之后我發(fā)現(xiàn)日志比文檔管用得多。 Spring Boot系統(tǒng)屬性解密：屬性源優(yōu)先級(jí)與解密層實(shí)踐
寫在最前面系統(tǒng)屬性這層?xùn)|西平時(shí)誰都不會(huì)特意去看它可一旦里面塞了加密值問題就會(huì)變得很別扭——配置文件里寫明文的那套經(jīng)驗(yàn)全失效了。前段時(shí)間我接手一個(gè)項(xiàng)目運(yùn)維在啟動(dòng)腳本里用-D傳了一串加密后的數(shù)據(jù)庫口令結(jié)果 Spring 容器起來之后拿到的還是密文連接池直接報(bào)認(rèn)證失敗。后來折騰了大半天才把整條鏈路捋順?biāo)餍园堰^程整理一下從屬性源的優(yōu)先級(jí)、解密層的插入位置到幾個(gè)幾乎必踩的坑一次說清楚。這篇內(nèi)容適合已經(jīng)寫過 Spring Boot、但沒系統(tǒng)研究過屬性加載鏈路的朋友也適合正在給老項(xiàng)目補(bǔ)安全加固的同學(xué)照著做。1. 系統(tǒng)屬性在 Spring Boot 屬性鏈路里的真實(shí)位置1.1 一次 setProperty 之后值究竟被誰讀走了System.setProperty(key, value)寫進(jìn)去的東西本質(zhì)上是 JVM 全局的一張Properties表底層是Hashtable進(jìn)程內(nèi)所有線程共享生命周期跟 JVM 一致。Spring Boot 在啟動(dòng)早期會(huì)把這張表包裝成一個(gè)PropertySource名字固定叫systemProperties塞進(jìn)MutablePropertySources里。你后面寫的Value(${xxx})、ConfigurationProperties、environment.getProperty(xxx)最終都會(huì)順著這條鏈一路找下來。關(guān)鍵在于包裝這兩個(gè)字。Spring 拿到的不是你原始那張Properties而是一個(gè)只讀視圖getProperty每次調(diào)用都會(huì)實(shí)時(shí)去問 JVM。也就是說你在容器啟動(dòng)之后調(diào)System.setPropertyenvironment.getProperty是能立刻讀到新值的。但已經(jīng)完成綁定的 Bean、已經(jīng)解析完的占位符不會(huì)自動(dòng)刷新這一點(diǎn)后面會(huì)專門講。理解這一層很重要。很多人以為系統(tǒng)屬性就是環(huán)境變量的小名其實(shí)兩者在 Spring Boot 里是兩個(gè)獨(dú)立的屬性源名字分別是systemProperties和systemEnvironment優(yōu)先級(jí)也不一樣系統(tǒng)屬性排在環(huán)境變量前面。這個(gè)順序直接決定了你的加密值會(huì)不會(huì)被別的配置蓋掉。1.2 屬性源優(yōu)先級(jí)決定了你的加密值會(huì)被誰覆蓋Spring Boot 的屬性源是有明確順序的靠前的優(yōu)先。下面這張表是我實(shí)際排查時(shí)整理的只列了日常最常撞上的幾層優(yōu)先級(jí)屬性源典型來源1命令行參數(shù)--app.secret.xxx...2SPRING_APPLICATION_JSON環(huán)境變量里的 JSON3Servlet 相關(guān)參數(shù)少見4JNDI少見5systemProperties-Dkeyvalue、System.setProperty6systemEnvironment操作系統(tǒng)環(huán)境變量7random.*隨機(jī)值8外部配置文件jar 同級(jí)的application.yml9jar 內(nèi)配置文件classpath:/application.yml10PropertySource代碼里聲明的11默認(rèn)值SpringApplication.setDefaultProperties從這個(gè)順序能看出來兩件事。第一系統(tǒng)屬性天然壓過application.yml你在配置文件里寫同名 key 是蓋不住它的這是好事方便運(yùn)維用啟動(dòng)參數(shù)覆蓋。第二命令行參數(shù)又壓過系統(tǒng)屬性所以如果有人用--app.secret.xxx明文啟動(dòng)你的加密邏輯就白做了——這一點(diǎn)在做兜底校驗(yàn)時(shí)值得加一條判斷。還有個(gè)容易忽略的細(xì)節(jié)Profile 相關(guān)的配置文件application-prod.yml排在同名非 Profile 文件前面但它們整體都排在系統(tǒng)屬性之后。所以只要 key 對(duì)得上系統(tǒng)屬性永遠(yuǎn)贏。這也解釋了為什么有些團(tuán)隊(duì)喜歡把所有敏感配置都通過-D注入而不是寫進(jìn)配置文件。1.3 三個(gè)必須提前想清楚的時(shí)間點(diǎn)做加解密之前有三個(gè)時(shí)間點(diǎn)必須先確認(rèn)否則代碼寫得再漂亮也不生效。設(shè)置時(shí)間點(diǎn)System.setProperty是在SpringApplication.run()之前、之中還是之后調(diào)的之前最穩(wěn)Spring 能完整讀到之中取決于具體階段之后只能保證environment.getProperty讀到已經(jīng)綁定的 Bean 拿不到。解密層插入時(shí)間點(diǎn)解密邏輯必須插在所有讀取動(dòng)作之前。Spring Boot 提供了EnvironmentPostProcessor、ApplicationContextInitializer、BeanFactoryPostProcessor三個(gè)常見鉤子它們的執(zhí)行階段完全不同選錯(cuò)了就會(huì)出現(xiàn)配置文件里的能解密、系統(tǒng)屬性里的不能這種詭異現(xiàn)象。占位符解析時(shí)間點(diǎn)Value的占位符由PropertySourcesPlaceholderConfigurer在 Bean 實(shí)例化階段解析晚于環(huán)境準(zhǔn)備。所以只要在環(huán)境準(zhǔn)備階段把屬性源包一層Value就能拿到解密值。我見過最典型的翻車方式是在某個(gè)PostConstruct方法里調(diào)System.setProperty塞密鑰然后指望Value能讀到。結(jié)果 Bean 初始化順序稍微一變讀到的就是 null。這類問題排查起來極其費(fèi)勁因?yàn)椴粓?bào)錯(cuò)只是值不對(duì)。2. 方案選型三種落地路徑的邊界與取舍2.1 路徑一在設(shè)置源頭就地解密最直接的做法是在main方法里、SpringApplication.run之前把系統(tǒng)屬性里的加密值解密后重新setProperty回去。代碼大概長這樣public static void main(String[] args) { decryptSystemProperties(); SpringApplication.run(DemoApplication.class, args); } private static void decryptSystemProperties() { Properties props System.getProperties(); for (String name : props.stringPropertyNames()) { String raw props.getProperty(name); if (raw ! null raw.startsWith(enc:v1:)) { System.setProperty(name, AesGcmCipher.decrypt(raw)); } } }這段代碼的優(yōu)勢(shì)是簡單、無框架依賴、執(zhí)行時(shí)機(jī)絕對(duì)早。缺點(diǎn)是它會(huì)把解密后的明文回寫到 JVM 系統(tǒng)屬性里任何能讀System.getProperties()的代碼包括某些診斷工具都能看到明文。另外它只處理系統(tǒng)屬性配置文件里的加密值管不著如果你的項(xiàng)目兩種來源都有就得維護(hù)兩套邏輯。這條路徑適合什么場(chǎng)景我總結(jié)下來是項(xiàng)目規(guī)模小、敏感配置全部走啟動(dòng)參數(shù)、團(tuán)隊(duì)不想引入額外依賴。反過來說如果配置文件里也有加密值或者需要按環(huán)境切換密鑰版本就別選它了后期會(huì)很難受。2.2 路徑二用 Jasypt 兜住所有屬性源Jasypt 的 Spring Boot Starter 是這類需求里出場(chǎng)率最高的方案。它的思路是提供一個(gè)EncryptablePropertySourceConverter在容器 refresh 之前把所有PropertySource逐個(gè)包一層讀取時(shí)遇到ENC(...)包裹的值就解密。配置成本很低加個(gè)依賴、配個(gè)密鑰就行。它對(duì)系統(tǒng)屬性同樣有效因?yàn)閟ystemProperties也在被包裝的名單里。我實(shí)測(cè)過-Dapp.secret.db-passwordENC(xxx)這種寫法Spring 讀出來是解密后的值。具體流程是EnableEncryptablePropertiesBeanFactoryPostProcessor在BeanFactory后置處理階段觸發(fā)屬性源轉(zhuǎn)換此時(shí)Environment已經(jīng)準(zhǔn)備好了所以Value和ConfigurationProperties都能拿到明文。但 Jasypt 有幾個(gè)需要提前知道的邊界。它的密鑰本身要通過jasypt.encryptor.password配置這個(gè)值如果也從系統(tǒng)屬性來就得保證包裝之前已經(jīng)就位它的默認(rèn)算法是PBEWITHHMACSHA512ANDAES_256需要 BouncyCastle 支持JDK 版本低的項(xiàng)目要額外引依賴它對(duì)值的前綴匹配是ENC(開頭、)結(jié)尾如果你的密文里恰好包含這個(gè)模式會(huì)被二次解密產(chǎn)生莫名其妙的錯(cuò)誤。還有一個(gè)隱蔽的問題Jasypt 的包裝發(fā)生在BeanFactory后置處理階段比EnvironmentPostProcessor晚。如果某個(gè)EnvironmentPostProcessor在更早的階段就要讀加密屬性比如決定加載哪個(gè)配置文件那時(shí)候還是密文。這種情況雖然少見但一旦碰上就很難定位。2.3 路徑三自己包裝 PropertySource第三種是自己寫一個(gè)EnvironmentPostProcessor在環(huán)境準(zhǔn)備階段遍歷所有屬性源把需要處理的那幾個(gè)替換成解密包裝器。這種做法可控性最高能精確控制包裝哪些源、能自定義密文前綴、能支持密鑰版本、能在解密失敗時(shí)給出明確日志。代價(jià)是要自己寫代碼大概一百多行包括一個(gè)加解密工具類、一個(gè)PropertySource包裝器、一個(gè)EnvironmentPostProcessor實(shí)現(xiàn)和注冊(cè)文件。聽著多其實(shí)拆開看每一塊都不復(fù)雜后面第三章會(huì)給出完整實(shí)現(xiàn)。這條路徑適合對(duì)安全有明確要求、或者需要和現(xiàn)有密鑰管理流程對(duì)接的項(xiàng)目。比如你的密鑰來自某個(gè)配置中心需要在啟動(dòng)時(shí)拉取那用自定義處理器就比 Jasypt 靈活得多。2.4 三條路徑的橫向?qū)Ρ染S度源頭就地解密Jasypt Starter自定義 PropertySource實(shí)現(xiàn)成本極低低中覆蓋配置文件否是是覆蓋系統(tǒng)屬性是是是密鑰版本支持需自己實(shí)現(xiàn)弱強(qiáng)明文殘留會(huì)回寫系統(tǒng)屬性不回寫不回寫執(zhí)行時(shí)機(jī)最早較晚可調(diào)排查難度低中中選型上我的建議是新項(xiàng)目、配置來源統(tǒng)一走啟動(dòng)參數(shù)的選路徑一夠用且省事已經(jīng)在用 Spring Boot 且只想快速補(bǔ)上的選 Jasypt對(duì)密鑰輪換、審計(jì)日志有要求的老老實(shí)實(shí)寫自定義處理器。三條路徑也可以混用比如配置文件走 Jasypt、系統(tǒng)屬性走源頭解密但混用會(huì)讓排查變復(fù)雜不建議。3. 手寫一個(gè)能識(shí)別系統(tǒng)屬性的解密層3.1 先寫一個(gè)靠譜的 AES-GCM 工具類算法選擇上我不推薦再用PBEWithMD5AndDES這個(gè)在 Jasypt 老版本里是默認(rèn)值強(qiáng)度已經(jīng)不夠看了。直接上AES/GCM/NoPadding帶認(rèn)證標(biāo)簽?zāi)芡瑫r(shí)防篡改。public final class AesGcmCipher { private static final String TRANSFORMATION AES/GCM/NoPadding; private static final int IV_LENGTH 12; private static final int TAG_LENGTH_BIT 128; private static final String PREFIX enc:v1:; private static final SecureRandom RANDOM new SecureRandom(); private AesGcmCipher() { } public static String encrypt(String plain, SecretKey key) throws Exception { byte[] iv new byte[IV_LENGTH]; RANDOM.nextBytes(iv); Cipher cipher Cipher.getInstance(TRANSFORMATION); cipher.init(Cipher.ENCRYPT_MODE, key, new GCMParameterSpec(TAG_LENGTH_BIT, iv)); byte[] cipherText cipher.doFinal(plain.getBytes(StandardCharsets.UTF_8)); ByteBuffer buffer ByteBuffer.allocate(iv.length cipherText.length); buffer.put(iv).put(cipherText); return PREFIX Base64.getUrlEncoder().withoutPadding() .encodeToString(buffer.array()); } public static String decrypt(String encoded, SecretKey key) throws Exception { if (encoded null || !encoded.startsWith(PREFIX)) { return encoded; } byte[] all Base64.getUrlDecoder() .decode(encoded.substring(PREFIX.length())); ByteBuffer buffer ByteBuffer.wrap(all); byte[] iv new byte[IV_LENGTH]; buffer.get(iv); byte[] cipherText new byte[buffer.remaining()]; buffer.get(cipherText); Cipher cipher Cipher.getInstance(TRANSFORMATION); cipher.init(Cipher.DECRYPT_MODE, key, new GCMParameterSpec(TAG_LENGTH_BIT, iv)); return new String(cipher.doFinal(cipherText), StandardCharsets.UTF_8); } }幾個(gè)點(diǎn)值得說明。Base64.getUrlEncoder()用的是 URL 安全字符集把和/換成了-和_這樣密文丟進(jìn)啟動(dòng)腳本、環(huán)境變量、URL 查詢串都不會(huì)被轉(zhuǎn)義。我就吃過這個(gè)虧標(biāo)準(zhǔn) Base64 里的在某個(gè) CI 平臺(tái)的變量傳遞環(huán)節(jié)被轉(zhuǎn)成了空格解密直接報(bào)填充異常查了兩小時(shí)。前綴enc:v1:有兩個(gè)作用一是避免誤傷普通值二是為密鑰輪換預(yù)留版本號(hào)。以后換密鑰就上enc:v2:解密時(shí)按版本選對(duì)應(yīng)密鑰老數(shù)據(jù)不用一次性全刷。IV 長度選 12 字節(jié)是 GCM 的推薦值性能最好。認(rèn)證標(biāo)簽 128 位是標(biāo)準(zhǔn)配置別為了省幾個(gè)字節(jié)改成 96 位收益微乎其微。3.2 包裝屬性源時(shí)的關(guān)鍵選擇Enumerable 不能丟寫包裝器的時(shí)候有個(gè)坑必須提前避開如果你把一個(gè)EnumerablePropertySource包裝成普通的PropertySourcegetPropertyNames()就返回不了了。后果是ConfigurationProperties的寬松綁定失效、Environment.getProperty的下標(biāo)查找失效、actuator 的/env端點(diǎn)看不到這些屬性。所以包裝類要按源的類型分兩種實(shí)現(xiàn)或者直接寫一個(gè)繼承EnumerablePropertySource的版本public class DecryptingPropertySource extends EnumerablePropertySourcePropertySource? { private final SecretResolver resolver; private final PredicateString keyFilter; public DecryptingPropertySource(String name, PropertySource? source, SecretResolver resolver, PredicateString keyFilter) { super(name, source); this.resolver resolver; this.keyFilter keyFilter; } Override public Object getProperty(String name) { Object value source.getProperty(name); if (value instanceof String str keyFilter.test(name)) { return resolver.resolve(str); } return value; } Override public String[] getPropertyNames() { if (source instanceof EnumerablePropertySource? enumerable) { return enumerable.getPropertyNames(); } return new String[0]; } Override public boolean containsProperty(String name) { return source.containsProperty(name); } }SecretResolver負(fù)責(zé)真正的解密內(nèi)部加一層ConcurrentHashMap緩存同一個(gè)密文只解一次。啟動(dòng)階段屬性可能被讀幾百次緩存能省下不少開銷。public class SecretResolver { private final MapString, SecretKey keys; private final MapString, String cache new ConcurrentHashMap(); public SecretResolver(MapString, SecretKey keys) { this.keys keys; } public String resolve(String raw) { if (raw null || !raw.startsWith(enc:)) { return raw; } return cache.computeIfAbsent(raw, this::doResolve); } private String doResolve(String raw) { String version raw.substring(4, raw.indexOf(:, 4)); SecretKey key keys.get(version); if (key null) { throw new IllegalStateException(未找到密鑰版本: version); } try { return AesGcmCipher.decrypt(raw, key); } catch (Exception e) { throw new IllegalStateException(屬性解密失敗請(qǐng)檢查密鑰與密文是否匹配, e); } } }注意異常信息里不要帶明文也不要帶完整密文。帶上密鑰版本號(hào)就夠了生產(chǎn)日志里泄露密文等于泄露了一半信息。3.3 EnvironmentPostProcessor 的注冊(cè)和生效時(shí)機(jī)處理器本身很簡單核心是遍歷屬性源、替換、保持順序public class DecryptingEnvironmentPostProcessor implements EnvironmentPostProcessor, Ordered { Override public void postProcessEnvironment(ConfigurableEnvironment environment, SpringApplication application) { SecretResolver resolver SecretKeyLoader.load(environment); MutablePropertySources sources environment.getPropertySources(); ListString names new ArrayList(); for (PropertySource? ps : sources) { names.add(ps.getName()); } PredicateString filter name - name.startsWith(app.secret.) || name.startsWith(spring.datasource.); for (String name : names) { PropertySource? original sources.get(name); if (original null || original instanceof DecryptingPropertySource) { continue; } sources.replace(name, new DecryptingPropertySource(name, original, resolver, filter)); } } Override public int getOrder() { return Ordered.LOWEST_PRECEDENCE; } }getOrder()返回LOWEST_PRECEDENCE是有講究的。Spring Boot 2.4 之后配置文件通過ConfigDataEnvironmentPostProcessor加載它的 order 很靠前。如果你的處理器 order 太小執(zhí)行時(shí)application.yml還沒進(jìn)屬性源列表就漏掉了。設(shè)成最低優(yōu)先級(jí)能保證所有配置文件都加載完之后再統(tǒng)一包裝。迭代時(shí)要先收集名字快照不能在遍歷MutablePropertySources的同時(shí)調(diào)用replace會(huì)拋ConcurrentModificationException。這個(gè)坑我在第一次寫的時(shí)候踩過啟動(dòng)直接掛掉。SecretKeyLoader負(fù)責(zé)從環(huán)境變量或外部密鑰文件讀取主密鑰。這里要強(qiáng)調(diào)一點(diǎn)密鑰絕不能和密文放在同一個(gè)屬性源里。密文在啟動(dòng)參數(shù)、密鑰在環(huán)境變量這是最低要求再好一點(diǎn)是密鑰從掛載的 secret 文件讀只有特定用戶可讀。3.4 Spring Boot 3.x 的注冊(cè)差異與兼容寫法Spring Boot 2.x 的注冊(cè)文件是META-INF/spring.factoriesorg.springframework.boot.env.EnvironmentPostProcessor\ com.example.config.DecryptingEnvironmentPostProcessorSpring Boot 3.x 改成了META-INF/spring/org.springframework.boot.env.EnvironmentPostProcessor.imports內(nèi)容直接寫類名一行一個(gè)com.example.config.DecryptingEnvironmentPostProcessor如果項(xiàng)目要同時(shí)兼容 2.x 和 3.x兩個(gè)文件都放內(nèi)容各寫各的格式。Spring Boot 3 會(huì)優(yōu)先讀 imports 文件找不到再回退到spring.factories放兩份不會(huì)沖突。另外 3.x 對(duì)spring.factories的很多擴(kuò)展點(diǎn)都做了遷移如果你還依賴其他擴(kuò)展點(diǎn)建議一次性檢查一遍別只改了這一處。3.5 讓 Value、ConfigurationProperties、Environment 三條讀取路徑都走通包裝完之后要驗(yàn)證三條路徑是不是都拿到明文。Value走的是PropertySourcesPlaceholderConfigurer它讀的是Environment的propertySources包裝后的源直接生效沒問題。ConfigurationProperties走的是ConfigurationPropertySources這是一個(gè)在環(huán)境準(zhǔn)備末尾 attach 上去的視圖。因?yàn)樗?attach 時(shí)持有的是MutablePropertySources的引用遍歷是動(dòng)態(tài)的所以后包裝也生效。但要注意 attach 的時(shí)機(jī)在你的處理器之后——Ordered.LOWEST_PRECEDENCE恰好能保證這一點(diǎn)。environment.getProperty(key)直接遍歷propertySources同樣生效。有一個(gè)例外是PropertySource注解引入的屬性源。它的加載時(shí)機(jī)在ConfigurationClassPostProcessor階段晚于EnvironmentPostProcessor所以不會(huì)被包裝到。如果這個(gè)源里也有加密值需要單獨(dú)處理比如在BeanFactoryPostProcessor里再包一次或者干脆把加密值挪到application.yml里。4. 從加密一個(gè)值到項(xiàng)目跑起來的完整實(shí)操4.1 生成 256 位密鑰并加密目標(biāo)值密鑰生成用 KeyGenerator 就行別自己拼字節(jié)數(shù)組KeyGenerator generator KeyGenerator.getInstance(AES); generator.init(256, new SecureRandom()); SecretKey key generator.generateKey(); String base64Key Base64.getEncoder().encodeToString(key.getEncoded()); System.out.println(主密鑰: base64Key);256 位 AES 在 JDK 8u161 之后默認(rèn)就支持不需要額外裝策略文件。如果你的運(yùn)行環(huán)境是很老的 JDK 8 小版本跑的時(shí)候會(huì)拋InvalidKeyException: Illegal key size那就得升級(jí) JDK 或者裝無限強(qiáng)度策略文件。這個(gè)報(bào)錯(cuò)信息很明確一看就知道原因。拿到密鑰之后加密目標(biāo)值SecretKey key new SecretKeySpec(Base64.getDecoder().decode(base64Key), AES); String encrypted AesGcmCipher.encrypt(Pssw0rd-2024, key); System.out.println(encrypted);輸出大概長這樣enc:v1:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx長度 60 到 80 個(gè)字符之間具體取決于明文長度。4.2 啟動(dòng)腳本里注入系統(tǒng)屬性的幾種寫法Linux 下用-D傳參java -Dapp.secret.db-passwordenc:v1:xxxxx \ -Dspring.profiles.activeprod \ -jar demo.jar注意值里的特殊字符。雖然用了 URL 安全 Base64理論上只有字母數(shù)字和-_但前綴里有個(gè)冒號(hào)在 YAML 或某些腳本里冒號(hào)后面跟空格會(huì)被當(dāng)成分隔符。所以建議整個(gè)值用單引號(hào)包起來別圖省事。容器環(huán)境里更推薦用環(huán)境變量避免命令行參數(shù)被ps看到env: - name: APP_SECRET_DB_PASSWORD valueFrom: secretKeyRef: name: app-secret key: db-password環(huán)境變量名APP_SECRET_DB_PASSWORD會(huì)被 Spring Boot 的寬松綁定映射成app.secret.db-password所以你的代碼里照常寫Value(${app.secret.db-password})就行。這個(gè)映射規(guī)則是全大寫、下劃線轉(zhuǎn)點(diǎn)、點(diǎn)轉(zhuǎn)短橫線。搞清楚這條規(guī)則很多環(huán)境變量明明設(shè)了卻讀不到的問題就迎刃而解了。如果值里必須帶加密前綴環(huán)境變量這種方式反而更安全因?yàn)椴恍枰?jīng)過 shell 解析。4.3 寫個(gè)測(cè)試驗(yàn)證解密鏈路真的生效測(cè)試這塊有個(gè)坑SpringBootTest會(huì)緩存ApplicationContext如果第一個(gè)測(cè)試類啟動(dòng)時(shí)系統(tǒng)屬性還沒設(shè)后面再設(shè)也不會(huì)重新加載。所以要么用DirtiesContext要么在BeforeAll里設(shè)置并確保測(cè)試類順序。SpringBootTest DirtiesContext(classMode DirtiesContext.ClassMode.AFTER_CLASS) class SecretPropertyTest { static final String KEY 測(cè)試用密鑰的Base64; BeforeAll static void setUp() throws Exception { SecretKey key new SecretKeySpec(Base64.getDecoder().decode(KEY), AES); System.setProperty(app.secret.db-password, AesGcmCipher.encrypt(Pssw0rd-2024, key)); System.setProperty(APP_SECRET_KEY, KEY); } AfterAll static void tearDown() { System.clearProperty(app.secret.db-password); System.clearProperty(APP_SECRET_KEY); } Value(${app.secret.db-password}) String dbPassword; Autowired Environment environment; Test void 系統(tǒng)屬性應(yīng)被解密讀取() { assertThat(dbPassword).isEqualTo(Pssw0rd-2024); assertThat(environment.getProperty(app.secret.db-password)) .isEqualTo(Pssw0rd-2024); } }AfterAll里清理系統(tǒng)屬性這一步別省。系統(tǒng)屬性是 JVM 級(jí)別的測(cè)試跑完不清理會(huì)影響同一個(gè) JVM 里的其他測(cè)試類癥狀是單跑通過、全跑失敗特別難查。4.4 長度、性能與緩存的實(shí)際測(cè)算密文長度可以精確算出來。明文n字節(jié)GCM 加密后是n 16字節(jié)認(rèn)證標(biāo)簽加上 12 字節(jié) IV總共n 28字節(jié)。Base64 URL 無填充編碼后的長度是ceil((n 28) * 4 / 3)再減去填充再加上 7 個(gè)字符的前綴。拿一個(gè) 12 字符的口令舉例12 28 40字節(jié)Base64 后約 54 字符加前綴總共 61 字符。這個(gè)長度對(duì)啟動(dòng)參數(shù)和環(huán)境變量來說毫無壓力。性能方面AES-GCM 在現(xiàn)代 CPU 上有硬件加速指令單次加解密在微秒級(jí)。真正影響啟動(dòng)時(shí)間的是屬性被讀取的次數(shù)——一個(gè)中等規(guī)模的應(yīng)用啟動(dòng)時(shí)屬性讀取可能上萬次。所以緩存是必須的用ConcurrentHashMap以密文為 key 緩存明文命中率接近 100%。我實(shí)測(cè)過一個(gè)有 8 個(gè)加密屬性的項(xiàng)目加了緩存之后解密耗時(shí)從 40 毫秒降到 3 毫秒以內(nèi)。要提醒一句緩存里存的是明文內(nèi)存 dump 能看到。如果對(duì)內(nèi)存安全有極高要求可以考慮用char[]并在用完后清零但這會(huì)把代碼復(fù)雜度拉高不少一般業(yè)務(wù)系統(tǒng)不必做到這個(gè)程度。5. 踩坑實(shí)錄那些配置看著對(duì)但就是不生效的情況5.1 值被配置文件覆蓋的排查順序最常見的問題是系統(tǒng)屬性設(shè)了但讀出來還是配置文件里的值。排查順序我一般是這樣的第一步看 key 是否完全一致。系統(tǒng)屬性里的點(diǎn)號(hào)、短橫線、大小寫都有講究。app.secret.dbPassword和app.secret.db-password在寬松綁定下是同一個(gè)但在environment.getProperty里是兩個(gè)不同的 key。用Value時(shí)尤其容易搞混。第二步看屬性源順序有沒有被人為改過。有些項(xiàng)目啟動(dòng)時(shí)會(huì)調(diào)用environment.getPropertySources().addFirst(...)塞自定義源把系統(tǒng)屬性擠下去了。這種情況在引入了某些配置中心客戶端的項(xiàng)目里很常見。第三步看是不是加密前綴沒匹配上。比如你的密文是ENC(xxx)格式但處理器只認(rèn)enc:v1:那就原樣返回了原始字符串看著像沒解密。第四步看處理器有沒有真的被注冊(cè)。spring.factories里類名寫錯(cuò)一個(gè)字母就靜默不加載不報(bào)任何錯(cuò)?？梢栽谔幚砥骼锎蛞恍?info 日志啟動(dòng)時(shí)確認(rèn)一下。5.2 解密異常與亂碼的定位方法解密報(bào)錯(cuò)無非幾類。AEADBadTagException說明密鑰不對(duì)或者密文被改過這是 GCM 的認(rèn)證失敗屬于最明確的一類。IllegalBlockSizeException通常是密文被截?cái)啾热鐐鬏斶^程中丟了字符。IllegalArgumentException: Illegal base64 character說明 Base64 解碼失敗基本可以斷定是特殊字符被轉(zhuǎn)義了。亂碼問題多數(shù)出在編碼上。加密時(shí)用 UTF-8 取字節(jié)解密時(shí)也必須用 UTF-8 還原中間任何一步用了平臺(tái)默認(rèn)編碼都可能出問題。特別是在 Windows 上開發(fā)、Linux 上部署的場(chǎng)景默認(rèn)編碼不一樣很容易踩。還有一種隱蔽情況屬性值本身就是空字符串。System.setProperty(key, )設(shè)進(jìn)去之后environment.getProperty返回的是空串而不是 null某些框架會(huì)把空串當(dāng)成未配置處理走了默認(rèn)值分支。如果加密后的值恰好解出空串行為會(huì)很怪。建議在解密之后加一句判空把空串轉(zhuǎn)成 null 或者直接拋異常。5.3 常見問題速查表現(xiàn)象可能原因處理方式讀到的是密文原文處理器未注冊(cè)或 order 太靠前檢查注冊(cè)文件order 設(shè) LOWEST_PRECEDENCE讀到的是配置文件的值屬性源被 addFirst 覆蓋檢查是否有自定義源插到最前面啟動(dòng)報(bào) InvalidKeyExceptionJDK 版本低不支持 256 位升級(jí) JDK 或裝無限強(qiáng)度策略報(bào) AEADBadTagException密鑰不匹配或密文損壞核對(duì)密鑰版本檢查傳輸過程報(bào) Illegal base64 character密文中特殊字符被轉(zhuǎn)義改用 URL 安全 Base64ConfigurationProperties 綁不上包裝時(shí)丟了 Enumerable包裝類繼承 EnumerablePropertySource測(cè)試單跑通過全跑失敗系統(tǒng)屬性污染AfterAll 里清理系統(tǒng)屬性環(huán)境變量設(shè)了但讀不到命名映射規(guī)則不匹配全大寫、下劃線分詞5.4 密鑰管理和日志里的安全紅線有幾個(gè)紅線是必須守住的。密鑰不能出現(xiàn)在代碼倉庫里包括測(cè)試代碼。測(cè)試用的密鑰要單獨(dú)生成只用于測(cè)試環(huán)境而且要明確標(biāo)注僅測(cè)試使用。密鑰不能和密文在同一個(gè)屬性源。如果兩部分都在application.yml里那加密等于沒做任何一個(gè)能看配置文件的人都能解密。日志里不能打印解密后的值。很多框架在 debug 級(jí)別會(huì)打印屬性綁定的過程如果你的屬性名比較敏感比如帶password要確認(rèn)這些日志不會(huì)上線。異常堆棧里不能帶明文。Cipher.doFinal拋異常時(shí)不會(huì)帶明文但如果你自己包裝異常時(shí)把原值拼進(jìn) message那就漏了。前面給的SecretResolver里我只帶了密鑰版本就是這個(gè)考慮。還有一點(diǎn)容易被忽略actuator 的/env和/configprops端點(diǎn)默認(rèn)會(huì)做脫敏脫敏規(guī)則是匹配password、secret、key、token這類關(guān)鍵詞。如果你的屬性名叫app.datasource.credential不在這份名單里就會(huì)被原樣展示。這個(gè)名單可以自定義但更穩(wěn)妥的做法是直接限制這些端點(diǎn)的訪問權(quán)限。6. 上線前的加固清單6.1 actuator 端點(diǎn)的脫敏處理Spring Boot 的脫敏靠SanitizingFunction實(shí)現(xiàn)2.6 之后可以自定義。默認(rèn)規(guī)則只覆蓋常見關(guān)鍵詞業(yè)務(wù)自定義的屬性名很容易漏。Bean public SanitizingFunction customSanitizer() { return property - { String name property.getName().toLowerCase(); if (name.contains(credential) || name.contains(passwd) || name.contains(private)) { return property.withValue(******); } return property; }; }這段代碼注冊(cè)到容器后/env端點(diǎn)里匹配到的值都會(huì)顯示成星號(hào)。注意這只是展示層面的保護(hù)屬性值在內(nèi)存里仍然是明文別把它當(dāng)成加密手段。更徹底的做法是把 actuator 端點(diǎn)限制在內(nèi)網(wǎng)訪問或者干脆在生產(chǎn)環(huán)境只暴露health和info。配置項(xiàng)management.endpoints.web.exposure.include設(shè)成health,info就夠用了。6.2 密鑰輪換與多版本密鑰的共存設(shè)計(jì)密鑰輪換是安全實(shí)踐里的常規(guī)操作但在配置加密這個(gè)場(chǎng)景下很容易做砸。核心思路是解密時(shí)支持多個(gè)版本加密時(shí)只用最新版本。前面給的enc:v1:前綴就是為此設(shè)計(jì)的。輪換時(shí)先生成 v2 密鑰把SecretResolver的 keys 映射表里同時(shí)放 v1 和 v2重新加密所有敏感值并替換成enc:v2:前綴確認(rèn)沒有 v1 的密文殘留之后再把 v1 從映射表里移除。這個(gè)過程可以分多次發(fā)布完成不需要一次性切換。第一版發(fā)布只加 v2 密鑰的支持密文還是 v1第二版發(fā)布把密文換成 v2第三版發(fā)布移除 v1 密鑰。每次發(fā)布都可回滾風(fēng)險(xiǎn)可控。要注意的是如果密鑰來自外部服務(wù)輪換時(shí)要考慮服務(wù)的可用性。密鑰服務(wù)掛了會(huì)導(dǎo)致應(yīng)用完全起不來所以本地最好有一份降級(jí)密鑰或者把密鑰緩存到本地文件。6.3 測(cè)試環(huán)境與生產(chǎn)環(huán)境的隔離測(cè)試環(huán)境的密鑰和生產(chǎn)環(huán)境必須完全不同這是基本要求。但實(shí)際項(xiàng)目里經(jīng)常出現(xiàn)測(cè)試密鑰硬編碼在代碼里、生產(chǎn)環(huán)境復(fù)用的情況。我的做法是把密鑰來源做成可配置的通過app.secret.key-source指定可選值是env、file、vault。測(cè)試環(huán)境用env配合 CI 的變量注入生產(chǎn)環(huán)境用file掛載只讀的密鑰文件。這樣同一份代碼在不同環(huán)境走不同路徑不需要改代碼。同時(shí)要在啟動(dòng)時(shí)加一條校驗(yàn)如果檢測(cè)到當(dāng)前是生產(chǎn) Profile 但密鑰來源是env且密鑰長度不足直接啟動(dòng)失敗。寧可起不來也別帶著弱密鑰跑起來。另外測(cè)試環(huán)境的數(shù)據(jù)最好也是脫敏的。有些團(tuán)隊(duì)為了圖省事把生產(chǎn)數(shù)據(jù)導(dǎo)到測(cè)試庫密碼還是同一套這種時(shí)候加密配置就形同虛設(shè)了。我個(gè)人在實(shí)際操作中的體會(huì)是配置加密這件事真正的難點(diǎn)不在算法而在讓所有人都按同一套規(guī)則來。代碼里寫得再完善運(yùn)維在啟動(dòng)腳本里直接寫明文整條鏈路就破了。所以落地的時(shí)候除了技術(shù)方案最好再配一條啟動(dòng)校驗(yàn)檢測(cè)到關(guān)鍵屬性沒有加密前綴時(shí)打一條 WARN 日志慢慢把習(xí)慣糾正過來。踩過幾次坑之后我發(fā)現(xiàn)日志比文檔管用得多。