인증서 도구
이 도구들은 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.
워크스페이스에 설정된 인증 기관 목록을 조회합니다. CA 이름, 도메인, 유효 기간, 키 알고리즘/크기를 반환합니다. 서명 요청을 만들기 전에 사용 가능한 CA를 확인할 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
page | integer | 아니오 | 페이지네이션 페이지 번호 |
page_size | integer | 아니오 | 페이지당 항목 수 |
예시
“우리가 설정해 둔 인증 기관이 뭐가 있어?”
에이전트가 list_certificate_authorities를 호출해 각 CA의 이름, 도메인, 유효 기간 설정을 알려줍니다.
워크스페이스 내에서 인증서를 서명할 새 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를 호출합니다.
특정 CA의 상세 정보를 ID로 조회합니다: 설정, 유효 기간, 키 알고리즘/크기, 상태. CA ID는 list_certificate_authorities로 확인합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
ca_id | string | 예 | 인증 기관 ID |
예시
“alpacax.com CA의 상세 정보를 보여줘”
에이전트가 list_certificate_authorities로 CA ID를 찾은 뒤 get_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 설정은 그대로 유지됩니다.
인증서 요청을 한 번도 받지 않은 CA를 삭제합니다. 요청을 한 번이라도 받은 CA는 삭제가 거부되고, CA와 함께 서명 요청, 인증서 기록, 폐기 내역이 그대로 남습니다. 요청 기록이 있는 CA를 더 이상 쓰지 않으려면 CA가 실행 중인 서버를 삭제하세요. 그러면 CA는 CA 목록에서 사라지고 요청 서명에도 선택되지 않습니다. 관리자 또는 CA 소유자 권한이 필요합니다.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
ca_id | string | 예 | 삭제할 인증 기관 ID |
예시
“이제 안 쓰는 옛날 스테이징 CA를 삭제해줘”
삭제에 성공하면 되돌릴 수 없으므로 에이전트가 delete_certificate_authority를 호출하기 전에 사용자에게 CA ID를 확인합니다. CA가 이미 인증서 요청을 받았다면 호출이 거부되고 아무것도 삭제되지 않습니다.
인증서 서명 요청(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 대응 명령어