인증서 도구
이 도구들은 Alpacon 내장 PKI를 관리합니다: 인증서를 서명하는 인증 기관(CA), 인증서를 요청하는 인증서 서명 요청(CSR), 발급된 인증서, 그리고 인증서를 무효화하는 폐기 요청입니다. “alpacax.com용 CA를 만들어줘”, “web-01.internal용 인증서를 요청해줘”, “곧 만료되는 인증서를 폐기해줘” 같은 요청을 처리합니다.
일반적인 생명주기는 다음과 같습니다. create_certificate_authority로 도메인당 한 번 CA를 만들고, create_sign_request로 인증서를 요청합니다. 이때 CA는 요청된 도메인이나 IP를 기준으로 자동 매칭됩니다. 관리자나 CA 소유자가 approve_sign_request로 요청을 승인하면 CA가 인증서를 발급합니다. 인증서를 조기에 무효화해야 한다면 revoke_certificate가 폐기 요청을 시작하며, 호출자가 CA 소유자나 관리자인 경우 자동 승인되고 그렇지 않으면 승인을 기다립니다.
모든 도구는 workspace(필수)와 region(선택, 미지정 시 설정된 리전 사용)을 받습니다. 아래 표에서는 이 공통 파라미터를 생략합니다.
요약
| 도구 | 설명 | 접근 수준 |
|---|---|---|
list_certificate_authorities | 인증 기관 목록 조회 | 읽기 전용 |
create_certificate_authority | 인증 기관 생성 | 추가적 |
get_certificate_authority | 인증 기관 상세 정보 조회 | 읽기 전용 |
update_certificate_authority | 인증 기관의 유효 기간이나 소유자 업데이트 | 멱등적 쓰기 |
delete_certificate_authority | 인증 기관 영구 삭제 | 파괴적 |
list_sign_requests | 인증서 서명 요청 목록 조회 | 읽기 전용 |
create_sign_request | 인증서 서명 요청 생성 | 추가적 |
get_sign_request | 인증서 서명 요청 상세 정보 조회 | 읽기 전용 |
delete_sign_request | 대기 중인 인증서 서명 요청 취소 | 파괴적 |
approve_sign_request | 대기 중인 CSR을 승인해 CA가 인증서를 발급하도록 함 | 추가적 |
deny_sign_request | 인증서 서명 요청 거부 | 파괴적 |
retry_sign_request | signing 상태에 멈춘 CSR 재시도 | 멱등적 쓰기 |
list_certificates | 발급된 인증서 목록 조회 | 읽기 전용 |
get_certificate | 인증서 상세 정보 조회 | 읽기 전용 |
revoke_certificate | 인증서에 대한 폐기 요청 생성 | 파괴적 |
list_revoke_requests | 인증서 폐기 요청 목록 조회 | 읽기 전용 |
get_revoke_request | 폐기 요청 상세 정보 조회 | 읽기 전용 |
approve_revoke_request | 대기 중인 폐기 요청 승인 | 파괴적 |
deny_revoke_request | 대기 중인 폐기 요청 거부 | 파괴적 |
retry_revoke_request | revoking 상태에 멈춘 폐기 요청 재시도 | 멱등적 쓰기 |
cancel_revoke_request | 대기 중인 폐기 요청 취소 | 파괴적 |
인증 기관
인증 기관(CA)은 도메인의 인증서를 서명하는 신뢰의 뿌리입니다. 각 CA는 서버(에이전트)에서 호스팅되며 사용자가 소유합니다. CLI 대응 명령어: alpacon authority.
list_certificate_authorities
워크스페이스에 설정된 인증 기관 목록을 조회합니다. CA 이름, 도메인, 유효 기간, 키 알고리즘/크기를 반환합니다. 서명 요청을 만들기 전에 사용 가능한 CA를 확인할 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
page | integer | 아니요 | 페이지네이션 페이지 번호 |
page_size | integer | 아니요 | 페이지당 항목 수 |
예시
“우리가 설정해 둔 인증 기관이 뭐가 있어?”
에이전트가 list_certificate_authorities를 호출해 각 CA의 이름, 도메인, 유효 기간 설정을 알려줍니다.
create_certificate_authority
워크스페이스 내에서 인증서를 서명할 새 CA를 생성합니다. 이름, 루트 도메인, 조직, CA를 호스팅할 서버(에이전트), 소유자 사용자가 필요합니다. 유효 기간, 키 알고리즘(rsa 또는 ecdsa), 키 크기(RSA는 2048/4096, ECDSA는 256/384), CA를 에이전트에 자동 설치할지 여부를 선택적으로 지정할 수 있습니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | string | 예 | 인증 기관 이름 |
domain | string | 예 | CA의 루트 도메인. 고유해야 함 |
organization | string | 예 | 이 CA가 속한 조직명 |
server_id | string | 예 | 이 CA를 실행하는 서버(에이전트) UUID |
owner | string | 예 | 소유자 사용자 UUID |
root_valid_days | integer | 아니요 | 루트 인증서 유효 기간(일) |
default_valid_days | integer | 아니요 | 하위 인증서의 기본 유효 기간(일) |
max_valid_days | integer | 아니요 | 사용자가 요청 가능한 최대 유효 기간(일) |
key_algorithm | string | 아니요 | 키 알고리즘: rsa 또는 ecdsa |
key_size | integer | 아니요 | 키 크기(비트): RSA는 2048/4096, ECDSA는 256/384 |
install | boolean | 아니요 | CA를 에이전트에 자동 설치 |
예시
“alpacax.com용 인증 기관을 ca-server 에이전트에 만들어줘”
에이전트가 domain="alpacax.com", 해결된 server_id, 요청자를 owner로 지정해 create_certificate_authority를 호출합니다.
get_certificate_authority
특정 CA의 상세 정보를 ID로 조회합니다: 설정, 유효 기간, 키 알고리즘/크기, 상태. CA ID는 list_certificate_authorities로 확인합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
ca_id | string | 예 | 인증 기관 ID |
예시
“alpacax.com CA의 상세 정보를 보여줘”
에이전트가 list_certificate_authorities로 CA ID를 찾은 뒤 get_certificate_authority를 호출해 전체 설정을 반환합니다.
update_certificate_authority
기존 CA를 업데이트합니다. 부분 업데이트이므로 제공된 필드만 변경됩니다. default_valid_days, max_valid_days, owner는 수정 가능하지만 CA의 이름, 도메인, 호스팅 서버, 키 파라미터는 생성 후 변경할 수 없습니다. 관리자 또는 CA 소유자 권한이 필요합니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
ca_id | string | 예 | 인증 기관 ID |
default_valid_days | integer | 아니요 | 하위 인증서의 새 기본 유효 기간(일) |
max_valid_days | integer | 아니요 | 사용자가 요청 가능한 새 최대 유효 기간(일) |
owner | string | 아니요 | 새 소유자 사용자 UUID |
예시
“alpacax.com CA의 최대 인증서 유효 기간을 90일로 낮춰줘”
에이전트가 ca_id와 max_valid_days=90으로 update_certificate_authority를 호출합니다. 나머지 CA 설정은 그대로 유지됩니다.
delete_certificate_authority
CA를 영구 삭제합니다. 되돌릴 수 없으며, 이 CA가 발급한 모든 인증서는 더 이상 검증할 수 없게 됩니다. 관리자 또는 CA 소유자 권한이 필요합니다.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
ca_id | string | 예 | 삭제할 인증 기관 ID |
예시
“이제 안 쓰는 옛날 스테이징 CA를 삭제해줘”
되돌릴 수 없는 작업이므로 에이전트가 delete_certificate_authority를 호출하기 전에 사용자에게 CA ID를 확인합니다.
인증서 서명 요청(CSR)
인증서 서명 요청(CSR)은 CA에 인증서 발급을 요청합니다. CSR은 requested, signing, signed, failed, canceled, denied 상태를 거칩니다. CLI 대응 명령어: alpacon csr.
list_sign_requests
워크스페이스의 CSR 목록을 조회합니다. 상태, 커먼 네임, 관련 CA를 포함합니다. 대기 중인 인증서 요청을 검토할 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
page | integer | 아니요 | 페이지네이션 페이지 번호 |
page_size | integer | 아니요 | 페이지당 항목 수 |
예시
“승인 대기 중인 인증서 요청이 있어?”
에이전트가 list_sign_requests를 호출한 뒤 requested 상태인 항목만 걸러서 알려줍니다.
create_sign_request
새 인증서를 요청하는 CSR을 생성합니다. domain_list(DNS 이름)나 ip_list(IP 주소)로 Subject Alternative Name을 최소 하나 이상 제공해야 합니다. CA는 SAN을 각 CA의 루트 도메인과 매칭해 자동으로 선택되고, 커먼 네임은 첫 번째 SAN 항목에서 파생됩니다. 조직명은 매칭된 CA에서 상속됩니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
domain_list | array | 아니요 | Subject Alternative Name: DNS 항목 |
ip_list | array | 아니요 | Subject Alternative Name: IP 주소 |
valid_days | integer | 아니요 | 인증서 유효 기간(일) |
예시
“web-01.alpacax.com용 인증서를 요청해줘”
에이전트가 domain_list=["web-01.alpacax.com"]으로 create_sign_request를 호출합니다. Alpacon이 이를 alpacax.com 루트 도메인을 가진 CA와 매칭합니다.
get_sign_request
특정 CSR의 상세 정보를 ID로 조회합니다: 상태, 커먼 네임, SAN, 관련 CA, 처리 세부 정보.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
csr_id | string | 예 | 인증서 서명 요청 ID |
예시
“web-01.alpacax.com CSR 상태가 어떻게 돼?”
에이전트가 list_sign_requests로 CSR ID를 찾은 뒤 get_sign_request를 호출해 전체 상태와 처리 세부 정보를 조회합니다.
delete_sign_request
CSR을 취소합니다. requested(대기) 상태인 CSR만 취소할 수 있으며, canceled 상태로 전환됩니다. 이미 처리 중이거나 완료된 CSR은 이 방법으로 취소할 수 없습니다. 관리자, CA 소유자, 원 요청자만 가능합니다.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
csr_id | string | 예 | 취소할 인증서 서명 요청 ID |
예시
“방금 잘못된 도메인으로 제출한 인증서 요청을 취소해줘”
에이전트가 CSR ID로 delete_sign_request를 호출합니다. 요청은 발급되지 않고 canceled 상태로 전환됩니다.
approve_sign_request
대기 중인 CSR을 승인해 CA가 인증서를 발급하도록 합니다. 대기 중인 CSR은 list_sign_requests로 찾습니다. 관리자 또는 CA 소유자 권한이 필요합니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
csr_id | string | 예 | 승인할 인증서 서명 요청 ID |
예시
“web-01.alpacax.com CSR을 승인해줘”
에이전트가 CSR ID로 approve_sign_request를 호출하면 CA가 인증서를 발급합니다.
deny_sign_request
CSR을 거부합니다. approve_sign_request와 달리 상태 제한이 없어 어떤 상태의 CSR이든 거부할 수 있습니다. 요청자에게 결정 사항이 통지됩니다. 관리자 또는 CA 소유자 권한이 필요합니다.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
csr_id | string | 예 | 거부할 인증서 서명 요청 ID |
예시
“그 CSR 거부해줘, 우리 소유 도메인이 아니야”
에이전트가 CSR ID로 deny_sign_request를 호출하면 요청자에게 통지됩니다.
retry_sign_request
signing(처리 중) 상태에 멈춘 CSR을 재시도해 CA로 요청을 다시 보냅니다. signing 상태의 CSR만 재시도할 수 있습니다. 관리자 또는 CA 소유자 권한이 필요합니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
csr_id | string | 예 | 재시도할 인증서 서명 요청 ID |
예시
“저 CSR이 10분째 signing 상태에서 멈춰 있어, 다시 시도해줘”
에이전트가 CSR ID로 retry_sign_request를 호출해 CA에 요청을 다시 보냅니다.
인증서
발급된 인증서는 이 API에서 읽기 전용입니다. 인증서는 서명 요청 흐름을 통해서만 생성됩니다. CLI 대응 명령어: alpacon cert.
list_certificates
워크스페이스에 발급된 인증서 목록을 조회합니다. 커먼 네임, 만료일, 폐기 상태를 포함합니다. authority_id로 필터링할 수 있습니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
authority_id | string | 아니요 | 인증 기관 ID로 필터링 |
page | integer | 아니요 | 페이지네이션 페이지 번호 |
page_size | integer | 아니요 | 페이지당 항목 수 |
예시
“alpacax.com CA가 발급한 인증서를 전부 보여줘”
에이전트가 해당 CA의 ID를 authority_id로 지정해 list_certificates를 호출합니다.
get_certificate
특정 발급 인증서의 상세 정보를 ID로 조회합니다: 내용, 커먼 네임, SAN, 만료일, 폐기 상태.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
certificate_id | string | 예 | 인증서 ID |
예시
“web-01.alpacax.com 인증서는 언제 만료돼?”
에이전트가 list_certificates로 인증서 ID를 찾은 뒤 get_certificate를 호출해 만료일을 확인합니다.
revoke_certificate
발급된 인증서를 무효화할 폐기 요청을 생성합니다. RFC 5280 사유 코드와 자유 형식의 requested_reason을 선택적으로 포함할 수 있습니다. 호출자가 CA 소유자나 관리자라면 요청이 자동 승인되어 인증서가 즉시 폐기되고, 그렇지 않으면 approve_revoke_request를 통한 승인을 기다립니다.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
certificate_id | string | 예 | 폐기할 인증서 ID |
reason | integer | 아니요 | RFC 5280 폐기 사유 코드(기본값: 0, 미지정). 0, 1, 2, 3, 4, 5, 6, 9, 10 중 하나 |
requested_reason | string | 아니요 | 폐기에 대한 자유 형식 설명 |
사유 코드:
| 코드 | 사유 |
|---|---|
| 0 | 미지정 |
| 1 | 키 손상 |
| 2 | CA 손상 |
| 3 | 소속 변경 |
| 4 | 대체됨 |
| 5 | 운영 중단 |
| 6 | 인증서 보류 |
| 9 | 권한 철회 |
| 10 | AA 손상 |
예시
“web-01.alpacax.com 인증서를 폐기해줘, 키가 유출됐어”
에이전트가 certificate_id와 reason=1로 revoke_certificate를 호출합니다. 호출자가 CA 소유자나 관리자라면 인증서가 즉시 폐기되고, 그렇지 않으면 관리자나 CA 소유자의 승인을 기다립니다.
폐기 요청
폐기 요청은 인증서 무효화 승인 흐름을 추적합니다. revoke_certificate가 폐기 요청을 생성하며, 이 도구들로 직접 조회하고 관리할 수 있습니다. 요청은 requested, revoking, revoked, failed, denied, canceled 상태를 거칩니다. CLI 대응 명령어: alpacon revoke.
list_revoke_requests
워크스페이스의 인증서 폐기 요청 목록을 상태와 함께 조회합니다. 대기 중인 폐기 요청을 검토할 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
page | integer | 아니요 | 페이지네이션 페이지 번호 |
page_size | integer | 아니요 | 페이지당 항목 수 |
예시
“내 승인을 기다리는 폐기 요청이 있어?”
에이전트가 list_revoke_requests를 호출한 뒤 requested 상태인 항목만 걸러서 알려줍니다.
get_revoke_request
특정 폐기 요청의 상세 정보를 ID로 조회합니다: 사유, 상태, 관련 인증서.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
revoke_id | string | 예 | 폐기 요청 ID |
예시
“그 유출된 인증서의 폐기 요청 상태가 어떻게 돼?”
에이전트가 list_revoke_requests로 폐기 요청 ID를 찾은 뒤 get_revoke_request를 호출해 상태를 확인합니다.
approve_revoke_request
대기 중인 폐기 요청을 승인합니다. 승인 후 인증서가 폐기되고 CRL(인증서 폐기 목록)에 추가됩니다. 관리자 또는 CA 소유자 권한이 필요합니다.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
revoke_id | string | 예 | 승인할 폐기 요청 ID |
예시
“그 대기 중인 폐기 요청을 승인해줘”
에이전트가 폐기 요청 ID로 approve_revoke_request를 호출하면 인증서가 즉시 폐기됩니다.
deny_revoke_request
대기 중인 폐기 요청을 거부합니다. 인증서는 계속 유효합니다. 관리자 또는 CA 소유자 권한이 필요합니다.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
revoke_id | string | 예 | 거부할 폐기 요청 ID |
예시
“그 폐기 요청 거부해줘, 인증서가 아직 필요해”
에이전트가 폐기 요청 ID로 deny_revoke_request를 호출하면 인증서는 계속 유효한 상태로 남습니다.
retry_revoke_request
revoking 상태에 멈춘 폐기 요청을 재시도해 CA로 요청을 다시 보냅니다. revoking 상태의 요청만 재시도할 수 있습니다. 관리자 또는 CA 소유자 권한이 필요합니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
revoke_id | string | 예 | 재시도할 폐기 요청 ID |
예시
“저 폐기 요청이 한참 revoking 상태에서 멈춰 있어, 다시 시도해줘”
에이전트가 폐기 요청 ID로 retry_revoke_request를 호출해 CA에 요청을 다시 보냅니다.
cancel_revoke_request
승인되기 전에 대기 중인 폐기 요청을 철회합니다. 요청은 canceled 상태로 전환되고 인증서는 계속 유효합니다. requested(대기) 상태인 폐기 요청만 취소할 수 있습니다. 관리자, CA 소유자, 원 요청자만 가능합니다.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
revoke_id | string | 예 | 취소할 폐기 요청 ID |
예시
“그 인증서 폐기하지 마, 요청 취소해줘”
에이전트가 폐기 요청 ID로 cancel_revoke_request를 호출합니다. 인증서는 영향을 받지 않습니다.
관련 문서
- 서버 관리 도구: CA가 호스팅된 서버(에이전트)를 찾을 때 사용
alpacon authority: 인증 기관 관리 CLI 대응 명령어alpacon csr: 인증서 서명 요청 CLI 대응 명령어alpacon cert: 발급된 인증서 CLI 대응 명령어alpacon revoke: 폐기 요청 CLI 대응 명령어