워드프레스 7.2 Secrets API 직접 써 보니: API 키 암호화와 꼭 챙길 설정
워드프레스 7.2에 들어가는 Secrets API는 플러그인이 API 키 같은 비밀 값을 암호화해 저장하는 기능이고, 실제로 돌려 보니 데이터베이스에 평문이 전혀 남지 않았습니다. 다만 wp-config.php의 WP_SECRETS_KEY가 샘플 자리표시자 그대로면 저장 자체가 모두 막혔습니다. 7.2로 업데이트하는 운영자가 꼭 챙겨야 할 부분이 바로 이 키입니다. 이 글의 결과는 마케팅테이블이 7.2 베타를 테스트 환경에 직접 띄워 실행한 기록입니다.
목차
테스트 환경
| 항목 | 내용 |
|---|---|
| 측정일 | 2026년 11월 12일 |
| 워드프레스 | 7.2-beta5 (2026년 11월 10일 공개된 베타) |
| 실행 방식 | 워드프레스 공식 도구 WordPress Playground CLI로 PC에 임시 사이트를 띄움 |
| PHP | 8.3.36 (sodium 확장 없이 워드프레스 내장 sodium_compat 사용) |
| 테스트 방법 | Secrets API 함수를 호출하는 PHP 파일을 사이트에 넣고 결과를 JSON으로 기록 |
Secrets API의 설계와 함수 목록은 워드프레스 코어 팀의 The Secrets API in WordPress 7.2 개발 노트에 정리되어 있습니다. 이 글은 그 내용이 실제로 어떻게 동작하는지 확인한 기록입니다. 베타 버전이라 정식 출시 때 바뀔 수 있습니다.
Secrets API가 왜 필요한가
지금까지 많은 플러그인은 외부 서비스의 API 키, 결제 연동 키, 메일 발송 비밀번호를 옵션 테이블에 평문으로 저장해 왔습니다. 데이터베이스 백업 파일이 유출되거나, 다른 플러그인의 취약점으로 옵션이 읽히면 키가 그대로 드러나는 구조입니다. Secrets API는 이 값들을 암호화해 저장하고, 필요할 때만 꺼내 쓰게 하는 표준 방법을 워드프레스 코어에 넣은 것입니다.
외부 자동화 도구로 사이트에 접속할 때 쓰는 비밀번호도 같은 문제를 안고 있습니다. 자동화용 계정은 애플리케이션 비밀번호처럼 용도별로 나누고, 플러그인이 보관하는 키는 앞으로 Secrets API로 암호화하는 흐름이 될 가능성이 큽니다.
테스트 1: 기본 설정에서는 저장이 전부 막혔다
Playground로 막 설치한 7.2-beta5 사이트에서 wp_set_secret()을 호출하자 secret_key_unavailable 오류가 나며 저장되지 않았습니다. 오류 메시지는 “WP_SECRETS_KEY가 정의되어 있지만 사용할 수 없다”는 내용이었습니다.

원인을 확인해 보니 이 테스트 환경의 wp-config.php에는 WP_SECRETS_KEY를 포함한 모든 인증 키와 솔트가 샘플 파일의 자리표시자 문구(27자) 그대로 들어가 있었습니다. 개발 노트에도 자리표시자 값, 빈 값, 인증 키·솔트를 복사한 값은 유효하지 않다고 되어 있는데, 실제로 그 규칙대로 차단된 것입니다. wp_is_secrets_api_available()도 false를 돌려줬습니다.
이 결과는 실제 사이트에도 그대로 적용됩니다. 키를 제대로 설정하지 않은 사이트에서는 Secrets API를 쓰는 플러그인이 값을 저장하지 못합니다. 개발 노트에 따르면 새로 설치하는 사이트는 설치 과정에서 키가 자동으로 만들어지고, 기존 사이트는 사이트 상태(Site Health) 화면이 만들어 주는 한 줄을 wp-config.php에 추가하면 됩니다.
테스트 2: 올바른 키를 넣으면 이렇게 동작했다
무작위 64자 키를 WP_SECRETS_KEY로 넣고 같은 테스트를 다시 돌렸습니다.

| 확인 항목 | 결과 |
|---|---|
| API 사용 가능 여부 | true |
저장 (wp_set_secret) |
성공, 62ms |
조회 (wp_get_secret) |
WP_Secret 객체 반환, 6ms |
reveal() 값 |
저장한 값과 일치 |
| 옵션 테이블에서 평문 검색 | 0건 |
| 저장된 레코드 | _wp_secrets_root_key(96자), _wp_secret_mkt-lab/api-key(419자), 둘 다 autoload 꺼짐 |
| 값 교체 후 조회 | 새 값으로 바뀜 |
| 삭제 후 조회 | null |
처리 시간은 PC 위에서 PHP를 웹어셈블리로 돌리는 Playground 환경에서 잰 값이라, 실제 서버에서는 달라질 수 있습니다. 다만 한 번 저장하고 읽는 데 수십 밀리초 수준이라 일반적인 사용에서 부담이 될 정도는 아니었습니다.
테스트 3: 실수로 출력해도 값이 새지 않았다
개발자가 디버깅하다가 비밀 값을 화면이나 로그에 찍어 버리는 실수는 흔합니다. 그래서 wp_get_secret()이 돌려준 객체를 print_r, JSON 변환, var_export로 각각 출력해 봤습니다. 세 경우 모두 결과에 실제 값이 들어 있지 않았습니다. 값을 꺼내는 방법은 reveal() 하나뿐이었습니다. 로그에 객체를 통째로 남기는 실수를 해도 키가 노출되지 않는 설계입니다.
wp_list_secrets()도 이름, 지문(fingerprint), 생성 시각, 이전 값 보관 여부, 교체 필요 여부만 돌려주고 값은 포함하지 않았습니다.
테스트 4: 이름 규칙
| 시도한 이름 | 결과 |
|---|---|
ok-name/ok_secret |
저장됨 |
noslash (슬래시 없음) |
저장됨 (개발 노트상 경고 대상) |
Upper/Case (대문자) |
secret_invalid_name |
a/b/c (슬래시 2개) |
secret_invalid_name |
-lead/x (하이픈으로 시작) |
secret_invalid_name |
개발 노트의 권장 형식은 플러그인-슬러그/시크릿-이름입니다. 슬래시가 없는 이름도 저장은 되지만 개발 노트에서는 경고를 띄우는 방식이라고 설명하므로, 플러그인을 만든다면 권장 형식을 따르는 것이 안전합니다.
운영자가 7.2 업데이트 때 챙길 것
- 업데이트 후 사이트 상태 확인: 개발 노트에 따르면 보안 항목에 키 문제, 복호화할 수 없는 시크릿, 교체 대기 중인 자격 증명을 점검하는 테스트가 추가됩니다.
- WP_SECRETS_KEY 추가: 기존 사이트라면 사이트 상태가 안내하는 줄을 wp-config.php에 넣습니다. 도커 기반 패널에서는 wp-config.php 위치가 일반 호스팅과 다를 수 있으니 이지패널 설치 가이드처럼 파일 위치를 먼저 확인하세요.
- 키 백업: 이 키를 잃어버리거나 바꾸면 저장된 시크릿을 모두 읽을 수 없게 됩니다. 비밀번호 관리자 등에 따로 보관합니다.
- 솔트처럼 바꾸지 않기: 보안 점검 때 인증 키와 솔트를 일괄 교체하는 습관이 있다면,
WP_SECRETS_KEY는 그 대상에서 빼야 합니다. - 서버 이전 시 함께 옮기기: 데이터베이스만 옮기고 wp-config.php의 키를 새로 만들면 시크릿이 전부 깨집니다.

자주 묻는 질문
지금 쓰는 플러그인의 API 키도 자동으로 암호화되나요?
아닙니다. 플러그인이 Secrets API를 쓰도록 바뀌어야 합니다. 개발 노트에는 기존 옵션 값을 시크릿으로 옮기는 함수도 소개되어 있지만, 적용 여부는 각 플러그인 개발자가 정합니다.
sodium 확장이 없는 서버에서도 쓸 수 있나요?
이번 테스트 환경에는 sodium 확장이 없었지만 워드프레스에 들어 있는 호환 라이브러리로 암호화가 동작했습니다. 다만 실제 서버에서는 확장이 설치되어 있는 편이 성능상 유리합니다.
정식 7.2에서도 결과가 같을까요?
이번 결과는 베타 5 기준입니다. 개발 노트에도 베타 중 바뀐 부분이 안내되어 있어, 정식 출시 후 다시 확인해 업데이트하겠습니다.


