본문으로 건너뛰기

원격 코드 서명 API 참고

이 문서는 원격 서명 기능을 직접 연동해야 하는 개발자를 대상으로 다음 두 가지 인터페이스를 설명합니다:

  • POST /v1/codesign/sign: 서명할 해시 다이제스트를 제출하고 RSA PKCS#1 서명 결과를 가져옵니다.
  • POST /v1/codesign/report-sign: 클라이언트 최종 처리 결과를 보고합니다(서명 횟수 집계에 영향을 주지 않음).

연동 주소​

환경주소
프로덕션 환경(기본값)https://ssl.face.racent.com
NICSRS 환경https://ssl.face.nicsrs.com

다른 환경의 주소가 필요한 경우, 인도 또는 운영팀에서 제공하는 주소를 기준으로 합니다.

공통 규약​

요청 형식​

  • 프로토콜: HTTPS
  • Method: POST
  • Body: JSON
  • Headers:
Content-Type: application/json
Accept: application/json
Authorization: Basic <base64(accessKey:accessSecret)>

인증​

인터페이스는 HTTP Basic Auth를 사용합니다:

  • Username: Access Key
  • Password: Access Secret

Authorization 헤더 생성:

printf "%s:%s" "$ACCESS_KEY" "$ACCESS_SECRET" | base64

일반 응답 구조​

{
  "code": 0,
  "message": "ok",
  "data": {}
}
필드타입의미
codeinteger비즈니스 상태 코드. 0은 성공을 의미하며, 0이 아닌 경우 비즈니스 실패를 의미합니다.
messagestring비즈니스 상태 설명으로, 실패 시 오류 설명이 표시됩니다.
dataobject인터페이스 비즈니스 데이터.

호출자는 HTTP 상태 코드와 비즈니스 상태 코드를 모두 처리해야 합니다:

  • HTTP 상태 코드가 2xx가 아님 → HTTP 오류로 처리합니다.
  • HTTP 상태 코드가 2xx이고 code != 0인 경우 → 비즈니스 오류로 처리합니다.
  • HTTP 상태 코드가 2xx이고 code == 0인 경우 → 해당 data를 읽습니다.

서명 인터페이스​

인터페이스 설명​

POST /v1/codesign/sign

서명할 해시 원시 바이트(Base64 인코딩)를 제출하면, 원격 서비스가 지정된 인증서를 사용해 RSA PKCS#1 서명을 완료한 후 결과를 반환합니다.

주의

/v1/codesign/sign에서 서명 내용이 성공적으로 반환되면 서명이 성공한 것으로 간주되어 서명 횟수가 1회 추가됩니다. 실패한 요청은 서명 횟수를 차감하지 않습니다. report-sign 호출 여부는 횟수 계산에 영향을 주지 않습니다.

요청 매개변수​

{
  "code": "CERT_CODE",
  "digest": "BASE64_ENCODED_HASH",
  "algorithm": "SHA256",
  "padding": "PKCS1",
  "extra": {
    "platform": "windows/amd64",
    "version": "1.0.0",
    "revision": "abcdef0",
    "time": "2026-06-12T10:00:00+08:00",
    "hostname": "build-host-01",
    "signing_filename": "Example.exe",
    "signing_filesize": 1048576
  }
}
필드타입필수설명
codestring예인증서 번호로, 원격 서명 인증서를 선택하는 데 사용됩니다.
digeststring예서명할 해시 원시 바이트의 Base64 인코딩 값입니다. 호출자는 대상 파일 및 서명 도구의 요구 사항에 따라 로컬에서 해시를 계산해야 합니다.
algorithmstring예해시 알고리즘으로, SHA1, SHA256, SHA384, SHA512를 지원합니다.
paddingstring예RSA 패딩 모드로, 현재는 PKCS1로 고정되어 있습니다.
extraobject아니오클라이언트 컨텍스트 정보로, 서명 기록, 감사 및 문제 해결에 사용됩니다.

extra 필드 설명:

필드유형의미
platformstring클라이언트 플랫폼으로, 예: windows/amd64, linux/amd64.
versionstring클라이언트 버전.
revisionstring클라이언트 빌드 revision입니다.
timestring클라이언트 빌드 시간 또는 요청 시간입니다.
hostnamestring서명을 시작한 호스트 이름입니다.
signing_filenamestring서명된 파일 이름 또는 경로로, 보안 정책에 따라 민감 정보를 마스킹하는 것을 권장합니다.
signing_filesizeinteger서명된 파일 크기(바이트)입니다.

요청 예시​

curl -u "$ACCESS_KEY:$ACCESS_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "code": "CERT_CODE",
    "digest": "BASE64_ENCODED_HASH",
    "algorithm": "SHA256",
    "padding": "PKCS1",
    "extra": {
      "platform": "windows/amd64",
      "version": "1.0.0",
      "hostname": "build-host-01",
      "signing_filename": "Example.exe",
      "signing_filesize": 1048576
    }
  }' \
  https://ssl.face.racent.com/v1/codesign/sign

성공 응답​

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "735985894427246592",
    "signature": "BASE64_ENCODED_SIGNATURE"
  }
}
필드타입의미
idstring서명 레코드 ID로, report-sign 호출 시 사용합니다.
signaturestringRSA 서명 결과의 Base64 인코딩입니다.

서명 결과 보고​

인터페이스 설명​

POST /v1/codesign/report-sign

클라이언트가 원격 서명 결과를 가져온 후 로컬 처리, 저장 또는 호출자에게 반환하는 과정에서 실패할 수 있습니다. 이 인터페이스는 클라이언트의 최종 처리 상태를 서버에 회신하여 서명 기록 표시 및 감사 추적에 활용하기 위해 사용됩니다.

설명

이 인터페이스는 클라이언트의 처리 결과만 기록할 뿐, /v1/codesign/sign의 횟수 집계 결과는 변경하지 않습니다. 이 인터페이스를 호출하지 않아도 서명 성공 횟수에 영향을 미치지 않습니다.

요청 매개변수​

{
  "id": "735985894427246592",
  "status": 1
}
필드유형필수설명
idstring예/v1/codesign/sign가 반환한 data.id입니다.
statusinteger예클라이언트 최종 처리 상태: 1 성공, 2 실패.

요청 예시​

curl -u "$ACCESS_KEY:$ACCESS_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "735985894427246592",
    "status": 1
  }' \
  https://ssl.face.racent.com/v1/codesign/report-sign

성공 응답​

{
  "code": 0,
  "message": "ok",
  "data": null
}

오류 응답 예시​

인증 실패:

{
  "code": 401,
  "message": "unauthorized",
  "data": null
}

매개변수 오류:

{
  "code": 400,
  "message": "invalid request",
  "data": null
}
주의

구체적인 오류 코드와 오류 메시지는 서버에서 실제로 반환하는 내용을 기준으로 합니다. 연동 측은 고정된 오류 문구에 의존하여 비즈니스 분기 판단을 해서는 안 됩니다.

연동 권장 사항​

  • Access Secret을 안전하게 보호하고, 로그, 크래시 리포트 또는 프론트엔드 페이지에 기록하지 마세요.
  • digest는 해시 원시 바이트의 Base64 인코딩이어야 하며, 16진수 문자열이나 전체 파일 내용이 아니어야 합니다.
  • algorithm는 digest의 실제 해시 알고리즘과 일치해야 합니다.
  • 현재 패딩 모드는 PKCS1로 고정되어 사용되므로, 다른 값을 전달하지 마세요.
  • digest와 signature 필드는 길이가 길 수 있으므로, 로그에는 길이 또는 접두사·접미사를 마스킹한 결과만 기록할 것을 권장합니다.
  • 클라이언트에서 최종 처리가 완료된 후 report-sign를 호출하여 결과를 보고하면, 추후 감사 및 문제 해결에 용이합니다.
  • 네트워크 오류, HTTP 오류, 비즈니스 오류를 각각 별도로 처리하고, 서명 요청에 합리적인 타임아웃 및 재시도 정책을 설정하세요.
최종 수정: 에