C SDK:下载并校验安装包
本页内容
使用短期下载凭证取得指定版本,核对独立保存的预期摘要后再使用文件。
适用场景
需要在 Linux / POSIX 服务端下载并校验指定安装包时,使用 cloudsign_download_package。它根据短期凭证传输文件,核对大小与预期 SHA-256,成功后才保存目标文件。
开始前必须已有独立可信的预期摘要。DownloadReceipt 不返回安装包摘要,不能用本次下载后现算的值替代预期值。
前提条件
- 已完成 C SDK 入门,使用获准下载的长期 AccessKey。原包需要相应产品的 DownloadOriginal;企业签名包需要
enterprise:DownloadSigned。 - 准备准确的应用 ID、版本 ID 和包类型。签名包版本从原签名任务的
signed_version.id取得。 - 从自己的受信发布记录取得对应文件的 SHA-256,并配置允许访问的精确 HTTPS 文件传输域名。
- 目标父目录已存在,位于调用方控制的私有目录,目标文件名尚未使用。
操作步骤
- 核对应用、版本与
original/signed包类型,确认预期摘要属于这份文件。 - 用已保存的业务幂等键调用 申请安装包下载凭证,确认回执含可用 ticket。
- 将成功回执、预期摘要、允许访问的域名和目标路径交给下载助手。
- 只在助手返回 OK 后使用目标文件;无论成功失败,均按接口释放回执与客户端资源。
运行示例
配置 CLOUDSIGN_BASE_URL、长期 AccessKey 和本次申请的 CLOUDSIGN_IDEMPOTENCY_KEY;从受保护配置注入 CLOUDSIGN_STORAGE_ORIGIN 与 CLOUDSIGN_EXPECTED_SHA256。原包和签名包不能共用摘要。
命令行示例需要哪些配置
这些变量由自己的进程安全配置注入,不把 Secret 写进命令历史或源码。它们只配置客户端,不选择平台存储厂商。
| 变量 | 如何填写 |
|---|---|
CLOUDSIGN_BASE_URL | 网站 HTTPS 主域名 https://www.onesignios.com。 |
CLOUDSIGN_ACCESS_KEY_ID | 示例使用的长期 AccessKey ID。 |
CLOUDSIGN_ACCESS_KEY_SECRET | 同一组长期凭据的 Secret。 |
CLOUDSIGN_API_CA_FILE | 可选的 API CA 文件;默认使用系统 CA。 |
CLOUDSIGN_STORAGE_ORIGIN | 由独立可信配置确认的精确 HTTPS 文件传输来源,用于限制客户端可访问的目标。 |
CLOUDSIGN_STORAGE_CA_FILE | 可选的文件传输 CA 文件,不能用它关闭证书验证。 |
CLOUDSIGN_IDEMPOTENCY_KEY | 本次下载凭证申请已经持久保存的幂等键。 |
CLOUDSIGN_EXPECTED_SHA256 | 这份准确版本文件的独立可信 SHA-256。 |
cmake -S . -B build
cmake --build build -j2
./build/cloudsign_download_example "$APP_ID" "$VERSION_ID" signed /srv/my-app/private/release.ipa查看完整 download-example.c 源码
/* Trusted-server CLI: one explicit ticket issuance, then a verified storage GET. */
#include <cloudsign/openapi.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
static int hex_id(const char *text,char prefix,size_t digits){
if(!text||strlen(text)!=digits+(prefix?1:0)||(prefix&&*text++!=prefix))return 0;
for(size_t i=0;i<digits;++i)if(!((text[i]>='0'&&text[i]<='9')||(text[i]>='a'&&text[i]<='f')))return 0;
return 1;
}
static int env_copy(char *output,size_t capacity,const char *name,int required){
const char *value=getenv(name);if(!value||!*value)return !required;
size_t length=strlen(value);if(length>=capacity)return 0;memcpy(output,value,length+1);return 1;
}
int main(int argc,char **argv){
cloudsign_credentials keys={0};cloudsign_client *client=NULL;cloudsign_result *receipt=NULL;
cloudsign_downloaded saved;cloudsign_status status=CLOUDSIGN_INVALID_INPUT;int initialized=0,exit_code=1;
const char *sha=getenv("CLOUDSIGN_EXPECTED_SHA256"),*storage=getenv("CLOUDSIGN_STORAGE_ORIGIN");
const char *idem=getenv("CLOUDSIGN_IDEMPOTENCY_KEY"),*origin=getenv("CLOUDSIGN_BASE_URL");
if(argc!=5||!hex_id(argv[1],'A',32)||!hex_id(argv[2],'V',32)||(strcmp(argv[3],"original")&&strcmp(argv[3],"signed"))){
fputs("Usage: cloudsign_download_example APP_ID VERSION_ID original|signed DESTINATION\n",stderr);goto done;
}
if(!hex_id(sha,0,64)||!storage||!idem||!origin
||!env_copy(keys.access_key_id,sizeof(keys.access_key_id),"CLOUDSIGN_ACCESS_KEY_ID",1)
||!env_copy(keys.access_key_secret,sizeof(keys.access_key_secret),"CLOUDSIGN_ACCESS_KEY_SECRET",1))goto done;
status=cloudsign_global_init();if(status!=CLOUDSIGN_OK)goto done;initialized=1;
cloudsign_options api={.origin=origin,.credentials=&keys,.ca_file=getenv("CLOUDSIGN_API_CA_FILE"),.timeout_ms=15000};
status=cloudsign_client_create(&api,&client);cloudsign_credentials_clear(&keys);if(status!=CLOUDSIGN_OK)goto done;
char body[192];int length=snprintf(body,sizeof(body),"{\"version_id\":\"%s\",\"package_type\":\"%s\",\"duration_seconds\":60}",argv[2],argv[3]);
if(length<0||(size_t)length>=sizeof(body)){status=CLOUDSIGN_INVALID_INPUT;goto done;}
cloudsign_param path[]={{"app_id",argv[1]}};
cloudsign_request request={.path=path,.path_count=1,.body_json=body,.idempotency_key=idem};
status=cloudsign_create_download_ticket(client,&request,&receipt);if(status!=CLOUDSIGN_OK)goto done;
const char *allowed[]={storage};
cloudsign_download_options options={.app_id=argv[1],.version_id=argv[2],.package_type=argv[3],.expected_sha256=sha,
.allowed_origins=allowed,.allowed_origin_count=1,.ca_file=getenv("CLOUDSIGN_STORAGE_CA_FILE"),.total_timeout_ms=120000};
status=cloudsign_download_package(receipt,argv[4],&options,&saved);
if(status!=CLOUDSIGN_OK)goto done;
printf("%s %llu %s\n",cloudsign_result_request_id(receipt),(unsigned long long)saved.size_bytes,saved.sha256);exit_code=0;
done:
if(exit_code)fprintf(stderr,"%s %s; RequestId: %s\n",cloudsign_status_name(status),cloudsign_result_error_code(receipt),cloudsign_result_request_id(receipt));
cloudsign_result_free(receipt);cloudsign_client_free(client);cloudsign_credentials_clear(&keys);
if(initialized)cloudsign_global_cleanup();return exit_code;
}
确认结果
| 情况 | 怎样判断 | 下一步 |
|---|---|---|
| 退出 0 | 文件大小和 SHA-256 已校验,目标文件已保存。 | 读取返回的 size_bytes、sha256,再使用目标文件。 |
| 目标文件已存在 | 助手保留已有文件,不覆盖。 | 检查原文件,确需独立下载时选择新的目标路径。 |
| 退出 1 | 配置、申请、传输或校验失败。 | 按下面的错误分类处理,不能把临时文件当成已完成产物。 |
示例申请一次 60 秒凭证,下载预算为 120 秒。下载状态与原业务 API 的成功回执需要分别检查。
参数与详细规则
平台选择文件传输服务;这里配置的域名白名单用于限制客户端的网络访问范围,不是存储厂商或账号选择。
| 参数或对象 | 表示什么 | 使用要点 |
|---|---|---|
| expected_sha256 | 对应文件的 64 位小写摘要。 | 从独立受信记录取得,不沿用另一版本或原包摘要。 |
| allowed_origins | 允许客户端访问的精确 HTTPS 来源。 | 不从收到的 URL 自动推导信任。 |
| 目标路径 | 在私有目录下选择尚不存在的文件。 | 服务端返回的 file_name 不直接用作本地路径。 |
查看完整参数、内存管理与运行边界
| 配置 / 输出 | 说明 |
|---|---|
app_id / version_id / package_type | 来自调用方保存的业务状态,分别匹配凭证的 应用 ID、版本 ID 及 original / signed;远端 file_name 只作一致性检查,不作为本地路径。 |
expected_sha256 | 必须提供对应文件的 64 位小写摘要。来自受信发布清单;没有预期摘要时不能跳过验证。 |
allowed_origins | 1–16 个独立配置的精确 HTTPS 源,例如 https://packages.example.com;不支持通配符、IP 字面量、非 443 端口、路径或查询。DNS 和出口策略由接入服务控制。 |
total_timeout_ms / cancelled | 总预算 1000–600000 ms,可设同步取消回调。网络请求以剩余预算为上限;本地文件操作和回调不能被强制打断,返回后检查预算。 |
ca_file | 默认使用系统 CA;需要私有 CA 时从可信配置指定。最低 TLS 1.2,始终校验证书与主机名。 |
cloudsign_downloaded | 成功返回 size_bytes 和已验证 sha256。失败清空输出;返回状态属于本次下载,与原 API 回执的状态分开检查。 |
运行限制与错误处理
独立存储连接只发送凭证 GET,不携带 AccessKey、Token、API 签名头、Cookie、netrc 认证或隐式代理。拒绝重定向、非 200、Range 响应、压缩与冲突的长度 / 编码头。内容按块写入随机 0600 临时文件,大小限制为 1 字节–16 GiB,同时校验凭证大小和 SHA-256,不将整个安装包读入内存。传输开始前检查凭证有效期;开始后的传输仍受总预算限制。
目标父目录必须已存在、受调用方控制,且不可被组 / 其他用户写入。固定打开的目录后创建临时文件,完成校验和文件 fsync 后,使用硬链接原子创建原先不存在的目标;并发时已有文件或符号链接都会保留。文件系统须支持硬链接,不能退回覆盖写入。成功与失败均尝试清理临时文件;进程被强制终止后,由调用方清理自己的临时目录。
DownloadUnavailable 表示凭证已过期或幂等重放只剩 ticket=null;IntegrityError 表示大小 / 摘要不符;FileError 表示目录、目标冲突或写入失败;另有 InvalidInput、InvalidResponse、TransportError、DeadlineExceeded、Cancelled。存储 429 / 503 也不会自动重试或续票。不要记录签名 URL、凭证原文、Secret 或错误页面。
失败后如何继续
| 情况 | 怎样判断 | 下一步 |
|---|---|---|
| DownloadUnavailable | 短期凭证过期,或回执为 ticket=null。 | 先核对原申请;确需新凭证时保存新的业务幂等键再申请。 |
| IntegrityError / FileError | 大小或摘要不符,或目录、文件写入有问题。 | 停止使用文件,核对原版本、摘要及目标目录。 |
| TransportError / DeadlineExceeded / Cancelled | 下载未完成或本次等待已停止。 | 保留原业务记录;助手不会自动重试或续签凭证。 |
文件助手使用 Linux / POSIX 文件接口。其他系统的支持范围见源码包 README,收到 UnsupportedPlatform 时应停止本次文件操作。网络中断后先核对原记录,不自动开始另一项业务。