step CLI

step은 인증서, key, JWT/JWK, OAuth/OIDC 및 Smallstep CA를 다루는 범용 CLI다. step-ca 서버의 초기화와 클라이언트 등록, X.509/SSH 인증서 발급·갱신 작업에는 step ca와 step ssh 명령군을 사용한다.

• 인증서 생성, 조회, 검증과 key/JWT 처리는 step certificate, step crypto 명령군을 사용한다.
• step-ca 초기화와 CA 접속 설정, 인증서 발급·갱신은 step ca 명령군을 사용한다.
• 기본 작업 디렉터리는 $(step path)로 확인하며, STEPPATH 또는 context에 따라 달라질 수 있다.
• 새로운 클라이언트는 신뢰할 수 있는 경로로 받은 root fingerprint를 사용해 bootstrap해야 한다.

brew install step
step version

Homebrew의 step formula는 step CLI와 step-ca를 함께 설치할 수 있다. 설치 결과는 각각의 version 명령으로 확인한다.

sudo apt-get update
sudo apt-get install -y --no-install-recommends curl gpg ca-certificates
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://packages.smallstep.com/keys/apt/repo-signing-key.gpg \
  | sudo tee /etc/apt/keyrings/smallstep.asc >/dev/null
 
sudo tee /etc/apt/sources.list.d/smallstep.sources >/dev/null <<'EOF'
Types: deb
URIs: https://packages.smallstep.com/stable/debian
Suites: debs
Components: main
Signed-By: /etc/apt/keyrings/smallstep.asc
EOF
 
sudo apt-get update
sudo apt-get install step-cli

CA 서버도 이 호스트에서 운영할 때만 step-ca package를 추가한다.

sudo apt-get install step-ca

RHEL, CentOS Stream, Rocky Linux, AlmaLinux 등 Enterprise Linux 계열에서는 Smallstep EL repository를 추가한 뒤 step-cli package를 설치한다.

cat <<'EOF' | sudo tee /etc/yum.repos.d/smallstep.repo >/dev/null
[smallstep]
name=Smallstep
baseurl=https://packages.smallstep.com/stable/el/
enabled=1
repo_gpgcheck=0
gpgcheck=1
gpgkey=https://packages.smallstep.com/keys/smallstep-0x889B19391F774443.gpg
EOF
 
sudo dnf makecache
sudo dnf install -y step-cli
step version

Fedora에서는 Smallstep Fedora repository를 사용한다.

cat <<'EOF' | sudo tee /etc/yum.repos.d/smallstep.repo >/dev/null
[smallstep]
name=Smallstep
baseurl=https://packages.smallstep.com/stable/fedora/
enabled=1
repo_gpgcheck=0
gpgcheck=1
gpgkey=https://packages.smallstep.com/keys/smallstep-0x889B19391F774443.gpg
EOF
 
sudo dnf makecache
sudo dnf install -y step-cli
step version

RHEL 계열 또는 Fedora에서 CA 서버도 운영할 때만 step-ca package를 추가한다.

sudo dnf install -y step-ca
step-ca version

winget install Smallstep.step
step version

step <command> [arguments] [global-flags] [command-flags]
step ca <subcommand> [arguments] [global-flags] [subcommand-flags]

• step COMMAND [FLAGS] ARGS
• step ca SUBCOMMAND [FLAGS] ARGS

• ca: Smallstep CA 초기화, bootstrap, 인증서 발급·갱신·폐기 및 provisioner 관리.
• certificate: X.509 인증서와 CSR 생성, 조회, fingerprint, 검증 및 trust store 설치.
• crypto: key, hash, JWK/JWT, random value 등 암호화 관련 유틸리티.
• ssh: step-ca를 이용한 SSH 인증서 발급, login 및 host key 관리.
• oauth: OAuth/OIDC 인증 흐름에서 token 획득.
• context: 여러 CA 또는 환경의 step 설정을 분리하고 전환.
• base64, path, version: 인코딩, 작업 경로 및 버전 확인 유틸리티.

# 대화형 CA 설정 생성
step ca init
 
# 생성된 기본 설정 경로 확인
step path
 
# CA 서버 실행
step-ca "$(step path)/config/ca.json"

• step ca init [–ssh] [–acme]: CA 인증서, key와 ca.json 구성을 생성한다.
• step-ca CA_CONFIG: 지정한 ca.json으로 CA 서버를 시작한다.

CA 관리자가 별도 신뢰 경로로 전달한 CA URL과 root fingerprint를 사용한다. CA 서버가 제시한 값을 검증 없이 그대로 신뢰하지 않는다.

step ca bootstrap \
  --ca-url https://ca.example.internal:8443 \
  --fingerprint SHA256_ROOT_FINGERPRINT

• root 인증서는 기본적으로 $(step path)/certs/root_ca.crt에 저장된다.
• CA URL, fingerprint, root 경로는 $(step path)/config/defaults.json에 기록된다.
• bootstrap 후 같은 context에서는 많은 step ca 명령에서 –ca-url과 –root를 생략할 수 있다.

# leaf certificate와 private key 발급
step ca certificate service.example.internal service.crt service.key
 
# 기존 certificate 갱신
step ca renew service.crt service.key
 
# certificate 내용 확인
step certificate inspect service.crt
 
# CA root를 기준으로 검증
step certificate verify service.crt --roots "$(step path)/certs/root_ca.crt"

step certificate inspect https://example.com

step certificate create dev.example.internal dev.crt dev.key \
  --profile self-signed \
  --subtle

step certificate fingerprint /secure/path/root_ca.crt

• step path: 현재 context의 STEPPATH를 출력한다.
• STEPPATH: 기본 ~/.step 대신 사용할 작업 디렉터리를 지정한다.
• $(step path)/config/defaults.json: 기본 CA URL, root certificate와 fingerprint를 저장한다.
• $(step path)/config/ca.json: 로컬 step-ca 서버 구성 파일의 일반적인 위치다.
• step context list: 사용 가능한 context를 조회한다.
• step context current: 현재 context를 확인한다.

• x509: certificate signed by unknown authority: bootstrap 상태와 defaults.json의 root 경로를 확인하고, 신뢰할 수 있는 fingerprint로 다시 검증한다.
• CA 접속 실패: –ca-url의 scheme, port, DNS, 방화벽과 서버의 dnsNames 설정을 확인한다.
• certificate 발급 거부: subject/SAN이 provisioner와 authority policy에 허용되는지 확인한다.
• 갱신 실패: certificate 만료 상태, private key 일치 여부, CA 접근성 및 provisioner 정책을 확인한다.
• 설정이 예상과 다름: step path, step context current, STEPPATH 값을 함께 확인한다.

• package 이름은 플랫폼에 따라 step, step-cli 또는 Smallstep.step이지만 기본 실행 파일 이름은 step이다.
• step과 step-ca의 feature 및 option은 release에 따라 달라질 수 있으므로 자동화 전 step version, step-ca version과 각 subcommand의 –help를 기록한다.
• step은 step-ca 전용 명령만 제공하는 도구가 아니며, 일부 certificate와 crypto 작업은 CA 서버 없이도 사용할 수 있다.

step --help

이 환경에는 step 실행 파일이 없어 실제 help 출력을 수록하지 않았다.
설치한 버전의 출력은 다음 명령으로 확인한다.
 
step --help

step ca --help

이 환경에는 step 실행 파일이 없어 실제 help 출력을 수록하지 않았다.
설치한 버전의 출력은 다음 명령으로 확인한다.
 
step ca --help

• openssl
• mkcert
• Smallstep: step CLI
• Smallstep: step ca reference
• Smallstep: step-ca server

• codex:: 2026-07-19 Split the RPM repository guidance into Enterprise Linux and Fedora endpoints while preserving the Hostinger-side RHEL update.
• codex:: 2026-07-19 Added RHEL and Fedora RPM repository installation instructions for step-cli and optional step-ca.
• codex:: 2026-07-19 Created step CLI reference with step-ca bootstrap, certificate lifecycle, installation, security, and troubleshooting guidance.