第31章 密钥泄露报告 API
Secret reporting API
未公开发布
请注意,该 API 仅按个案开放。如需对接此 API,请联系 admin@pypi.org。
第三方通过该 API 与 PyPI 集成,以发现、识别并吊销意外公开的 API 令牌。目前以下合作伙伴向 PyPI 报告公开暴露的 API 令牌:
所有使用 API 令牌的 PyPI 用户默认已加入此服务,无需执行额外操作即可享受该权益。
该 API 供可能发现 PyPI API 令牌并希望向 PyPI 上报的第三方使用。
识别 PyPI 密钥格式
PyPI API 令牌是一个由前缀(pypi)、分隔符(-)以及表示用 PyMacaroon 序列化为 base64 的 Macaroon 的字符串组成的字符串:
pypi-[A-Za-z0-9-_]{85,}
该 base64 字符串长度不得少于 85 个字符。由于我们可能会向序列化的 Macaroon 添加任意附加条件(caveats),因此令牌长度可以任意长。
集成
PyPI 采用了 GitHub 密钥扫描上报模式。
公钥标识符与签名
PyPI 要求发往该 API 的每个请求包含两个请求头:
- 包含公钥标识符的请求头
- 使用对应密钥对原始消息体进行签名后生成的签名值所在的请求头
这些请求头的名称可以任意,应在集成时提供给 PyPI。它们将在每次请求中进行验证。
PyPI 假定签名为 ECDSA 签名,且摘要算法为 SHA-256。
公钥验证
PyPI 期望能够在一个集成时提供的 URL 处验证用于签署请求的公钥。该 URL 结构可以任意,但必须位于可信域名上。
集成方应准备提供 P-256/384/521 密钥,并仅使用 SHA-256(尽管 P-384 和 P-521 通常分别对应 SHA-384 和 SHA-512,但在此处不得使用)。
对该 URL 发起 GET 请求时,响应应返回一个 JSON 文档,其示例结构如下:
{
"public_keys": [
{
"key_identifier": "90a421169f0a406205f1563a953312f0be898d3c7b6c06b681aa86a874555f4a",
"key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9MJJHnMfn2+H4xL4YaPDA4RpJqUq\nkCmRCBnYERxZanmcpzQSXs1X/AljlKkbJ8qpVIW4clayyef9gWhFbNHWAA==\n-----END PUBLIC KEY-----\n",
"is_current": false
},
{
"key_identifier": "bcb53661c06b4728e59d897fb6165d5c9cda0fd9cdf9d09ead458168deb7518c",
"key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEYAGMWO8XgCamYKMJS6jc/qgvSlAd\nAjPuDPRcXU22YxgBrz+zoN19MzuRyW87qEt9/AmtoNP5GrobzUvQSyJFVw==\n-----END PUBLIC KEY-----\n",
"is_current": true
}
]
}
注意,提供多个密钥并非必需。在披露时,PyPI 不会接受未标记为当前有效(is_current: true)的密钥的响应。
路由
上报密钥
路由:POST /_/secrets/disclose-token
接受一个或多个任意 API 令牌的上报,并包含发现位置详情。消息体为 JSON 数组,包含一个或多个对象,每个对象代表一次密钥匹配。
每个密钥匹配对象的键包括:
- token:密钥匹配的值(必填)
- type:找到的令牌类型(必填)
- url:发现匹配的公开 URL(必填)
目前 type 的唯一有效值为 "pypi_api_token"。
可以附加其他字段,但会被忽略。
请求示例:
POST /_/secrets/disclose-token HTTP/1.1
Host: pypi.org
Some-Public-Key-Identifier: ...
Some-Public-Key-Signature: ...
[
{
"token": "pypi-NMIfyYncKcRALEXAMPLE...",
"type": "pypi_api_token",
"url": "https://github.com/octocat/Hello-World/blob/12345600b9cbe38a219f39a9941c9319b600c002/foo/bar.txt",
}
]
状态码:
- 204 No Content - 我们已确认收到请求,但不会评论处理结果。
- 400 Bad Request - 请求格式存在某种错误,我们无法处理该上报。响应体将包含更详细的错误信息。该令牌未被上报,应重新提交。