ApiAuth 技术文档

1. 安装指南

ApiAuth 是一个用于客户端和服务器端 HTTP 应用的 Ruby gem，它实现了与亚马逊 Web 服务相同的认证方法（HMAC-SHA2）。要安装 ApiAuth，请确保您的 Ruby 版本 >= 2.6，如果使用 Rails，请确保 Rails 版本 >= 6.0。

安装命令如下：

[sudo] gem install api-auth

请注意，gem 名称中的连字符是 api-auth，而不是下划线。

2. 项目的使用说明

ApiAuth 主要用于在客户端对请求进行签名，并在服务器端验证签名。它支持多种流行的 HTTP 客户端，如 Net::HTTP、ActionDispatch::Request、RestClient、Faraday 等。

2.1 客户端请求签名

假设您有一个客户端访问 ID 和密钥：

@access_id = "1044"
@secret_key = ApiAuth.generate_secret_key

使用 RestClient 进行 PUT 请求的示例：

headers = { 'X-Authorization-Content-SHA256' => "dWiCWEMZWMxeKM8W8Yuh/TbI29Hw5xUSXZWXEJv63+Y=",
  'Content-Type' => "text/plain",
  'Date' => "Mon, 23 Jan 1984 03:29:56 GMT"
}

@request = RestClient::Request.new(
    url: "/resource.xml?foo=bar&bar=foo",
    headers: headers,
    method: :put
)

对请求进行签名：

@signed_request = ApiAuth.sign!(@request, @access_id, @secret_key)

签名后，请求头中将添加 Authorization 字段，请求即可发送。

2.2 ActiveResource 客户端

ApiAuth 可以透明地保护您的 ActiveResource 通信，只需在 ActiveResource 类中添加一行配置：

class MyResource < ActiveResource::Base
  with_api_auth(access_id, secret_key)
end

这将自动为您的应用中的所有 ActiveResource 请求签名。

2.3 Faraday 客户端

ApiAuth 提供了 Faraday 中间件，用于为 Faraday 连接添加认证：

require 'faraday/api_auth'
Faraday.new do |f|
  f.request :api_auth, @access_id, @secret_key
end

请注意，中间件的顺序很重要，确保 api_auth 是最后一个。

3. 项目 API 使用文档

3.1 生成 API 密钥

您可以使用以下方法为客户端生成 Base64 编码的 API 密钥：

ApiAuth.generate_secret_key

3.2 验证请求

要验证请求是否真实，可以使用以下方法：

ApiAuth.authentic?(signed_request, secret_key)

默认情况下，authentic? 方法使用 Authorization 头中指定的摘要方法。如果需要强制使用其他摘要方法，可以传递 digest 参数：

ApiAuth.authentic?(signed_request, secret_key, :digest => 'sha256')

为了防止重放攻击，默认情况下，请求的有效期为 15 分钟。您可以通过 clock_skew 参数调整有效期：

ApiAuth.authentic?(signed_request, secret_key, :clock_skew => 60) # 1 分钟

3.3 获取客户端访问 ID

您可以从请求头中提取客户端的访问 ID：

ApiAuth.access_id(signed_request)

4. 项目安装方式

ApiAuth 的安装非常简单，只需使用以下命令：

[sudo] gem install api-auth

确保您的 Ruby 和 Rails 版本符合要求，并且 OpenSSL 配置正确。

总结

ApiAuth 是一个强大的工具，用于在客户端和服务器端之间进行安全的 HTTP 通信。通过简单的配置和 API 调用，您可以轻松地为请求签名并验证其真实性。希望本文档能帮助您更好地理解和使用 ApiAuth。