API 통합

sslTrus는 원격 코드 서명 API를 제공하며, 서명 클라이언트, 빌드 시스템 또는 기타 서명 통합 프로그램을 자체 개발해야 하는 개발자에게 적합합니다.

API는 클라이언트가 계산한 파일 다이제스트를 수신하고, 원격 코드 서명 서비스가 지정된 코드 서명 인증서를 사용하여 개인 키 서명을 완료한 후 서명 결과를 반환합니다.

클라이언트 담당:

서명할 데이터의 다이제스트 계산.
대상 파일에 필요한 서명 구조 구성.
원격 서명 인터페이스 호출.
반환된 서명 결과를 대상 파일 또는 서명 구조에 기록.
필요에 따라 클라이언트 최종 처리 결과 보고.

코드 서명 개인 키는 항상 클라우드 HSM에 보관되며 API를 통해 클라이언트에 반환되지 않습니다.

접속 주소

프로덕션 환경 기본 주소:

https://ssl.face.racent.com

NICSRS 환경:

https://ssl.face.nicsrs.com

전체 서명 인터페이스:

POST https://ssl.face.racent.com/v1/codesign/sign

결과 보고 인터페이스:

POST https://ssl.face.racent.com/v1/codesign/report-sign

실제 제공 환경에서 다른 서비스 주소를 사용하는 경우, 제공 또는 운영 측에서 안내한 주소를 기준으로 하십시오.

신원 인증

API는 HTTP Basic Auth를 사용합니다.

대응 관계:

Username = Access Key
Password = Access Secret

요청 헤더:

Authorization: Basic <base64(accessKey:accessSecret)>

예:

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

실제 사용 시 curl는 -u 매개변수를 통해 직접 제공할 수 있습니다:

curl -u "$ACCESS_KEY:$ACCESS_SECRET"

Access Secret은 민감한 자격 증명이므로 소스 코드, 공개 설정 파일, 로그 또는 프런트엔드 페이지에 기록해서는 안 됩니다.

일반 요청 형식

API 사용:

HTTPS
POST
JSON

요청 헤더:

Content-Type: application/json
Accept: application/json
Authorization: Basic <credentials>

공통 응답 형식

API는 통일된 JSON 구조를 반환합니다:

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

필드 설명:

필드	유형	설명
`code`	integer	비즈니스 상태 코드, `0` 는 성공을 나타냅니다
`message`	string	상태 또는 오류 정보
`data`	object	인터페이스 비즈니스 데이터

클라이언트는 HTTP 상태 코드와 비즈니스 상태 코드를 동시에 확인해야 합니다.

다음과 같은 방식으로 처리하는 것을 권장합니다:

HTTP 非 2xx
    ↓
HTTP 请求失败

HTTP 2xx + code != 0
    ↓
业务失败

HTTP 2xx + code == 0
    ↓
读取 data

HTTP 200만으로 서명 요청 성공을 판단하지 마십시오.

서명 인터페이스

인터페이스:

POST /v1/codesign/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
  }
}

주요 매개변수:

매개변수	유형	필수	설명
`code`	string	예	코드 서명 인증서 번호
`digest`	string	예	서명할 다이제스트 원본 바이트의 Base64 인코딩
`algorithm`	string	예	다이제스트 알고리즘
`padding`	string	예	RSA 패딩 방식, 현재 `PKCS1`로 고정
`extra`	object	아니요	클라이언트 컨텍스트 및 감사 정보

다이제스트 알고리즘

현재 지원:

SHA1
SHA256
SHA384
SHA512

예를 들어 SHA-256을 사용할 때:

{
  "algorithm": "SHA256"
}

algorithm은(는) 반드시 digest에서 실제로 사용하는 다이제스트 알고리즘과 일치해야 합니다.

digest 형식

digest은(는) 반드시:

해시 원시 바이트 → Base64

아닙니다:

文件内容 Base64

아닙니다:

十六进制哈希字符串

예를 들어 특정 SHA-256 다이제스트 자체가 32바이트라면, 해당 32개의 원시 바이트를 Base64로 인코딩한 후 인터페이스에 전달해야 합니다.

padding

현재 고정 사용:

PKCS1

즉:

{
  "padding": "PKCS1"
}

다른 패딩 방식을 전달하지 마십시오.

extra

extra 는 클라이언트 컨텍스트, 감사 정보를 기록하고 문제 해결을 지원하는 데 사용됩니다.

지원:

필드	유형	설명
`platform`	string	클라이언트 플랫폼
`version`	string	클라이언트 버전
`revision`	string	클라이언트 빌드 revision
`time`	string	빌드 시간 또는 요청 측 기록 시간
`hostname`	string	요청을 시작한 호스트 이름
`signing_filename`	string	서명된 파일 이름 또는 로컬 경로
`signing_filesize`	integer	파일 크기, 단위는 바이트

예:

{
  "extra": {
    "platform": "linux/amd64",
    "version": "1.2.0",
    "hostname": "github-runner-01",
    "signing_filename": "app.exe",
    "signing_filesize": 5242880
  }
}

如果 signing_filename에 내부 디렉터리, 사용자 이름 또는 기타 민감한 정보가 포함된 경우 고객 측 보안 정책에 따라 마스킹 처리하는 것이 좋습니다.

서명 요청 예시

curl 사용:

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": "linux/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"
  }
}

반환 필드:

필드	유형	설명
`id`	string	서명 기록 ID
`signature`	string	RSA 서명 결과의 Base64 인코딩

실제 서명 기능의 경우 클라이언트는 주로 다음을 사용합니다:

data.signature

로컬에서 처리 완료 후 최종 상태를 보고해야 하는 경우 다음 사항도 저장해야 합니다:

data.id

클라이언트 처리 프로세스

일반적인 프로세스:

读取待签名文件
      ↓
按照目标格式生成待签名数据
      ↓
计算摘要
      ↓
Base64 编码摘要
      ↓
POST /v1/codesign/sign
      ↓
获得 signature
      ↓
构造最终签名结构
      ↓
写回目标文件
      ↓
POST /v1/codesign/report-sign

주의 사항:

/v1/codesign/sign

하위 수준의 원격 프라이빗 키 서명만 담당합니다.

PE Authenticode, JAR, PDF 또는 기타 파일 형식의 서명 구조를 구성하는 방법은 클라이언트가 대상 형식에 따라 자체적으로 처리합니다.

서명 결과 보고

인터페이스:

POST /v1/codesign/report-sign

클라이언트가 원격 서명 결과를 받은 후에도 이후 과정에서 실패가 발생할 수 있습니다. 예를 들면:

최종 서명 구조 생성 실패.
대상 파일 쓰기 실패.
로컬 파일 권한 오류.
이후 클라이언트 처리 예외 발생.

이 인터페이스를 사용하여 최종 처리 상태를 서버에 다시 전달할 수 있습니다.

요청 매개변수

{
  "id": "735985894427246592",
  "status": 1
}

参数：

필드	유형	필수	설명
`id`	string	예	`/v1/codesign/sign` 반환된 서명 레코드 ID
`status`	integer	예	클라이언트 최종 처리 상태

상태 값：

상태	설명
`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
}

서명 횟수

API 서명 횟수는 원격 서명 작업의 성공 여부를 기준으로 합니다.

다음의 경우:

HTTP 2xx
code == 0
data.signature 非空

동시에 성립하는 경우, 한 번의 성공적인 서명으로 간주합니다:

签名次数 +1

다음 상황에서는 서명 횟수가 차감되지 않습니다.

인증 실패.
매개변수 오류.
네트워크 요청 실패.
비즈니스 요청 실패.
서버에서 서명 내용을 성공적으로 반환하지 못한 경우.

특별히 유의해야 할 사항:

/v1/codesign/report-sign

단지 클라이언트의 최종 처리 상태만 보고하며, 새로운 서명 작업에 속하지 않으며 서명 횟수를 늘리거나 줄이지도 않습니다.

클라이언트가 원격 서명 결과를 성공적으로 받았더라도, 이후 로컬에서 파일을 쓰는 데 실패한 경우, 이전에 성공적으로 완료된 원격 개인 키 서명은 이미 서명 횟수 1회가 발생한 것입니다.

더 많은 횟수 계산 규칙은 참고 자료를 참조하십시오.

오류 처리

클라이언트는 다음을 각각 처리해야 합니다:

네트워크 오류.
HTTP 오류.
API 업무 오류.
클라이언트 로컬 처리 오류.

인증 실패

예:

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

확인해야 할 사항:

Access Key가 올바른지 확인합니다.
Access Secret이 올바른지 확인합니다.
요청에 Authorization Header가 올바르게 포함되어 있는지 확인합니다.

매개변수 오류

예:

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

중점적으로 확인해야 합니다:

code 이(가) 올바른지.
digest 이(가) 올바른 Base64인지.
algorithm 이(가) 요약과 일치하는지.
padding 이(가) PKCS1 인지.

클라이언트는 고정된 다음 사항에 의존해서는 안 됩니다:

message

문자열 실행 프로그램 로직.

비즈니스 처리는 상태 코드와 인터페이스 계약을 우선적으로 따라야 합니다.

시간 초과와 재시도

원격 서명 인터페이스를 호출할 때는 합리적인 네트워크 시간 초과를 설정해야 합니다.

재시도가 필요할 때는 특히 다음 사항에 주의해야 합니다:

签名接口不是普通查询接口

클라이언트가 네트워크 이상으로 응답을 받지 못했다고 해서 서버가 서명을 완료하지 않았다는 의미는 아닙니다.

따라서 자동 재시도 메커니즘을 설계할 때는 무제한 또는 무조건적으로 서명 요청을 반복해서 보내는 것을 피해야 합니다.

다음 항목을 각각 기록하는 것이 좋습니다.

요청 시작 시간.
대상 인증서 번호.
요약 식별자.
HTTP 상태.
비즈니스 상태 코드.
반환된 서명 레코드 ID.
클라이언트 최종 처리 상태.

로그에 전체 Access Secret을 기록하지 마십시오.

로그 및 감사

다음과 같은 필수 서명 컨텍스트를 기록하는 것이 좋습니다.

certificate code
platform
client version
hostname
filename
filesize
sign record id
result

对于：

digest
signature

이처럼 길이가 큰 데이터는 일반 로그에 전체를 기록하지 않는 것이 좋습니다.

기록할 수 있는 항목:

길이.
해시.
마스킹 처리된 앞뒤 일부.

파일 경로에도 사용자 이름, 프로젝트 이름 또는 내부 디렉터리 정보가 포함될 수 있으므로 실제 보안 요구 사항에 따라 마스킹 여부를 결정해야 합니다.

보안 참고 사항

API 통합 시 다음 원칙을 따르는 것이 좋습니다.

Access Secret은 프런트엔드 코드에 저장하지 않아야 합니다.
Access Secret을 Git 저장소에 커밋하지 않아야 합니다.
일반 로그에 전체 Authorization Header를 기록하지 마세요.
전체 Access Secret을 기록하지 마세요.
digest 및 signature에 대해 필요한 로그 마스킹을 수행하세요.
HTTPS를 통해 원격 서명 서비스를 호출하세요.
클라이언트는 HTTP 상태와 비즈니스 상태를 검증해야 합니다.
네트워크 요청에 적절한 시간 초과 및 재시도 정책을 설정하세요.

원격 코드 서명 API가 반환하는 것은 서명 결과이지 개인 키가 아닙니다.

코드 서명 개인 키는 항상 원격 HSM에 보관됩니다.

API 사용 시기

기존 통합 방식으로 요구 사항을 이미 충족한다면 일반적으로 해당 도구를 바로 사용하면 됩니다.

시나리오	권장 방식
EXE, DLL, MSI 등 파일 직접 서명	클라이언트 도구
Microsoft SignTool, Visual Studio 등 Windows 소프트웨어	Windows Provider
JAR 파일 서명	Java 통합
GitHub Actions, Electron Builder 등 자동 빌드	CI/CD 및 빌드 도구
서명 클라이언트 직접 개발	API
파일 형식 서명 절차 직접 구현	API
다이제스트와 서명 결과를 직접 제어해야 하는 경우	API

API는 하위 수준의 서명 절차를 제어해야 하는 개발자에게 더 적합합니다.

일반 파일에 코드 서명만 완료하면 되는 경우, 기존 클라이언트나 표준 Provider를 우선 사용하면 서명 파일 형식을 직접 처리해야 하는 작업량을 줄일 수 있습니다.

접속 주소​

신원 인증​

일반 요청 형식​

공통 응답 형식​

서명 인터페이스​

요청 매개변수​

다이제스트 알고리즘​

digest 형식​

padding​

extra​

서명 요청 예시​

서명 응답​

클라이언트 처리 프로세스​

서명 결과 보고​

요청 매개변수​

요청 예시​

성공 응답​

서명 횟수​

오류 처리​

인증 실패​

매개변수 오류​

시간 초과와 재시도​

로그 및 감사​

보안 참고 사항​

API 사용 시기​

접속 주소

신원 인증

일반 요청 형식

공통 응답 형식

서명 인터페이스

요청 매개변수

다이제스트 알고리즘

digest 형식

padding

extra

서명 요청 예시

서명 응답

클라이언트 처리 프로세스

서명 결과 보고

요청 매개변수

요청 예시

성공 응답

서명 횟수

오류 처리

인증 실패

매개변수 오류

시간 초과와 재시도

로그 및 감사

보안 참고 사항

API 사용 시기