UFS 14 - UFS RPMB安全读写命令

UFS 1-UFS架构简介1
UFS 2 -UFS架构简介2
UFS 3 - UFS RPMB
UFS 4 - UFS Boot
UFS 5 - UFS UIC Layer: MIPI M-PHY
UFS 6 - UAP – SCSI Commands（1）
UFS 7 - UAP – SCSI Commands（2）
UFS 8 - UAP – SCSI Commands（3）
UFS 9 - UAP – SCSI Commands（4）
UFS 10 - UAP – SCSI Commands（5）
UFS 11 - UFS RPMB分区功能验证
UFS 12 - UAP – SCSI Commands（6）
UFS 13 - Logical Unit Management

1 SECURITY PROTOCOL IN/OUT Commands

SECURITY PROTOCOL IN command and SECURITY PROTOCOL OUT command defined in [SPC] are used to encapsulate and deliver data packets of any security protocol between host and device without interpreting, dis-assembling or re-assembly the data packets for delivery.
[SPC]中定义的SECURITY PROTOCOL IN命令和SECURITY PROTOCOL OUT命令用于在主机和设备之间封装和传递任何安全协议的数据包，而无需解释、分解或重新组装数据包进行传递。
The SECURITY PROTOCOL IN command and SECURITY PROTOCOL OUT command contain a SECURITY PROTOCOL field. A unique security protocol ID is assigned by T10 for JEDEC UFS application.
SECURITY PROTOCOL IN 命令和 SECURITY PROTOCOL OUT 命令包含 SECURITY PROTOCOL 字段。 T10 为 JEDEC UFS 应用程序分配了唯一的安全协议 ID。

• SECURITY PROTOCOL = ECh (JEDEC Universal Flash Storage)
• 安全协议 = ECh（JEDEC 通用闪存存储）

1.1 CDB format of SECURITY PROTOCOL IN/OUT commands

The RPMB well known logical unit shall support the following SECURITY PROTOCOL field values:
RPMB W-LUN应支持以下安全协议字段值：

• 00h: Security protocol information
• ECh: JEDEC Universal Flash Storage (security protocol ID assigned for JEDEC UFS application)
  Other values are invalid.
  SECURITY PROTOCOL IN/OUT commands shall consider the unique Security Protocol ID assigned to JEDEC UFS application as the only valid Security Protocol ID.
  安全协议输入/输出命令应将分配给 JEDEC UFS 应用程序的唯一安全协议 ID 视为唯一有效的安全协议 ID。
  When the SECURITY PROTOCOL field is set to ECh (i.e., the JEDEC Universal Flash Storage),
  当 SECURITY PROTOCOL 字段设置为 ECh（即 JEDEC 通用闪存存储）时，
• INC_512 bit shall be set to zero to specify that the ALLOCATION LENGTH or the TRANSFER LENGTH field expresses the number of bytes to be transferred.
• INC_512 位应设置为零，以指定分配长度或传输长度字段表示要传输的字节数。
• If the ALLOCATION LENGTH field in a SECURITY PROTOCOL IN command is not equal to an integer multiple of 512, then the command shall be terminated with CHECK CONDITION status.
• 如果 SECURITY PROTOCOL IN 命令中的 ALLOCATION LENGTH 字段不等于 512 的整数倍，则该命令应以 CHECK CONDITION 状态终止。
• If the TRANSFER LENGTH field in a SECURITY PROTOCOL OUT command is not equal to an integer multiple of 512, then the command shall be terminated with CHECK CONDITION status.
• 如果 SECURITY PROTOCOL OUT 命令中的 TRANSFER LENGTH 字段不等于 512 的整数倍，则该命令应以 CHECK CONDITION 状态终止。
• The SECURITY PROTOCOL SPECIFIC field specifies the RPMB Protocol ID.
• SECURITY PROTOCOL SPECIFIC 字段指定 RPMB 协议 ID。
  The RPMB Protocol ID indicates the RPMB region as defined in Table 12.11
  RPMB 协议 ID 指示如表 12.11 中定义的 RPMB 区域
  
  If the SECURITY PROTOCOL SPECIFIC field is set to an invalid value or the corresponding RPMB region is not enabled, then SECURITY PROTOCOL IN/OUT command shall be terminated with CHECK CONDITION status, with the sense key set to ILLEGAL REQUEST and the additional sense code set to INVALID FIELD IN CDB.
  如果安全协议特定字段设置为无效值或相应的 RPMB 区域未启用，则安全协议输入/输出命令应以检查条件状态终止，且检测密钥设置为非法请求并设置附加检测代码CDB 中的无效字段。
  Secure Write Protect Configuration Block write and Secure Write Protect Configuration Block read request are supported only by RPMB region 0.
  仅 RPMB 区域 0 支持安全写保护配置块写入和安全写保护配置块读取请求。
  As required by [SPC], the SECURITY PROTOCOL value of 00h (security protocol information) shall be supported if the SECURITY PROTOCOL IN command is supported by the device. The security protocol information security protocol (i.e., the SECURITY PROTOCOL field set to 00h in a SECURITY PROTOCOL IN command) is used to transfer security protocol related information from the logical unit.
  根据[SPC]的要求，如果设备支持 SECURITY PROTOCOL IN 命令，则应支持 SECURITY PROTOCOL 值 00h（安全协议信息）。安全协议信息安全协议（即，在 SECURITY PROTOCOL IN 命令中设置为 00h 的 SECURITY PROTOCOL 字段）用于从逻辑单元传输安全协议相关信息。
  When the SECURITY PROTOCOL field is set to 00h in a SECURITY PROTOCOL IN command, the two bytes SECURITY PROTOCOL SPECIFIC field shall contain a numeric value as defined in Table 12.11.
  当 SECURITY PROTOCOL IN 命令中的 SECURITY PROTOCOL 字段设置为 00h 时，两个字节的 SECURITY PROTOCOL SPECIFIC 字段应包含表 12.11 中定义的数值。
  

1.2 Supported security protocols list description

According to [SPC], if the SECURITY PROTOCOL field is set to 00h and the SECURITY PROTOCOL SPECIFIC field is set to 0000h in a SECURITY PROTOCOL IN command, the parameter data shall have the format shown in Table 12.13.
根据[SPC]，如果在 SECURITY PROTOCOL IN 命令中将 SECURITY PROTOCOL 字段设置为 00h 并且将 SECURITY PROTOCOL SPECIFIC 字段设置为 0000h，则参数数据应具有表 12.13 中所示的格式。

Security protocol information (00h) and the JEDEC Universal Flash Storage (ECh) are the only valid security protocol ID’s supported by the RPMB well known logical unit, therefore Table 12.13 shall be implemented as defined in Table 12.14.
安全协议信息（00h）和 JEDEC 通用闪存存储（ECh）是 RPMB 众所周知的逻辑单元支持的唯一有效安全协议 ID，因此表 12.13 应按照表 12.14 中的定义来实现。

1.3 Certificate data description

If the SECURITY PROTOCOL field is set to 00h and the SECURITY PROTOCOL SPECIFIC field is set to 0001h in a SECURITY PROTOCOL IN command, the parameter data shall have the format shown in Table 12.14.
如果在 SECURITY PROTOCOL IN 命令中将 SECURITY PROTOCOL 字段设置为 00h 并且将 SECURITY PROTOCOL SPECIFIC 字段设置为 0001h，则参数数据应具有表 12.14 中所示的格式。

The Device Server does not have a certificate to transfer, the CERTIFICATE LENGTH field shall be set to 0000h. therefore Table 12.15 shall be implemented as defined in Table 12.16.
设备服务器没有要传输的证书，证书长度字段应设置为 0000h。因此，表 12.15 应按照表 12.16 的定义执行。

2 CDB format of SECURITY PROTOCOL IN/OUT commands demo

2.1 SECURITY PROTOCOL OUT commands

2.1.1 ufs-utils中对UFS CDB的封装

在ufs-util工具中所使用的SECURITY PROTOCOL为ECh的SECURITY PROTOCOL OUT样例代码如下所示：

• unsigned char sec_out_cmd[SEC_PROTOCOL_CMD_SIZE] = { SECURITY_PROTOCOL_OUT, SEC_PROTOCOL_UFS, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0};代表安全写的命令字
• #define SEC_PROTOCOL_CMD_SIZE (12)安全协议的命令长度为12Byte
• #define SECURITY_PROTOCOL_OUT 0xb5安全写的操作码为B5h
• #define SEC_PROTOCOL_UFS (0xEC)UFS的安全协议为ECh

ufs-utils的相关资料可以参考UFS 11 - UFS RPMB分区功能验证

#define SEC_SPECIFIC_UFS_RPMB           (0x0001)
#define SEC_PROTOCOL_CMD_SIZE           (12)
#define SEC_PROTOCOL_UFS                (0xEC)
#define SECURITY_PROTOCOL_IN  0xa2
#define SECURITY_PROTOCOL_OUT 0xb5

int scsi_security_out(int fd, struct rpmb_frame *frame_in,
                unsigned int cnt, __u8 region, __u8 sg_type)
{
    
    
        int ret;
        __u32 trans_len = cnt * sizeof(struct rpmb_frame);
        __u16 sec_spec = (region << 8) | SEC_SPECIFIC_UFS_RPMB;
        unsigned char sec_out_cmd[SEC_PROTOCOL_CMD_SIZE] = {
    
     
                        SECURITY_PROTOCOL_OUT, SEC_PROTOCOL_UFS,
                        0, 0, 0, 0, 0, 0, 0, 0, 0, 0}; 

        if (fd < 0 || frame_in == NULL || cnt <= 0) {
    
    
                print_error("scsi sec_out cmd: wrong parameters");
                return ERROR;
        }                                                                                                                                                                                                          
        *(__u16 *)(sec_out_cmd + SEC_SPEC_OFFSET) = htobe16(sec_spec);
        *(__u32 *)(sec_out_cmd + SEC_TRANS_LEN_OFFSET) = htobe32(trans_len);

        printf(" request cmd: \r\n");
        for (int i = 0; i < SEC_PROTOCOL_CMD_SIZE; i++) {
    
    
                printf(" 0x%02x ", sec_out_cmd[i]);
        }
        printf("\r\n");

        ret = send_scsi_cmd(fd, sec_out_cmd, frame_in,
                        SEC_PROTOCOL_CMD_SIZE, trans_len,
                        SG_DXFER_TO_DEV, sg_type);

        return ret;
}

2.1.2 trusty os中对UFS CDB的封装

trusty os中按照struct sec_proto_cdb结构体去封装安全协议

• struct sec_proto_cdb in_cdb = {0xA2, 0xEC, 0x00, 0x01, 0x00, 0x00, 0, 0x00, 0x00};
• struct sec_proto_cdb out_cdb = {0xB5, 0xEC, 0x00, 0x01, 0x00, 0x00, 0, 0x00, 0x00};
  

/*
 * CDB format of SECURITY PROTOCOL IN/OUT commands
 * (JEDEC Standard No. 220D, Page 264)
 */
struct sec_proto_cdb {
    
    
    /*  
     * OPERATION CODE = A2h for SECURITY PROTOCOL IN command,
     * OPERATION CODE = B5h for SECURITY PROTOCOL OUT command.
     */
    uint8_t opcode;
    /* SECURITY PROTOCOL = ECh (JEDEC Universal Flash Storage) */
    uint8_t sec_proto;
    /*  
     * The SECURITY PROTOCOL SPECIFIC field specifies the RPMB Protocol ID.
     * CDB Byte 2 = 00h and CDB Byte 3 = 01h for RPMB Region 0.
     */
    uint8_t cdb_byte_2;
    uint8_t cdb_byte_3;
    /*  
     * Byte 4 and 5 are reserved.
     */
    uint8_t cdb_byte_4;
    uint8_t cdb_byte_5;
    /* ALLOCATION/TRANSFER LENGTH in big-endian */                                                                                                                                                                 
    uint32_t length;
    /* Byte 9 is reserved. */
    uint8_t cdb_byte_10;
    /* CONTROL = 00h. */
    uint8_t ctrl;
} __packed;

2.2 SECURITY PROTOCOL IN commands

SECURITY PROTOCOL IN commands的解析可以参考SECURITY PROTOCOL OUT commands。

#define SEC_SPECIFIC_UFS_RPMB           (0x0001)
#define SEC_PROTOCOL_CMD_SIZE           (12)
#define SEC_PROTOCOL_UFS                (0xEC)
#define SECURITY_PROTOCOL_IN  0xa2
#define SECURITY_PROTOCOL_OUT 0xb5

int scsi_security_in(int fd, struct rpmb_frame *frame, int cnt, __u8 region,
                __u8 sg_type)
{
    
    
        int ret;
        __u32 trans_len = cnt * sizeof(struct rpmb_frame);
        __u16 sec_spec = (region << 8) | SEC_SPECIFIC_UFS_RPMB;
        unsigned char sec_in_cmd[SEC_PROTOCOL_CMD_SIZE] = {
    
    
                        SECURITY_PROTOCOL_IN, SEC_PROTOCOL_UFS,
                        0, 0, 0, 0, 0, 0, 0, 0, 0, 0};

        printf("#whw# file:%s func:%s line:%d region:0x%x cnt:%d trans_len:%d\r\n", __FILE__, __func__, __LINE__, region, cnt, trans_len);
        WRITE_LOG("Start : %s\n", __func__);
        if (fd < 0 || frame == NULL || cnt <= 0) {
    
    
                print_error("scsi sec_in cmd: wrong parameters");
                return ERROR;
        }

        *(__u16 *)(sec_in_cmd + SEC_SPEC_OFFSET) = htobe16(sec_spec);
        *(__u32 *)(sec_in_cmd + SEC_TRANS_LEN_OFFSET) = htobe32(trans_len);

        printf(" request cmd: \r\n");                                                                                                                                                                              
        for (int i = 0; i < SEC_PROTOCOL_CMD_SIZE; i++) {
    
    
                printf(" 0x%02x ", sec_in_cmd[i]);
        }
        printf("\r\n");

        ret = send_scsi_cmd(fd, sec_in_cmd, frame, SEC_PROTOCOL_CMD_SIZE,
                trans_len, SG_DXFER_FROM_DEV, sg_type);

        return ret;
}