临时密钥生成及使用指引

最近更新时间:2019-04-08 14:44:44

临时密钥

临时密钥是通过 CAM 云 API 提供的接口,获取到权限受限的密钥。
COS API 可以使用临时密钥计算签名,用于发起 COS API 请求。
COS API 请求使用临时密钥计算签名时,需要用到获取临时密钥接口返回的信息中三个字段,分别如下:

  • tmpSecretId
  • tmpSecretKey
  • sessionToken

使用临时密钥的优势

Web、iOS、Android 使用 COS 的场景时,通过固定密钥计算签名方式不能有效地控制权限,同时把永久密钥放到客户端代码中有极大的泄露风险。如若通过临时密钥方式,则可以方便、有效地解决权限控制问题。
例如,在申请临时密钥过程中,可以通过设置权限策略 policy 字段,限制操作和资源,将权限限制在指定的范围内。

有关 COS API 授权策略,请查看:

获取临时密钥

获取临时密钥,可以通过提供的 COS STS SDK 方式获取,也可以直接请求 STS 云 API 的方式获取。

注意:

举例使用的是 Java SDK ,需要在 GitHub 上获取 SDK 代码(版本号)。若提示找不到对应 SDK 版本号,请确认是否在 GitHub 上获取到对应版本的 SDK。

COS STS SDK

COS 针对 STS 提供了 SDK 和样例,目前已有 Java、Nodejs、PHP、Python 等多种语言的样例。
具体内容请参考 COS STS SDK。各个 SDK 的使用说明请参考 Github 上的 README 和样例

假设您使用的是 Java SDK,请先下载 Java SDK,然后运行如下获取临时密钥示例:

// 根据 github 提供的 maven 集成方法导入 java sts sdk 
import org.json.JSONObject; 
import com.tencent.cloud.CosStsClient;

public class Demo {
    public static void main(String[] args) {
        TreeMap<String, Object> config = new TreeMap<String, Object>();

        try {
            // 替换为您的 SecretId 
            config.put("SecretId", "AKIDHTVVaVR6e3");
            // 替换为您的 SecretKey
            config.put("SecretKey", "PdkhT9e2rZCfy6");

            // 临时密钥有效时长,单位是秒
            config.put("durationSeconds", 1800);

            // 换成您的 bucket
            config.put("bucket", "examplebucket-1250000000");
            // 换成 bucket 所在地区
            config.put("region", "ap-guangzhou");

            // 这里改成允许的路径前缀,可以根据自己网站的用户登录态判断允许上传的目录,例子:* 或者 doc/* 或者 picture.jpg
            config.put("allowPrefix", "*");

            // 密钥的权限列表。简单上传、表单上传和分片上传需要以下的权限,其他权限列表请看 https://cloud.tencent.com/document/product/436/31923
            String[] allowActions = new String[] {
                    // 简单上传
                    "name/cos:PutObject",
                    // 表单上传、小程序上传
                    "name/cos:PostObject",
                    // 分片上传
                    "name/cos:InitiateMultipartUpload",
                    "name/cos:ListMultipartUploads",
                    "name/cos:ListParts",
                    "name/cos:UploadPart",
                    "name/cos:CompleteMultipartUpload"
            };
            config.put("allowActions", allowActions);

            JSONObject credential = CosStsClient.getCredential(config);
            //成功返回临时密钥信息,如下打印密钥信息
            System.out.println(credential);
        } catch (Exception e) {
            //失败抛出异常
            throw new IllegalArgumentException("no valid secret !");
        }
    }
}

使用临时密钥访问 COS

COS API 使用临时密钥访问 COS 服务时,通过 x-cos-security-token 字段来传递临时 sessionToken ;通过临时 SecretIdSecretKey 来计算签名。

以 COS Java SDK 为例,使用临时密钥访问 COS 示例如下:

说明:

运行如下示例前,请先在 Github 项目 获取 Java SDK 安装包。

// 根据 github 提供的 maven 集成方式导入 cos xml java sdk
import com.qcloud.cos.*;

public class Demo {
    public static void main(String[] args) throws Exception {

        // 用户基本信息
        String tmpSecretId = "COS_SECRETID";   // 替换为您的 SecretId 
        String tmpSecretKey = "COS_SECRETKEY";  // 替换为您的 SecretKey
        String sessionToken = "Token";  // 替换为您的 Token

        // 1 初始化用户身份信息(secretId, secretKey)
        COSCredentials cred = new BasicCOSCredentials(tmpSecretId, tmpSecretKey);
        // 2 设置 bucket 区域,详情请参阅 COS 地域 https://cloud.tencent.com/document/product/436/6224
        ClientConfig clientConfig = new ClientConfig(new Region("ap-beijing"));
        // 3 生成 cos 客户端
        COSClient cosclient = new COSClient(cred, clientConfig);
        // bucket名需包含appid
        String bucketName = "examplebucket-1250000000";

        String key = "doc/picture.jpg";
        // 上传 object, 建议 20M 以下的文件使用该接口
        File localFile = new File("src/test/resources/text.txt");
        PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);

        // 设置 x-cos-security-token header 字段
        ObjectMetadata objectMetadata = new ObjectMetadata();
        objectMetadata.setSecurityToken(sessionToken);
        putObjectRequest.setMetadata(objectMetadata);

        try {
            PutObjectResult putObjectResult = cosclient.putObject(putObjectRequest);
            // 成功:putobjectResult 会返回文件的 etag
            String etag = putObjectResult.getETag();
        } catch (CosServiceException e) {
            //失败,抛出 CosServiceException
            e.printStackTrace();
        } catch (CosClientException e) {
            //失败,抛出 CosClientException
            e.printStackTrace();
        }

        // 关闭客户端
        cosclient.shutdown();

    }
}