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만으로 서명 요청 성공을 판단하지 마세요.

서명 인터페이스

API:

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

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

{
  "algorithm": "SHA256"
}

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

digest 형식

digest은 다음이어야 합니다:

해시 원본 바이트 → Base64

아니요:

文件内容 Base64

아닙니다:

十六进制哈希字符串

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

padding

현재 고정 사용:

PKCS1

즉:

{
  "padding": "PKCS1"
}

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

추가

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 또는 기타 파일 형식에서 서명 구조를 구성하는 방법은 클라이언트가 대상 형식에 따라 자체적으로 처리합니다.

서명 결과 보고

API:

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
}

확인할 사항:

액세스 키가 올바른지 확인하세요.
액세스 시크릿이 올바른지 확인하세요.
요청에 인증 헤더가 올바르게 포함되어 있는지 확인하세요.

매개변수 오류

예:

{
  "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​

추가​

서명 요청 예시​

서명 응답​

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

서명 결과 보고​

요청 매개변수​

요청 예시​

성공 응답​

서명 횟수​

오류 처리​

인증 실패​

매개변수 오류​

시간 초과 및 재시도​

로그 및 감사​

보안 설명​

API 사용 시기​

접속 주소

신원 인증

일반 요청 형식

일반 응답 형식

서명 인터페이스

요청 매개변수

다이제스트 알고리즘

digest 형식

padding

추가

서명 요청 예시

서명 응답

클라이언트 처리 프로세스

서명 결과 보고

요청 매개변수

요청 예시

성공 응답

서명 횟수

오류 처리

인증 실패

매개변수 오류

시간 초과 및 재시도

로그 및 감사

보안 설명

API 사용 시기