Signature 项目技术文档

1. 安装指南

环境要求

• Ruby 版本：请参考项目 Travis CI 状态页面，确保你的 Ruby 版本在支持列表中。
• Bundler：确保你已经安装了 Bundler，用于管理 Ruby 依赖。

安装步骤

1. 克隆项目仓库到本地：

   git clone https://github.com/mloughran/signature.git
   

2. 进入项目目录：

   cd signature
   

3. 安装依赖：

   bundle install
   

2. 项目的使用说明

客户端示例

以下是一个使用 Signature 库进行客户端请求签名的示例：

params       = {:some => 'parameters'}
token        = Signature::Token.new('my_key', 'my_secret')
request      = Signature::Request.new('POST', '/api/thing', params)
auth_hash    = request.sign(token)
query_params = params.merge(auth_hash)

HTTParty.post('http://myservice/api/thing', {
  :body => query_params
})

query_params 将会包含以下内容：

{
  :some           => "parameters",
  :auth_timestamp => 1273231888,
  :auth_signature => "28b6bb0f242f71064916fad6ae463fe91f5adc302222dfc02c348ae1941eaf80",
  :auth_version   => "1.0",
  :auth_key       => "my_key"
}

服务器端示例（Sinatra）

以下是一个使用 Signature 库进行服务器端请求验证的示例：

error Signature::AuthenticationError do |controller|
  error = controller.env["sinatra.error"]
  halt 401, "401 UNAUTHORIZED: #{error.message}\n"
end

post '/api/thing' do
  request = Signature::Request.new('POST', env["REQUEST_PATH"], params)
  # 如果请求验证失败，将抛出 Signature::AuthenticationError
  token = request.authenticate do |key|
    Signature::Token.new(key, lookup_secret(key))
  end

  # 处理你的业务逻辑
end

3. 项目API使用文档

Signature::Token

• new(key, secret): 创建一个新的 Token 对象，key 和 secret 是必需的参数。
• key: 返回 Token 的 key。
• secret: 返回 Token 的 secret。

Signature::Request

• new(method, path, params): 创建一个新的 Request 对象，method 是请求方法（如 POST），path 是请求路径，params 是请求参数。
• sign(token): 使用给定的 Token 对请求进行签名，返回一个包含签名信息的哈希。
• authenticate(&block): 验证请求的签名，如果验证失败，抛出 Signature::AuthenticationError。

4. 项目安装方式

通过 Bundler 安装

1. 在项目的 Gemfile 中添加以下内容：

   gem 'signature'
   

2. 运行 bundle install 安装依赖。

通过 RubyGems 安装

直接使用 gem 命令安装：

gem install signature

5. 开发指南

运行测试

在项目根目录下运行以下命令以执行测试：

bundle exec rspec spec/*_spec.rb

贡献代码

1. Fork 项目仓库。
2. 创建新的分支进行开发。
3. 提交 Pull Request 到主仓库。

6. 版权信息

该项目由 Martyn Loughran 于 2010 年创建，详细版权信息请参考 LICENSE 文件。