본문으로 건너뛰기

원격 코드 서명 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를 사용합니다:

  • 사용자 이름: Access Key
  • 비밀번호: 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 오류, 비즈니스 오류를 각각 처리하고, 서명 요청에 합리적인 타임아웃과 재시도 정책을 설정하십시오.
최종 수정: 에