참고 문헌 / 증거
Telegram · 독립적인 증인
자체 키와 봇을 사용하여 위트니스를 실행하고, 서명된 체크포인트를 채널에 게시한 후, 내보낸 데이터를 이를 기준으로 대조하여 확인하십시오.
위트니스는 서명된 체크포인트를 컬렉터와 별도로 보관합니다. 위트니스는 컬렉터의 서명과 저널의 연속성을 확인하고, 자체 키로 결과에 서명한 후, 이를 텔레그램 채널에 게시합니다. 컬렉터의 위트니스 엔드포인트에 대한 읽기 전용 액세스 권한이 있는 별도의 서버에서 실행하십시오.
기술적 결과에는 보존된 저널 접두부, 챌린지 응답, 서명 검사, Merkle 포함/일관성 검사, 서명된 연속성 결과가 포함됩니다. 다른 보관자가 운영하는 위트니스의 경우, 보관자 정보와 키 관리 기록을 그 지문과 함께 보관하십시오. 분리된 키와 분리된 보관은 구성의 서로 다른 부분을 설명합니다. 검증기는 두 번째 키가 저널 헤드를 어느 기록까지 보존했는지 보고하며, 보관자의 키 관리 기록은 그 키를 누가 보유하는지 보여 줍니다. 위트니스 저널은 보조 검사이며, 증거의 최소 요건은 제3자 시간입니다. 채널 게시물은 외부 시간을 더합니다. 텔레그램이 각 공개 게시물에 날짜를 부여하고, 검증기가 그 날짜를 직접 읽습니다.
도표를 텍스트로 변환
- 수집기 → 위트니스 (서명된 체크포인트: 기록 수 + 헤더 해시)
- 위트니스 → Witness 저널, 자체 키
- 위트니스 → 텔레그램 채널 (자체 봇을 통해 서명된 게시물)
- 증거 ZIP → verify.py
- Witness 저널, 자체 키 → verify.py
- 텔레그램 채널 → verify.py (t.me/s 페이지에서 실시간으로 읽거나, 데스크톱으로 내보내기)
위트니스가 보관하는 것#
| 이 도구는 | 증인은 결코 |
|---|---|
| 단일 워크스페이스용 읽기 전용 위트니스 토큰 | 수집기의 텔레그램 세션 또는 API 인증 정보 |
| 자체 Ed25519 키 및 저널 | 수집기의 보관소, 서명 키 또는 패널 토큰 |
| 자체 텔레그램 봇 토큰 | 메시지 내용: 헤더에는 기록 수와 해시가 포함됩니다. |
이 토큰은 추가 도구(More tools) → 추가 기능(Extras) → 독립적인 증인(Independent witness)에서 생성되며, 한 번만 표시되고
SHA-256 형태로만 저장됩니다. 이 토큰은 정확히 하나의 엔드포인트인 GET /api/witness/head를 열며, 이 엔드포인트는 갓
서명된 체크포인트와 서명된 콘텐츠가 없는 수집 카운터, 운영 상태 정보를 반환합니다.
이 토큰으로는 패널을 열거나, 메시지 내용을 읽거나, 설정을 변경할 수 없으며,
해당 페이지에서는 패널 토큰이 허용되지 않습니다. 동일한 페이지에서 토큰을 취소할 수 있습니다. 수집기는
새로운 위트니스 키가 확인을 시작하는 시점(witness.seen)을 기록하고 토큰별 마지막 확인 내역을 표시하며,
2.5 간격 내에 확인되지 않은 위트니스는 기한이 지난 것으로 표시됩니다.
새로운 증인은 각 폴링마다 무작위 챌린지를 전송하며, 캡처 문장은 수집자 서명 아래에서 이를 반영합니다. 카운터는 정확한 체크포인트에 바인딩되며 서명된 증인 게시물에 포함됩니다. 기존 헤더는 독립형 증인에 의해 계속 허용됩니다. 저널의 증가량만으로는 새로운 메시지로 간주되지 않습니다.
확인 및 기록 대상#
지정된 간격(기본값 10분)마다 TgWitness는 다음과 같은 작업을 수행합니다:
- 헤드 자체를 가져옵니다(수집기는 이를 푸시하거나 건너뛸 수 없습니다);
- 수집자의 서명, 고정된 수집자 키(
--collector-fingerprint, 또는 가장 먼저 확인된 키), 비감소 카운트, 그리고 변경되지 않은 카운트에서 변경되지 않은 헤드를 검증합니다. 머클 포함 및 일관성 증명은 증가하는 저널이 보존된 체크포인트를 확장함을 검증합니다. 연속성 증명이 사용된 후에는 이를 제거하는 것이 거부됩니다; - 자체 저널에 서명된 기록을 추가합니다:
witness.anchor(상태ok,key_changed,rollback(이전보다 기록 수가 적음),fork(길이는 동일하지만 헤더가 다름) 또는invalid(검증에 실패함), 또는witness.no_response( 수집기가 응답하지 않은 경우); - TgWitness가
실행 중이고 봇 API에 접속할 수 있는 동안에는 “응답 없음”을 포함하여 서명된 결과를 채널에 게시합니다. 게시물 ID(
witness.posted)가 기록되며, 게시 실패 시에도 ID(witness.post_failed)가 기록됩니다.
게시물은 다음과 같은 형식을 띠며, 마지막 줄에는 서명된 진술이 포함됩니다:
TgWitness witness #42 · journal head
Collector 3fa9c2d1e0b4a7f6: 18234 records
Head 9b1f…c07e
2026-10-28T19:40:00.123+00:00
TGW1.eyJhdCI6…<statement>.<signature>
Witness 실행하기#
텔레그램 봇(@BotFather를 통해 생성)과, 해당 봇이 관리자로 등록된 채널, 그리고 증인이 접근할 수 있는 수집기 주소가 필요합니다. 이 주소는 사설 네트워크 외부에서 HTTPS를 통해 접속 가능해야 합니다(배포 안내서의 HTTPS 프로필 참조).
패널에서 ‘더 많은 도구 → 추가 기능 → 독립 위트니스 → 구성’을
엽니다. 다음 세 단계로 진행됩니다.
읽기 전용 액세스, 채널 및 간격 설정, 위트니스 실행. 게시
정책, 선택적 HTTP/SOCKS5 프록시 및 사용자 지정 봇 API 주소는 ‘고급
설정’에서 확인할 수 있습니다. 이 양식을 통해
해당 작업 공간의 수집기 키가 고정된 witness.json
파일을 다운로드합니다. 새로
생성된 읽기 전용 토큰을 ‘액세스 파일을
witness-token.txt
로 저장’하여 다운로드하고, 이 파일과 위트니스 호스트에서 생성된 bot-token.txt
파일을 해당 JSON 파일 옆에 배치하십시오. 수집기는 봇 토큰을 절대 수신하지 않습니다.
다운로드를 수행한다고 해서 서비스가 시작되거나 메시지가 게시되지는 않습니다. 호스팅된 프로젝트의 위트니스는
암묵적으로 등록되지 않습니다.
python -m tgwitness.witness run --config witness.json --check-config
python -m tgwitness.witness run --config witness.json
python -m tgwitness.witness fingerprint --config witness.json
첫 번째 명령어는 네트워크 요청이나 키 생성 없이 구성 파일과 비밀 파일을 확인합니다. JSON 내의 경로는 해당 파일을 기준으로 하며, CLI/환경 경로는 작업 디렉터리를 기준으로 합니다. 호스트 외부에 위트니스 지문을 보관하십시오. 수집기의 마지막 폴링(last-poll) 표시기는 요청을 확인하는 역할만 하며, 게시 여부는 Proof를 통해 보고되거나 위트니스 저널 및 채널에서 확인됩니다.
패널이 SSH 터널 뒤에 위치하는 경우, 이 Caddy 예시를 참고하여 별도의 HTTPS 호스트 이름에서
범위가 지정된 위트니스 엔드포인트만 노출하십시오.
기본 작업 공간은 https://witness.example.org를 사용하며, 다른 작업 공간은
https://witness.example.org/profiles/ID를 사용합니다. 토큰은 여전히 필요하며, 패널 및
기타 API 경로는 해당 가상 호스트를 통해 전달되지 않습니다.
정기적으로 게시되는 체크포인트를 원하시면 all를 선택하세요. 5분 간격으로 기록할 경우, 워크스페이스당 하루 약 288개의
게시물이 생성됩니다. changes/problems는 일부 체크포인트를 의도적으로 게시하지 않습니다.
MTProxy는 수집기의 텔레그램 클라이언트용입니다. HTTP 폴링 및 텔레그램의 HTTPS
봇 API는 각각 자체적인 직접/HTTP/SOCKS5 경로(봇 API)를 사용합니다.
컬렉터 옆에서, Docker를 사용하여(동일한 호스트 — 독립적인 프로세스 및 키, 하지만
동일한 운영자): .env에 값을 입력하고 프로필을 시작합니다.
TGWITNESS_WITNESS_TOKEN=tgww_...
TGWITNESS_WITNESS_BOT_TOKEN=123456:ABC...
TGWITNESS_WITNESS_CHANNEL=@your_witness_channel
# another workspace: TGWITNESS_WITNESS_COLLECTOR=http://tgwitness:8787/profiles/<workspace ID>
docker compose --profile witness up -d
docker compose logs witness # prints the witness key fingerprint
이미지를 게재할 경우 docker compose --project-directory . -f deploy/compose/compose.image.yaml --profile witness up -d를 사용하십시오.
타인의 서버(별도 보관)에서: 리포지토리를 해당 서버로 복사하고,
TGWITNESS_WITNESS_COLLECTOR=https://your-collector.example.org와 위의 세 가지 값을
.env에 설정한 다음,
docker compose --project-directory . -f deploy/compose/compose.witness.yaml up -d
또는 Docker 없이:
python -m tgwitness.witness run --collector https://your-collector.example.org \
--token-file witness-token.txt --bot-token-file bot-token.txt --channel @your_witness_channel
Discord에 게시하기#
위트니스는 텔레그램 대신 디스코드 채널에 게시할 수 있습니다. 디스코드에서
‘채널 편집’ → ‘통합’ → ‘웹훅’을 열고, 웹훅을 생성한 후 URL을 복사하세요.
패널에서 2단계에서 ‘디스코드 웹훅 · 귀하의 채널’을 선택하세요. 위트니스 호스트에서
해당 URL을 discord-webhook.txt 옆에 witness.json옆에 저장하십시오; 이 URL은
수집기로 절대 전송되지 않습니다.
python -m tgwitness.witness run --collector https://your-collector.example.org \
--token-file witness-token.txt --discord-webhook-file discord-webhook.txt
위트니스에는 텔레그램 채널 또는 디스코드 웹훅 중 하나의 게시자만 있으며, 둘 다 가질 수는 없습니다. 게시물
은 동일한 서명된 진술을 포함하며 누구에게도 핑을 보낼 수 없습니다. 디스코드의
2,000
자보다 긴 게시물은 짧은 한 줄로 대체되며, 전체 체크는
witness-check.txt
로 첨부됩니다. 각 게시물 ID는 witness.posted
로 기록됩니다. verify.py --channel
는 텔레그램 채널만 읽으므로, 디스코드의 경우 위트니스 저널을 보관하십시오. 이 저널에는 모든
체크가 포함되어 있습니다. 디스코드 게시물은 검증자에게 외부 시간을 제공하지 않습니다.
옵션#
| 옵션 | 환경 | 기본값 | 의미 |
|---|---|---|---|
--interval |
TGWITNESS_WITNESS_INTERVAL |
10 | 점검 간격: 1–1440 |
--timeout |
_TIMEOUT |
30 | 컬렉터 및 봇 API 응답 대기 시간: 5–600초 |
--post |
_POST |
all |
all: 모든 항목 확인; changes: 새로운 문제 또는 오류; problems: 오류만 있고 답변이 누락된 경우 |
--title |
_TITLE |
TgWitness witness |
각 채널 게시물의 첫 문장 |
--collector-fingerprint |
_COLLECTOR_FINGERPRINT |
– | 첫 번째 답변을 신뢰하기보다는 수집기 키를 고정하세요 |
--proxy |
_PROXY |
직접 | socks5://host:port 또는 http://host:port |
--bot-api |
_BOT_API |
https://api.telegram.org |
봇 API 주소(예: 로컬 봇 API 서버) |
--data-dir |
_DATA |
witness-data |
Witness 키 및 저널 |
--config |
_CONFIG |
– | 위의 옵션 중 하나를 포함한 JSON 파일 |
수집기 주소, 토큰 및 채널은 다음에서 가져옵니다. --collector, --token 또는
--token-file, --bot-token 또는 --bot-token-file, --discord-webhook-file 그리고 --channel,
또는 _COLLECTOR, _TOKEN, _TOKEN_FILE, _BOT_TOKEN, _BOT_TOKEN_FILE,
_DISCORD_WEBHOOK_FILE 그리고 _CHANNEL, 이를 통해 프로세스 목록에서 비밀 정보가 제외됩니다.
구성 파일은 밑줄(_)이 포함된 옵션 이름과, 채널 게시물의 단어를 대체하는
texts를 사용합니다:
{"collector": "https://your-collector.example.org", "token_file": "witness-token.txt",
"bot_token_file": "bot-token.txt", "channel": "@your_witness_channel",
"interval": 5, "timeout": 30, "post": "changes", "title": "Partner witness",
"texts": {"ok": "journal head", "no_response": "no answer from the collector", "records": "records"}}
texts 키: ok, key_changed, rollback, fork, invalid, no_response, collector,
records, head. 명령줄이 환경 변수보다 우선하며, 환경 변수가 파일보다 우선합니다.
알 수 없는 옵션이나 텍스트 키는 무시되지 않고 메시지를 표시하며 위트니스를 중지시킵니다.
표현 방식은 검증에 전혀 영향을 미치지 않습니다. verify.py는 모든
게시물 끝에 있는 서명된 토큰을 확인합니다. --post changes나 problems를 사용하더라도, 게시되지 않은 검사는 여전히
위트니스 저널에 남아 있으며, verify.py는 이를 ‘게시되지 않음’으로 나열합니다. 시작 레코드는
정책을 명시합니다. 모든 검사는 여전히 저널에 나타나므로, 게시물이 적다는 것은 텔레그램에 의해 날짜가 기록되는 횟수가
적다는 것을 의미할 뿐, 검사 횟수가 적다는 것을 의미하지는 않습니다.
채널이 없어도 Witness는 여전히 로그를 보관합니다. Witness 키 지문
(python -m tgwitness.witness fingerprint)은 다른 곳에 보관하십시오.
여러 워크스페이스를 위한 공개 증명 페이지#
python -m tgwitness.proof 한 번에 최대 32개의 워크스페이스를 처리하며, 각 워크스페이스의 최신 서명된 확인 내역을 담은
읽기 전용 페이지를 제공합니다. 모든 워크스페이스는 데이터 폴더 내에 고유한 위트니스 키와
저널, 그리고 고정된 컬렉터 키를 갖습니다. 텔레그램 채널에 게시하는 기능은
워크스페이스별로 선택 사항입니다. 다음 파일을 기준으로 시작하세요:
proof.config.example:
| 분야 | 의미 |
|---|---|
title |
페이지 제목, 1–100자 |
data_dir |
파일과 관련된 Witness 키 및 저널; 기본값 proof-data |
interval, timeout |
점검 간격(분, 1–1440, 기본값 5); 대기 시간(초, 5–600, 기본값 20) |
workspaces[].id, label |
짧은 소문자 별명과 표시되는 이름 |
workspaces[].collector |
컬렉터 주소; 다른 워크스페이스는 /profiles/<workspace ID> |
workspaces[].collector_fingerprint |
필수 항목이며, 워크스페이스마다 다릅니다. |
workspaces[].token_file |
해당 워크스페이스의 읽기 전용 위트니스 토큰이 포함된 파일 |
workspaces[].channel, bot_token_file |
선택 사항: 각 확인 결과를 채널에 게시하기 |
workspaces[].proxy, bot_api |
선택적 경로 및 봇 API 주소 |
python -m tgwitness.proof --config proof.json --check-config
python -m tgwitness.proof --config proof.json --host 127.0.0.1 --port 8790
첫 번째 명령어는 연결을 열지 않고 파일과 토큰 파일을 검증합니다. 이 페이지는 GET 및 HEAD 요청에만 응답합니다:
/모든 워크스페이스를 표시하며, 2.5 간격 동안 확인 표시가 없는 워크스페이스는 ‘유효하지 않음’으로 표시됩니다./api/proofJSON과 동일한 결과를 반환합니다./api/proof/<id>최신 서명된 명세서를 다운로드합니다 (tgwitness-public-proof-v1): 증인 기록 번호 및 해시, 상태, 고정된 수집기 키, 체크포인트, 수집 카운터 및 채널 게시 성공 여부, 해당 워크스페이스의 증인 키로 서명됨./healthz워크스페이스의 모니터가 중지되면 503 오류를 반환합니다.
Caddyfile.proof.example과 같이 이 페이지에 고유한 호스트 이름을 지정하십시오. 검증을 위해
아래 설명된 대로
python -m tgwitness.witness export --data-dir proof-data/<id> --out witness.zip 내보낸 후
아래 설명대로 사용하십시오.
확인#
Witness 측에서 저널을 내보내려면:
python -m tgwitness.witness export --out witness.zip
# Docker (add -f deploy/compose/compose.witness.yaml on a witness server):
docker compose exec witness python -m tgwitness.witness export --out /witness/witness.zip
docker compose cp witness:/witness/witness.zip .
그런 다음, 어디서든 수집기의 서명된 ZIP 파일과 공개 채널 주소를 사용하여:
python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
--witness witness.zip --witness-fingerprint WITNESS_SHA256 --channel https://t.me/s/your_witness_channel
--channel은 텔레그램 데스크톱 내보내기 파일(‘채팅 기록 내보내기 → JSON’을 선택하면
result.json 파일이 생성됨)이나 저장된 페이지 사본도 지원합니다. 이 경우 게시물 내용은 확인하지만
외부 시간은 제공하지 않습니다.
verify.py는 위트니스 저널(체인 및 서명)을 확인한 다음, 위트니스가 확인한 모든 헤드가
내보낸 저널의 일부인지 확인합니다. 즉, 해당 카운트에 있는 기록은 정확히
그 해시를 가져야 합니다. 일치하지 않는 헤드는 검증에 실패합니다. 즉, 위트니스가 이를 확인한 후
저널이 변경된 것입니다. 또한 이 스크립트는 내보내기 후에 확인된 헤드, 위트니스가
기록한 이상 현상, 실패한 응답, 이 내보내기 파일에 일치하는 체크포인트가 존재하는
기간("X부터 Y까지 위트니스됨") 및 누락된 부분을 보고합니다. 이후의 체크포인트는 해당 기간을 연장하지 않습니다.
결과에는 마지막으로 일치한 레코드 번호와 일치하는 체크포인트가 없는
후속 레코드 수가 포함됩니다. 수출본 자체 키로 서명된 응답만 집계됩니다. 즉, 증인이
한 번도 본 적 없는 키로 서명된 수출본은 증인되지 않은 것으로 보고되며, --fingerprint를 사용하지 않을 경우
서명자는 고정되지 않은 상태로 남습니다. --channel를 사용할 경우, 모든 서명된 게시물은 증인 저널과
레코드 단위로 일치해야 합니다. 변경된 게시물은 검증에 실패하며, 누락된 게시물은 목록에 표시됩니다. 토큰이
일치하면 콘텐츠가 인증되며, 날짜는 서명된 토큰의 범위를 벗어납니다.
검증자는 활성 https://t.me/s/… 또는 https://telegram.me/s/… 주소를 통해
검증 시점에 해당 페이지에서 각 게시물의 날짜를 읽습니다. 텔레그램이 해당 날짜를 설정하며,
수정된 게시물의 날짜는 사용되지 않습니다. 내보내기 시작 지점에서 해당 조건을 충족하는 게시물의 가장 이른 날짜는
증거의 최소 조건을 충족하는 마지막 기록의 외부
시간입니다. 제공된 result.json, 저장된 페이지 또는 다른 웹
주소와 같은 다른 출처의 날짜는 독립적인 시간이 아닌 제공된 메타데이터이며, 결과에는 게시물
날짜의 출처가 명시되어 있습니다(post_date_verification).
증인이 확인한 내보내기 범위 필요#
증인이 확인한 최종 기록을 반드시 포함해야 하는 업무 인계 시, --require-witness를 추가하십시오:
python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
--witness witness.zip --witness-fingerprint WITNESS_SHA256 --require-witness
이를 위해서는 독립적으로 보관된 증인 지문,
수집기 키와는 다른 키, 그리고 이 내보내기 파일의 정확한 끝 부분에 해당하는 체크포인트가 필요합니다. 이전 접두사만 포함하는 체크포인트는
불충분합니다. 수집을 일시 중지하고, 증인이
최종 상태를 관찰하도록 한 뒤, 저널에 추가 기록이 이루어지기 전에 내보내십시오. 저널이 변경되면 다른 체크포인트를 확보하고
해당 상태를 내보내십시오. 이후의 체크포인트만으로는 더 짧은 내보내기 파일의 최종 해시를 검증할 수 없습니다.
--channel도 함께 지정된 경우, 주장된 게시물이 누락되었거나 일치 집합이 비어 있으면 이
엄격한 검사에 실패합니다. 이 플래그가 없으면, 일반적인 무결성 검사에서도 여전히 증인이 없는
레코드를 보고하지만, 그 외에는 무결한 아카이브를 거부하지는 않습니다.
위트니스 저널과 고정된 키는 별도로 보관하십시오. 온라인 검증을 통해 체크포인트 간의 연속성을 확인하며, 오프라인 검증에서는 보존된 모든 체크포인트를 내보낸 파일과 비교합니다. 연속성 증명이 없는 레거시 헤드는 오프라인 비교 결과를 유지하며, 온라인 연속성 검증 없이 보고됩니다. 보고서에는 위트니스 가동 중단 시간 및 간격별 게시 실패 내역이 나열됩니다.
일일 봉인 및 사용 불가 타임스탬프 캘린더#
위트니스는 전날(UTC 기준)의 저널 경계를 봉인하고, 서명된 봉인의 해시를 OpenTimestamps에 제출합니다. 캘린더 제출은 보류 중인 증거이며, 독립적으로 검증된 비트코인 커밋먼트만이 검증기에서 확인을 받습니다.
모든 캘린더가 실패할 경우, 서명된 인장과 실패한 시도는 저널에 남아 있습니다. 시간별 유지보수 패스는 재시작이나 날짜 변경 후를 포함하여 해당 원본 기록을 재시도합니다. 이 패스는 최대 32개의 인장을 스캔하고, 최대 두 건의 누락된 제출을 처리하며, 패스당 재시도에 최대 60초를 소요합니다. 지속적인 커서는 오래된 인장들을 순차적으로 처리합니다. 보존된 제출물은 기존의 증명 업그레이드 경로를 따릅니다.
재시도 시 씰이 다시 작성되거나 원래 날짜가 변경되거나,
캘린더가 이를 더 일찍 수신했다고 주장하지 않습니다. 이후의 비트코인 커밋먼트는 여전히 후순위의 외부
확인으로 남아 있습니다. 누락된 증명은 none으로 유지되며, 보류 중인 증명은 검증자가
독립적으로 확인할 때까지 pending 상태로 유지됩니다.