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

例：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回の成功した署名と見なされます：

签名次数 +1

以下の場合、署名回数は消費されません：

認証失敗。
パラメータエラー。
ネットワークリクエスト失敗。
業務リクエスト失敗。
サーバーが署名内容を正常に返せなかった場合。

特に注意が必要な点：

/v1/codesign/report-sign

単にクライアントの最終処理状態を報告するものであり、新しい署名操作には該当せず、署名回数が増減することもありません。

たとえクライアントがリモート署名結果の取得に成功しても、その後ローカルでのファイル書き込みに失敗した場合、以前に正常に完了したリモート秘密鍵署名は既に署名回数を1回消費しています。

その他の計数ルールについては、参考资料を参照してください。

エラー処理

クライアントは以下のケースをそれぞれ処理する必要があります：

ネットワークエラー。
HTTP エラー。
API 業務エラー。
クライアントローカル処理エラー。

認証失敗

例：

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

確認すべき事項：

Access Key が正しいか。
Access Secret が正しいか。
リクエストに Authorization ヘッダーが正しく含まれているか。

パラメータエラー

例：

{
  "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 を使用するタイミング