보안 난수 API 연동 가이드: 난수 바이트·정수·감사

핵심 정리

보안에 민감한 랜덤 바이트, 범위형 숫자, 섞기, 표본 추출에는 CSPRNG 기반 서비스를 사용합니다.
연동 전에 연산 종류와 범위, 개수, 실패 시 처리 방식을 명확히 정합니다.
증빙 영수증은 서비스가 기록한 요청과 결과를 확인하는 자료이며, 공개적으로 난수 값을 재현하는 수학적 증명과는 다릅니다.

CSPRNG는 겉모양이 아니라 예측 저항성을 다룹니다

암호학적으로 안전한 의사난수 생성기는 이전 출력을 관찰해도 다음 출력을 현실적으로 예측하기 어렵도록 설계됩니다. 알려진 시드로 같은 결과를 반복하는 것이 중요한 일반 시뮬레이션용 생성기와 목적이 다릅니다.

API는 고객마다 원시 바이트를 제각각 변환하게 하기보다 연산 의미를 분명하게 제공해야 합니다. Rantropy는 REST와 gRPC를 통해 랜덤 바이트, 범위형 숫자, 섞기, 표본 추출, 분포 워크플로우를 제공하며 선택한 연산은 사용량과 증빙 맥락에 남습니다.

첫 요청 전에 정해야 할 연동 기준

보안용 값과 업무용 난수를 먼저 구분합니다. 세션 비밀값과 암호화 논스는 바이트 단위 출력과 엄격한 취급이 필요합니다. 추첨, 확률형 아이템, 표본 추출은 범위와 목록 크기, 복원 추출 여부, 오류 처리 기준을 명시해야 합니다.

일반적인 연동은 REST, 지속적인 서버 간 호출은 gRPC를 검토합니다.
업무 연산에 맞춰 요청 제한시간, 재시도, 멱등성 기준을 정합니다.
API 키는 비밀 관리 서비스에 보관하고 환경과 서비스별로 분리합니다.
어떤 요청에 영수증이 필요한지, 증빙을 얼마나 보관할지 정합니다.

바이트 수를 명시해 REST API를 호출합니다

랜덤 바이트 연산은 JSON의 count 값을 받아 지정한 수만큼 생성합니다. REST JSON 응답에서는 protobuf bytes 필드인 data가 base64로 표현되며 randomnessBytesConsumed에는 이 연산에서 과금되는 랜덤 바이트 수가 표시됩니다.

receiptId는 계약과 요청에서 영수증 생성이 활성화된 경우에만 포함됩니다. 난수 생성이 성공했다고 모든 응답에 영수증이 있다고 가정하지 말고 선택 필드로 처리해야 합니다.

랜덤 바이트 32개 요청API 주소와 자격증명은 환경 변수 또는 비밀 관리 서비스에서 주입합니다.

curl --request POST "$RANTROPY_REST_URL/v1/random/bytes" \
  --header "content-type: application/json" \
  --header "x-api-key: $RANTROPY_API_KEY" \
  --header "x-api-secret: $RANTROPY_API_SECRET" \
  --data '{"count":32}'

JSON 응답 예시data를 base64 디코딩하면 요청한 32바이트 원본을 얻을 수 있습니다.

{
  "response": {
    "success": true
  },
  "data": "<base64-encoded-random-bytes>",
  "randomnessBytesConsumed": 32,
  "receiptId": "<receipt-id-when-enabled>"
}

Rantropy의 검증 범위와 다른 난수 증명 방식

Rantropy는 요청, 결과 해시, 사용량, 시점을 조회 가능한 영수증으로 연결합니다. 요금제와 영수증 정책이 지원하면 해시 연결과 머클 증명을 이용해 나중의 누락이나 변경을 탐지할 수 있습니다.

이 증빙 모델은 검증 가능한 난수 함수인 VRF, 공개 난수 비콘, 커밋-리빌 프로토콜과 같지 않습니다. 공개키로 특정 값을 증명하거나 참여자 한쪽이 최종 시드를 임의로 고르지 못하게 하는 등 각 방식이 해결하는 문제가 다릅니다. 통제하려는 위협에 맞는 방식을 선택해야 합니다.

연동 후 운영 점검

로드밸런서 평균값만 보지 말고 연산별 지연시간과 오류를 관찰해야 합니다. API 사용량과 계약 한도를 대조하고, 영수증 조회를 정기적으로 검증하며, 장애 전에 키 교체 절차를 시험합니다. 대량 호출 환경은 API 키 수와 영수증 사용 비율까지 반영해 부하를 시험해야 합니다.

보안 난수 API를 고를 때 확인할 기준