English · 한국어
보고 안내¶
PQC 이관을 보고하는 사람과 그 보고서를 읽는 사람을 위한 안내입니다. 보고서의 어느 부분을 pqcota가 증거로 뒷받침할 수 있는지, 관측하지 못한 것을 어떻게 적어야 하는지, pqcota의 결과가 뒷받침하지 않는 문장은 무엇인지 설명합니다.
pqcota는 보고서를 쓰지 않습니다. 보고서 생성기도 점수 매기기도 없습니다. pqcota는 관측, 이력, 비교, 생성한 변경 파일을 내고, 보고서는 사용자가 그것들로 조립합니다. 모든 숫자에는 단위가 있고 단위는 서로 다릅니다. 결과 수, 발견 항목 수, 시스템 수는 더할 수 없습니다. 이 안내는 어느 것이 어느 단위인지 밝히며, 보고서도 그래야 합니다. 이 안내는 읽는 사람이 질문하는 순서를 따릅니다. 무엇을 다뤘나, 무엇을 찾았나, 무엇을 보지 못했나, 무엇이 바뀌었나, 누가 변경을 승인했나, 효과가 있었나 순서입니다. 전체 개요는 README에서 시작하세요. 연결된 문서 중 한국어판이 없는 것은 영문입니다.
보고서의 각 부분이 근거로 삼을 수 있는 것¶
| 보고서의 부분 | pqcota가 줄 수 있는 것 | 출처 |
|---|---|---|
| 범위와 기간 | 사용자가 준 등록 목록에 어떤 시스템이 있었는지, 자산 규칙으로 발견 항목이 몇 개 제외됐는지, 각 상태가 언제 기록됐는지 | 사용자의 등록 목록과 자산 규칙, 적재 요약, pqcota-inventory -history <node> |
| 발견 항목 | 시스템별 암호 라이브러리와 버전, Java provider 체인, 그리고 각각의 증거 강도. 연결별 협상된 알고리즘과 등급 | pqcota-inventory(중앙) 또는 pqcota-discover-view(한 번 보기, 저장소 없음) |
| 관측하지 못한 것 | 갭, 제외된 발견 항목, 등록되지 않은 시스템의 결과, 서명을 검증하지 않은 결과 | 적재 요약, 이력과 스냅샷 보기의 갭 줄, 사용자의 실행 로그 |
| 지난번 이후의 변경 | 두 스냅샷 사이에 추가, 삭제, 변경된 발견 항목 | pqcota-inventory -diff <older>,<newer> |
| 승인 | 계획이 확정됐는지, 등록된 키로 확인되는 서명이 붙어 있는지 | pqcota-provision(아니면 거부합니다)과 계획의 승인 항목 |
| 생성한 변경 | 생성기가 어떤 조치의 파일을 만들었는지, 그 전에 기록한 관측 상태 | pqcota-provision 출력과 pqcota-records |
| 적용한 변경 | 없음. pqcota는 변경을 적용하지 않고 적용됐다는 기록도 남기지 않습니다 | 배포 도구 자체의 로그 |
| 확인 | 변경 뒤의 새 관측과 이전 관측의 비교 | pqcota-inventory -diff, 아래의 한계 포함 |
1. 범위와 기간¶
독자가 숫자가 무엇을 덮는지 알기 전에는 보고서의 숫자가 아무 의미도 없습니다. 먼저 세 가지를 밝히세요.
- 어떤 시스템. 인벤토리는 결과를 받아들이기 전에 시스템이 등록돼 있도록 요구할 수 있습니다. 등록한 시스템의 총수는 사용자가 준 목록의 크기이며 pqcota는 이를 출력하지 않으므로 직접 세야 합니다. 적재 요약은 등록되지 않았거나 앵커가 없어서 거부한 결과를 보고합니다(
unregistered/no-anchor N이라는 줄입니다). 이것은 시스템이 아니라 결과의 수이고, 두 가지 원인을 구분하지 않습니다. - 어떤 자산. 계속 지켜볼 자산을 지정할 수 있습니다(예: 배포판의 기본 라이브러리를 제외). 제외는 없음이 아닙니다. 적재 요약과 인벤토리 보기는 몇 개가 제외됐는지 밝히며, 그 수는 시스템이 아니라 발견 항목(자산)의 수입니다. 독자가 제외된 항목이 존재하지 않는다고 결론짓지 않도록 그 단위를 붙여 인용하고, 시스템 수에 더하지 마세요.
- 언제. 인벤토리는 관측한 상태가 바뀔 때만 새 스냅샷을 보관합니다. 상태가 같은 반복 관측은 기존 스냅샷에 관측 횟수와 시간 범위로 기록되며,
pqcota-inventory -history <node>가 둘 다 보여 줍니다. 「마지막으로 바뀐 때」와 「마지막으로 관측한 때」는 다른 날짜이니 어느 쪽인지 밝히세요.
2. 발견 항목¶
관측한 것을 보고하되, 세 종류의 진술을 구분하세요.
- 시스템에 있는 라이브러리나 provider. 그 시스템이 쓸 수 있는 것을 보여 줍니다. 모든 연결이 그것을 쓴다는 것을 보여 주지는 않습니다. OpenSSL의 경우 pqcota는 라이브러리와 그 버전을 관측합니다. Java는 애플리케이션이 실행 중에 등록한 provider를 포함해 provider 체인을 읽을 수 있습니다.
- 연결에서 협상된 알고리즘. pqcota가 지켜보는 동안 양쪽이 합의한 것을 보여 줍니다. 그 구간에 일어나지 않은 연결은 결과에 없습니다.
- 등급. 🟢 양자내성 또는 하이브리드, 🔴 고전, ⚪ 등급 미정. 등급은 협상된 것을 기술합니다. 🔴는 취약하다거나 규정을 어겼다는 판정이 아닙니다. 바꿀지, 언제 바꿀지는 보고서가 그것을 결정하는 사람의 몫으로 적어야 하는 결정입니다.
발견 항목에 증거 강도를 함께 인용하세요. 증거 강도는 그 사실을 어떻게 수집했는지를 기록합니다. 실행 중인 시스템에서, 소스에서, 또는 추적으로 본 사실은 「confirmed」입니다. 제공받은 암호 자산 명세서에서 가져온 사실은 아무도 실행 중인 시스템을 관측하지 않았으므로 더 낮게 매깁니다.
3. 관측하지 못한 것¶
보고서에서 가장 자주 빠지는 부분이고, 꼼꼼한 독자가 가장 먼저 찾는 부분입니다. pqcota는 많은 갭이 기록에 남도록 만들어져 있습니다. pqcota-inventory -history의 gap 열은 스냅샷이 보지 못한 관측 계층을 알려 주고, 연결을 애플리케이션에 대응시키지 못한 까닭 같은 세부는 -snapshot이 출력합니다. 검증하지 않은 서명, 중복, 거부된 결과는 적재 출력에만 나옵니다. 하나의 보기가 아니라 각각이 출력되는 곳에서 모으세요.
| 일어난 일 | pqcota가 기록하는 방식 | 적을 말 |
|---|---|---|
| 수집기를 지원하지 않는 운영체제에서 실행함 | 갭 기록과 종료 코드 0. 갭이 인벤토리에 닿을 수 있도록 | 「관측하지 못함: 시스템 X, 까닭 Y」. 「암호 알고리즘이 발견되지 않음」이라고는 절대 적지 마세요 |
| 필요한 권한 없이 네트워크 캡처 | 네트워크 계층의 갭 기록과 종료 코드 0 | 「X의 연결을 관측하지 못함」 |
| OpenSSL 스캔이 프로세스 목록을 열지 못함 | 스캔이 완전성 메모에 프로세스 목록을 쓸 수 없다고 표시하고 결과를 냄 | 「X의 프로세스를 나열하지 못함」 |
| OpenSSL 스캔이 프로세스를 나열할 수 있지만 일부는 접근이 거부됨 | 스캔 통계에 거부 수로 집계되고, 갭으로 기록되지는 않음 | 그 수가 있으면 거부된 수를 인용 |
| 수집기가 시작하지 않거나, 결과 파일이 컨트롤러에 닿지 않음 | 아무것도 기록되지 않음. 적재할 갭 기록이 없습니다 | 실행 로그를 관측하려던 시스템 목록과 대조하세요. 갭 기록이 만들어졌다는 것도 적재가 성공했다는 증거는 아닙니다 |
| Java attach가 막힘 | 정적 provider 체인을 읽음. 실행 중에 등록된 provider는 사각지대로 남고 갭으로 보고됨 | 「X에서 실행 중에 등록된 provider가 빠졌을 수 있음」 |
| 결과 서명을 검증하지 않음(검증 키 없음) | 적재 요약이 검증한 것과 따로 검증하지 않음으로 셈 | 그 수와 검증을 켰는지 밝히세요 |
| 자산 규칙으로 제외된 발견 항목 | 적재 요약과 보기가 몇 개를 걷어 냈는지 밝힘(발견 항목의 수) | 수와 단위를 인용 |
| 등록되지 않은 시스템의 결과 | 적재 요약에 셈(결과의 수). 거부 항목(시스템, 수집기, 까닭, 내용 해시)은 데이터베이스가 설정돼 있으면 거기에, 없으면 메모리에 남고 프로세스가 끝나면 사라짐. 검토한 명령들은 이 항목을 나열하지 않으며 원래 결과도 거기에 보관되지 않음 | 수를 인용하고, 적재 출력을 보관하세요. 그것이 사용자가 갖게 될 기록입니다 |
| 같은 머신이 여러 이름으로 등록됨 | 적재 출력에 중복으로 표시. pqcota는 합치거나 이름을 고르지 않음. 탐지는 그 실행에서 함께 적재한 결과끼리만 비교하며 전체 이력을 찾지 않고, 신원 지문이 없는 머신은 대상이 아님 | 해결될 때까지 시스템 수가 부풀려졌을 수 있고, 따로 적재한 중복은 표시되지 않을 수 있다고 밝히세요 |
| 연결의 애플리케이션을 식별하지 못함(짧게 끝난 연결) | @?로 표시. 사람이 채울 수 있고 채운 값은 사람이 선언한 것으로 표시됨 |
대응시키지 못한 수와 사람이 선언한 수를 밝히세요 |
4. 지난번 이후의 변경¶
pqcota-inventory -diff <older>,<newer>는 두 스냅샷 사이에 추가, 삭제, 변경된 발견 항목을 나열합니다. 보고서에 쓸 때 주의할 점이 셋 있습니다.
- 인자 순서가 중요합니다. 첫 인자가 더 오래된 스냅샷입니다. 반대로 주면 「추가」가 「삭제」로 읽히며, 순서가 뒤집히면 도구가 경고를 출력합니다. 그 경고가 없는지 확인하세요.
- 규칙 버전이 다를 때. 두 스냅샷이 서로 다른 규칙 버전으로 도출됐다면, 도구는 도출 값의 차이가 실제 변경이 아니라 재계산일 수 있다고 경고합니다. 그런 차이를 시스템의 변경으로 보고하지 마세요.
- 「변경 없음」에는 까닭이 필요합니다. 새 스냅샷이 없다는 것은 관측한 상태가 같았다는 뜻입니다. pqcota가 관측하지 않는 면에서 시스템이 바뀌지 않았다는 뜻까지는 아닙니다.
5. 승인¶
변경은 확정됐고 승인 서명이 붙은 계획에서만 생성됩니다. 보고할 수 있는 것은 이렇습니다.
- 계획이 확정되고 승인됐으며, 승인이 검증됐습니다. 기본적으로 생성기는 서명을 승인자의 등록된 공개 키로 확인하고, 확인하지 못하면 거부합니다. 어느 승인자의 키가 등록돼 있었는지 밝히세요.
- 검증이나 완전성을 면제했다면 밝히세요. 명령줄 옵션 둘이 생성을 계속하게 합니다.
--allow-unverified-approvals(검증할 키가 등록되지 않았을 때 계속)와--allow-incomplete(빈칸이 있는 출력을 받아들임)입니다. 각각 선택한 것이라는 경고를 표준 오류로 출력합니다. 둘 중 하나라도 썼다면 보고서가 그렇게 밝혀야 합니다. - 종료 코드는 인증서가 아닙니다. 종료 코드 0은 명령이 실패하지 않았다는 뜻입니다.
--allow-incomplete와 함께면 빈칸을 넘어갔다는 뜻이기도 하며, 흔적은 표준 오류의 경고뿐입니다. 종료 코드 3은 출력에 빈칸이 있다는 뜻입니다. 종료 코드 1은 명령이 멈췄다는 뜻입니다. 계획이 거부됐거나(확정되지 않음, 승인 없음, 검증할 수 없는 승인) 데이터베이스 연결, 조회, 기록 쓰기가 실패한 경우이며, 이때 플레이북이 이미 표준 출력에 쓰였을 수 있습니다. 종료 코드 2는 사용법이나 입력 오류입니다. 표준 오류 텍스트, 사용한 옵션, 생성한 파일, 기록이 저장됐는지를 보관하고, 종료 코드만이 아니라 그것들로 보고하세요. - pqcota가 관리하지 않는 것. 누가 계획을 검토하고, 어떤 순서로 하고, 누가 승인자 키를 보관하는지는 조직의 절차입니다. 서명은 등록된 키를 가진 사람이 이 계획을 승인했음을 보일 뿐, 조직의 절차가 지켜졌음을 보이지는 않습니다.
6. 생성하고 적용한 변경¶
pqcota-records는 변경마다 기록된 것을 나열합니다. id와 상태, 노드, 계획, 영향받는 애플리케이션, 이전에 기록된 모듈(채워져 있으면 이후 것도), 스냅샷 참조를 풀 수 있었는지입니다.
STAGED는 생성기가 변경을 기록했다는 뜻입니다. 노드에 무엇이 놓였다는 뜻이 아닙니다. 생성기는 노드에 접속하지 않습니다. 보고서에는 두 줄을 따로 두세요. 생성하고 기록함(pqcota에서)과 적용함(날짜와 결과, 배포 도구의 로그에서만).- 기록은 생성기에 데이터베이스(
--dsn)를 줬을 때만 있습니다. 주지 않으면 변경 전 상태를 담지 않고 아무것도 저장되지 않습니다. - 기록된 「변경 전」은 인벤토리가 관측해 둔 상태입니다. 기록에는 관측된 모듈과, Java라면 관측된 provider 체인을 저장합니다.
pqcota-records가 보여 주는 것은 모듈뿐입니다. 백업이 아니며 시스템의 설정은 담지 않습니다. - 생성한 변경마다 짝이 되는 제거 파일이 있습니다. 제거는 계획이 배치한 것을 지웁니다. 이전 배포를 복원하는 것이 아니며, 설정으로 구현할 수 없는 변경은 수동 단계로 표시되므로 되돌리는 것도 수동입니다.
7. 변경 확인과 그 한계¶
보고서의 마지막 줄로 자연스러운 것은 「그리고 효과가 있음을 확인했다」입니다. 이 문장은 조심해서 쓰세요.
- 다시 관측하고 비교하세요. 새 관측을 적재하고
-diff를 쓰세요. Java provider 체인에서는 새 provider가 체인에 나타나므로 변경이 보입니다. - OpenSSL은 인벤토리가 움직이지 않을 수 있습니다. pqcota는 OpenSSL의 라이브러리와 버전을 관측하고, 어떤 provider가 로드됐는지는 관측하지 않습니다. 프로젝트 자체 데모에서 실물 양자내성 provider를 추가하자
openssl list -kem-algorithms의 ML-KEM 항목 수가 0에서 14로 늘었는데, 다시 관측해도 provider 계층이 관측되지 않으므로 변화 없음으로 나왔습니다. 이 결과는 적용에 실패한 것이 아니라 도구가 정직하게 알린 것입니다. - 연결의 등급은 양쪽이 알고리즘을 지원할 때만 바뀝니다. 한쪽만 올려서는 🔴 연결이 🟢으로 바뀌지 않습니다.
- 그러니 실제로 검증한 것을 적으세요. 「provider를 배치했고 노드가 그 알고리즘을 나열한다」는 능력에 관한 진술입니다. 「이제 연결이 양자내성 알고리즘을 협상한다」는 그 연결들을 관측해야 말할 수 있습니다.
8. pqcota 결과가 뒷받침하지 않는 문장¶
| 쓰지 말 것 | 까닭 | 대신 쓸 것 |
|---|---|---|
| 「우리 시스템의 X%가 양자 안전하다」 | pqcota는 시스템이 아니라 관측한 연결에 등급을 매기며 점수를 매기지 않음 | 「관측한 연결 M개 중 N개가 양자내성 또는 하이브리드 알고리즘을 협상했다」 |
| 「양자에 취약한 암호가 남아 있지 않다」 | pqcota는 관측한 것을 보일 뿐이고, 갭과 등록되지 않은 시스템이 있음 | 「다룬 M개 시스템에서 관측한 N개 연결 가운데 고전 키 교환은 없었다. 다음 시스템은 관측하지 못했다: …」 |
| 「우리는 규정을 준수한다」 | pqcota는 규정 준수 제품이 아니며 규정 준수를 인증하지 않음 | 「첨부한 증거: …」 |
| 「모든 시스템을 다뤘다」 | 등록과 제외 규칙이 범위를 정함 | 등록한 수, 제외한 수, 관측하지 못한 수를 밝힘 |
| 「변경을 검증했다」(다시 관측한 것만으로) | 관측이 바뀐 계층을 보지 못할 수 있음 | 관측한 것과 보지 못한 것을 적음 |
| 「아무도 이력을 바꿀 수 없다」 | 도구의 일반 명령은 옛 기록을 고치지 않지만, 데이터베이스 관리자 권한을 가진 사람의 변조까지 막는 것은 아님. pqcota-prune은 오래된 이력을 삭제할 수도 있으며, 삭제했다는 사실은 기록함 |
「도구는 변경을 새 항목으로 기록한다. 데이터베이스 접근은 …이 통제한다」 |
출력에서 각 숫자가 나오는 곳¶
2026-09-30에 실행한 데모에서 줄여 인용한 줄입니다. 문구는 버전에 따라 바뀔 수 있으므로 줄 전체가 아니라 낱말로 찾으세요.
| 보고 항목 | 명령 | 찾을 줄 | 단위 | 비고 |
|---|---|---|---|---|
| 받아들인, 거부한, 검증하지 않은 결과 | pqcota-ingest |
ingest result: accepted 7 · unregistered/no-anchor 0 · signature-rejected 0 → 3 nodes observed (changed 3 · identical 0) |
결과. 마지막 부분은 노드 수 | unregistered/no-anchor는 두 원인을 합침 |
| 서명을 한 번도 검증하지 않음 | pqcota-ingest |
unverified signatures: 7 … they were never checked |
결과 | 적재 출력에만 나옴 |
| 같은 머신, 여러 이름 | pqcota-ingest |
⚠ duplicate: physical machine … registered under several node_ids → [pay-db web-gw] |
머신 | 그 실행에서 적재한 결과끼리만 |
| 자산 규칙으로 제외된 발견 항목 | pqcota-ingest, pqcota-inventory |
asset scope: 3 excluded as out of scope, excluded by asset scope: 1 (… not absence) |
발견 항목 | 시스템 아님 |
| 상태가 기록되고 다시 확인된 때 | pqcota-inventory -history <node> |
열 changed, obs, observed, gap |
스냅샷, 관측 | gap은 보지 못한 계층을 알려 줌 |
| 보지 못한 까닭 | pqcota-inventory -snapshot <id> |
gap (unobservable by design != absent): … 3 of 4 edges could not be attributed to an app |
엣지 | 까닭은 -history가 아니라 이 줄에 있음 |
| 사람이 선언한 애플리케이션 | pqcota-inventory -snapshot <id> |
(1 of them are not observations but apps declared by a person) |
엣지 | |
| 등급 합계 | pqcota-inventory, pqcota-discover-view |
totals: 2 assets · 4 observed edges (🟢 PQC 2 · 🔴 classical 2 · ⚪ unknown 0) |
자산, 엣지 | |
| 달라진 것 | pqcota-inventory -diff <older>,<newer> |
removed 1, added N, changed N. 순서가 뒤집혔을 때와 규칙 버전이 다를 때의 경고 |
발견 항목 | 자산 규칙 뒤의 removed는 관리에서 빠졌다는 뜻이지 사라졌다는 뜻이 아님 |
| 승인 검증됨 | pqcota-provision |
approvals verified: reviewer-1 |
승인자 | 또는 검증하지 않았다는 경고 |
| 완전성 면제 | pqcota-provision |
N incomplete spot(s) — passed over because --allow-incomplete was given |
빈칸 | 표준 오류. 종료 코드는 0 그대로 |
| 기록 저장됨 | pqcota-provision --dsn |
persisted 1 records (before capture · STAGED · rollback basis) · snapshot references resolved 1, unresolved 0 |
기록 | STAGED는 적용이 아님 |
| 기록된 것 | pqcota-records |
• plan-demo:a1 [STAGED] node=… affected apps: … before : libssl.so.1.1@1.1.1f snapshot: … |
기록 | 모듈만이고 전체 설정은 아님 |
표의 모든 줄은 그 데모 실행에서 출력된 것입니다. 단 -diff 행의 두 경고는 예외입니다. 그 경고는 코드의 조건(두 스냅샷을 시간 역순으로 준 경우, 두 스냅샷이 서로 다른 규칙 버전으로 도출된 경우)에서 출력되며, 여기에 인용한 실행에서는 일어나지 않았습니다.
보고서 뼈대¶
| 절 | 채울 것 | 출처 |
|---|---|---|
| 범위 | 등록 목록의 크기(시스템), 제외한 발견 항목(발견 항목), 거부한 결과(결과). 단위를 구분해 두세요 | 사용자의 목록, 적재 요약 |
| 기간 | 관측 날짜, 시스템별 마지막 변경 날짜 | -history |
| 발견 항목 | 라이브러리, provider 체인, 증거 강도, 연결 등급과 합계 | pqcota-inventory |
| 관측하지 못한 것 | 까닭이 있는 갭, 검증하지 않은 서명, 중복, 대응시키지 못한 연결, 수집기가 결과를 내지 못한 시스템 | 적재 요약, -history의 gap 열, -snapshot의 gap 줄, 사용자의 실행 로그 |
| 지난 보고 이후의 변경 | 추가, 삭제, 변경. 규칙 버전을 적을 것 | -diff |
| 승인 | 계획, 승인자, 서명을 검증했는지, 사용한 옵션(--allow-unverified-approvals, --allow-incomplete), 생성기의 종료 코드와 표준 오류 |
pqcota-provision, 계획 파일 |
| 생성하고 기록한 변경 | 파일이 생성된 조치, 기록된 변경 전 상태, 기록이 저장됐는지 | pqcota-provision 출력, pqcota-records |
| 적용한 변경 | 시스템별 날짜와 결과 | 배포 도구 로그만 |
| 확인 | 다시 관측한 것, 달라진 것, pqcota가 볼 수 없는 것 | -diff, 7절 |
| 남은 일 | 수동 단계, 불완전한 계획, 아직 관측하지 못한 시스템 | 생성기 출력 |
받은 보고서에 던질 질문¶
- 이 보고서는 어떤 시스템을 다루며, 등록한 수, 제외한 수, 관측하지 못한 수는 얼마인가?
- 시스템마다 마지막으로 관측한 때와 마지막으로 바뀐 때는 언제인가?
- 여기 있는 🔴는 지켜본 연결이며, 그것을 어떻게 할지는 누가 정하는가?
- 무엇을 보지 못했고 그 까닭은 무엇인가?
- 승인 서명을 모두 검증했는가, 아니면 옵션으로 검증이나 완전성을 면제했는가?
- 각 숫자는 시스템, 결과, 발견 항목 중 무엇의 수인가?
- 「적용함」은 배포 로그에서 나온 것인가, 아니면 pqcota 기록에서만 나온 것인가?
- 완료됐다고 적은 변경이라면, 그 뒤에 무엇을 관측했고 도구가 바뀐 계층을 볼 수 있었는가?