mkcert

mkcert 는 개발용 로컬 CA를 만들고, 시스템에서 신뢰되는 TLS 인증서를 빠르게 발급하는 도구다.

mkcert -install
mkcert localhost 127.0.0.1 ::1
mkcert example.com "*.example.com" example.test localhost 127.0.0.1 ::1

• mkcert [<flags>…] NAME…
• mkcert -install: 로컬 CA를 system trust store에 설치
• mkcert -uninstall: trust store에서 로컬 CA 제거. CA 파일 자체는 남는다
• mkcert -CAROOT: 현재 CA 저장 경로 출력

• 공개 CA를 쓰기 어려운 localhost, 사설 개발 도메인, 내부 테스트 도메인에 적합하다.
• 먼저 mkcert -install 로 로컬 루트 CA를 trust store에 넣고, 이후 호스트 이름 목록으로 인증서를 발급한다.
• 기본 출력은 PEM 인증서와 개인키다. 이름이 여러 개면 첫 번째 이름 기준 파일명에 +N suffix가 붙는다.

• -install: 로컬 CA 생성 후 system, NSS/Firefox, Java trust store 설치를 시도
• -uninstall: trust store에서 mkcert CA 제거
• -cert-file FILE: 생성할 인증서 출력 경로 지정
• -key-file FILE: 생성할 개인키 출력 경로 지정
• -p12-file FILE: -pkcs12 사용 시 PKCS#12 파일 경로 지정
• -pkcs12: .p12/.pfx 번들 생성
• -ecdsa: ECDSA 키로 인증서 생성
• -client: client authentication 용 인증서 생성
• -csr CSR: CSR 기반으로 인증서 생성. 다른 발급 플래그와 충돌 가능
• -CAROOT: CA 저장 디렉터리 출력
• -help: 기본/고급 사용법 출력
• -version: 버전 출력

# 1회 초기화: 로컬 CA 생성 및 trust store 설치
mkcert -install  #(관리자권한)
 
# localhost 개발 인증서 발급
mkcert localhost 127.0.0.1 ::1
 
# wildcard 포함 다중 SAN 인증서 발급
mkcert example.com "*.example.com" example.test localhost 127.0.0.1 ::1
 
# 출력 파일명 고정
mkcert -cert-file cert.pem -key-file key.pem dev.local "*.dev.local"
 
# PKCS#12 번들 생성
mkcert -pkcs12 -p12-file local-dev.p12 localhost
 
# client certificate 생성
mkcert -client dev-client@example.test

# CA 저장 위치 확인
mkcert -CAROOT
 
# 별도 CA 디렉터리 사용
export CAROOT="$HOME/.local/share/mkcert-team-a"
mkcert -install
 
# trust store 대상을 제한
export TRUST_STORES=system,nss
mkcert -install

• CAROOT: 기본 CA 저장 위치를 바꿔 여러 로컬 CA를 병행 관리할 때 사용
• TRUST_STORES: system, java, nss 조합으로 설치 대상을 제한
• Node.js 는 system root store를 자동 사용하지 않으므로 필요하면 NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem" 를 설정한다

• Firefox 신뢰가 자동 설치되지 않으면 certutil 또는 libnss3-tools 설치 여부를 확인한다.
• Linux에서 system trust 설치가 안 되면 배포판별 update-ca-certificates, update-ca-trust, trust 도구 지원 여부를 본다.
• 권한 문제로 -install 이 실패하면 sudo 가능 여부 또는 관리자 권한 실행 여부를 확인한다.
• Node.js, Java, 컨테이너 런타임은 system trust store를 바로 따르지 않을 수 있으므로 별도 CA 경로 설정이 필요할 수 있다.
• 모바일 기기에서 신뢰하려면 $(mkcert -CAROOT)/rootCA.pem 을 기기에 설치해야 한다.

• 지원 대상 trust store는 system, NSS/Firefox, Java 이다.
• 호스트 이름 외에 IP, email, URL 이름도 인자로 받을 수 있다.
• 서버 설정은 자동으로 바꾸지 않으므로, 생성된 인증서와 키를 nginx, Caddy, 개발 서버, 프레임워크에 직접 연결해야 한다.

• 운영 환경용 공개 인증서 발급 도구가 아니다. production TLS에는 certbot 같은 ACME 기반 도구가 더 적합하다.
• 자체 서명 leaf certificate를 직접 배포하는 방식보다 로컬 개발 CA를 관리하는 쪽이 브라우저 경고를 줄이기 쉽다.

mkcert -help

Usage of mkcert:
 
	$ mkcert -install
	Install the local CA in the system trust store.
 
	$ mkcert example.org
	Generate "example.org.pem" and "example.org-key.pem".
 
	$ mkcert example.com myapp.dev localhost 127.0.0.1 ::1
	Generate "example.com+4.pem" and "example.com+4-key.pem".
 
	$ mkcert "*.example.it"
	Generate "_wildcard.example.it.pem" and "_wildcard.example.it-key.pem".
 
	$ mkcert -uninstall
	Uninstall the local CA (but do not delete it).
 
Advanced options:
 
	-cert-file FILE, -key-file FILE, -p12-file FILE
	    Customize the output paths.
 
	-client
	    Generate a certificate for client authentication.
 
	-ecdsa
	    Generate a certificate with an ECDSA key.
 
	-pkcs12
	    Generate a ".p12" PKCS #12 file, also know as a ".pfx" file,
	    containing certificate and key for legacy applications.
 
	-csr CSR
	    Generate a certificate based on the supplied CSR. Conflicts with
	    all other flags and arguments except -install and -cert-file.
 
	-CAROOT
	    Print the CA certificate and key storage location.
 
	$CAROOT (environment variable)
	    Set the CA certificate and key storage location. (This allows
	    maintaining multiple local CAs in parallel.)
 
	$TRUST_STORES (environment variable)
	    A comma-separated list of trust stores to install the local
	    root CA into. Options are: "system", "java" and "nss" (includes
	    Firefox). Autodetected by default.

• openssl
• certbot
• installation

• codex:: 2026-07-15 Created mkcert reference page with local CA workflow, trust-store variables, and safety notes.