配置调试签名

针对开发调试场景，DevEco Studio为开发者提供了自动签名方案，帮助开发者高效进行调试。此外，也可以选择手动签名方式生成调试签名。

使用场景说明

• 自动签名仅用于调试场景，方便开发者进行应用调试。部分调试场景下必须使用手动签名：
  1. 当需要进行跨设备调试、跨应用交互调试、断网情况下调试或者多用户共同开发且需要共享密钥时，必须使用手动签名。
  2. 如果开发过程中使用到需要审批的权限时，例如：
     1. 使用部分不支持自动签名的受限开放权限时，必须使用手动签名。支持自动签名的ACL权限清单请参见自动签名支持的ACL权限。
     2. 需要华为业务方审核的权限时（例如华为账号一键登录等），必须使用手动签名。
  3. 若kit需要配置指纹，建议使用手动签名。
• 发布场景必须使用手动签名。

自动签名

DevEco Studio 6.0.0 Beta3及之前版本，自动签名未关联注册的应用。从DevEco Studio 6.0.0 Beta5版本开始，自动签名新增关联注册应用的方式，签名操作界面新增“Associate with registered application”选项。

• 关联注册应用的自动签名：与应用市场（AppGallery Connect，简称AGC）的应用绑定，可在DevEco Studio开通开放能力。
• 未关联注册应用的自动签名：未与应用市场的应用绑定，不支持在DevEco Studio开通开放能力。

约束与限制

• 关联注册应用进行签名仅支持中国境内（香港特别行政区、澳门特别行政区、中国台湾除外）。
• 元服务的自动签名属于关联注册应用进行签名，元服务自动签名仅支持中国境内（香港特别行政区、澳门特别行政区、中国台湾除外）。
• 使用自动签名前，请确保本地系统时间与北京时间（UTC/GMT+08:00）保持一致。如果不一致，将导致签名失败。

关联注册应用

操作步骤

1. 连接真机设备或模拟器，具体请参考使用本地真机运行应用/元服务或使用模拟器运行应用/元服务，真机连接成功后如下图所示：

   

   

   如果同时连接多个设备，则使用自动化签名时，会同时将这多个设备的信息写到证书文件中。

2. 进入File > Project Structure... > Project > Signing Configs界面，勾选“Associate with registered application”。如果未登录，请先点击Sign In进行登录。

   

   

   • 点击Team下拉框，可以切换团队账号。
   • 开始签名后，DevEco Studio根据Bundle name查询该团队在AGC上同包名的应用。若在AGC查询到应用，则进行自动签名；若在AGC未查询到应用或应用冲突，请根据提示信息修改后重新自动签名，具体修改请参考常见问题。

3. 点击Enable open capabilities，在DevEco Studio上开通开放能力。当前支持开通如下四种开放能力：Push Kit（推送服务）、Device status detection（应用设备状态检测）、Map Kit（地图服务）、Safety Detect（安全检测服务），应用根据需要进行勾选。

   

4. （可选）在配置文件中添加ACL权限信息，ACL权限清单请参考自动签名支持的ACL权限。

   在需要使用权限的模块的module.json5（Stage模型）/config.json（FA模型）文件中添加“requestPermissions”/“reqPermissions”字段，并在字段下添加对应的权限名等信息。以下示例为在Stage模型工程中增加"ohos.permission.ACCESS_DDK_USB"权限。

   {
     "module": {
       ...
       "requestPermissions": [{
         "name": "ohos.permission.ACCESS_DDK_USB",
       }],
       ...
     }
   }

   

   修改配置文件后点击OK，若应用已在AGC申请该权限则签名成功；若应用未申请该权限，会导致签名失败，点击Notice弹窗中"submit a permission request in AppGallery Connect"或"Submit"，跳转至AGC申请权限，然后再返回DevEco Studio界面重新签名。

   

   

   • 申请ACL前注意事项：
     • 在申请ACL权限前，请审视是否符合受限权限的使用场景。当前仅少量符合特殊场景的应用可在通过审批后，使用受限权限。申请方式请见申请使用受限权限。
     • 涉及受限权限的应用，在上架时，应用市场（AGC）将根据应用的使用场景审核是否可以使用对应的受限权限。如不符合，应用的上架申请将被驳回，审核方式请见发布HarmonyOS应用。
   • 申请ACL后Profile证书说明：
     • 在ACL权限申请审批完成前，可获得一个有效期较短的临时Profile证书，使应用完成签名。临时证书到期后，若申请仍未审批通过，签名时需再次申请和再次获取临时证书。
     • 在ACL权限申请审批完成后，可获取一个有效期较长的正式Profile证书。

5. 签名完成后，在本地生成密钥（.p12）、证书请求文件（.csr）、数字证书（.cer）及Profile文件（.p7b）。将鼠标悬停在Provisioning Profile: DevEco Managed Profile后，可查看证书有效期、包名（bundle name）、ACL权限（acl）、开放能力（capability）等信息；或进入工程级build-profile.json5文件，在“signingConfigs”下可查看到配置成功的签名信息。

未关联注册应用

HarmonyOS工程********按以下步骤操作：

1. 连接真机设备或模拟器，具体请参考使用本地真机运行应用/元服务或使用模拟器运行应用/元服务，真机连接成功后如下图所示：

   

   

   如果同时连接多个设备，则使用自动化签名时，会同时将这多个设备的信息写到证书文件中。

2. 进入File > Project Structure... > Project > Signing Configs界面，勾选“Automatically generate signature”即可完成签名。如果未登录，请先单击Sign In进行登录，然后自动完成签名。

   

3. （可选）在配置文件中添加ACL权限信息，ACL权限清单请参考自动签名支持的ACL权限。修改配置文件后，点击Ok。

   在需要使用权限的模块的module.json5（Stage模型）/config.json（FA模型）文件中添加“requestPermissions”/“reqPermissions”字段，并在字段下添加对应的权限名等信息，以在Stage模型工程中增加"ohos.permission.ACCESS_DDK_USB"权限为例。

   {
     "module": {
       ...
       "requestPermissions": [{
         "name": "ohos.permission.ACCESS_DDK_USB",
       }],
       ...
     }
   }

   

   

   • 在调试签名时，不会强校验配置文件中添加的ACL权限。
   • 涉及受限权限的应用，上架时，应用市场（AGC）将根据应用的使用场景审核是否可以使用对应的受限权限，如不符合，应用的上架申请将被驳回。在配置ACL权限前，请审视是否符合受限权限的使用场景。当前仅少量符合特殊场景的应用可在通过审批后，使用受限权限，申请方式请见申请使用受限权限。

4. 签名完成后，在本地生成密钥（.p12）、证书请求文件（.csr）、数字证书（.cer）及Profile文件（.p7b）。将鼠标悬停在Provisioning Profile: DevEco Managed Profile后，可查看证书有效期、包名（bundle name）、ACL权限（acl）、开放能力（capability）等信息；或进入工程级build-profile.json5文件，在“signingConfigs”下可查看到配置成功的签名信息。

OpenHarmony工程********按以下步骤操作：

1. 连接真机设备或模拟器，具体请参考使用本地真机运行应用/元服务或使用模拟器运行应用/元服务，真机连接成功后如下图所示：

   

2. 进入File > Project Structure... > Project > Signing Configs界面。仅勾选“Automatically generate signature”时，生成OpenHarmony签名；勾选“Support HarmonyOS”和“Automatically generate signature”时，生成HarmonyOS签名。如果未登录，请先单击Sign In进行登录。

   

   签名完成后，如下图所示。在本地生成密钥（.p12）、证书请求文件（.csr）、数字证书（.cer）及Profile文件（.p7b），数字证书在AGCt网站的“证书、APP ID和Profile”页签中可以查看。

   

   

   • OpenHarmony工程签名时，推荐使用HarmonyOS签名。因为OpenHarmony签名是Release签名，Release签名的应用不支持调试和打印debug日志等。此外，OpenHarmony签名可能会影响应用运行。
   • 如果同时连接多个设备，则使用自动化签名时，会同时将这多个设备的信息写到证书文件中。

手动签名

HarmonyOS应用/元服务通过数字证书（.cer文件）和Profile文件（.p7b文件）来保证应用/元服务的完整性。在申请数字证书和Profile文件前，需要通过DevEco Studio生成密钥（存储在格式为.p12的密钥库文件中）和证书请求文件（.csr文件）。

基本概念

• 密钥：格式为.p12，包含非对称加密中使用的公钥和私钥，存储在密钥库文件中，公钥和私钥用于数字签名和验证。
• 证书请求文件：格式为.csr，全称为Certificate Signing Request，包含密钥对中的公钥和通用名称、组织名称、组织单位等信息，用于向AppGallery Connect申请数字证书。
• 数字证书：格式为.cer，由华为AppGallery Connect颁发。
• Profile文件：格式为.p7b，包含HarmonyOS应用/元服务的包名、数字证书信息、描述应用/元服务允许申请的证书权限列表，以及允许应用/元服务调试的设备列表（如果应用/元服务类型为Release类型，则设备列表为空）等内容，每个应用/元服务包中均必须包含一个Profile文件。

生成密钥和证书请求文件

DevEco Studio 6.1.0 Beta2及之后版本

1. 在主菜单栏单击Build > Generate Key and CSR。

2. 在Generate Key and CSR界面，可以单击Select an existing key选择已有的密钥库文件（存储有密钥的.p12文件），若没有密钥库文件则进行填写。下面以新创建密钥库文件为例进行说明。

   

3. 在Generate Key窗口，填写密钥库信息后，点击Next。

   • Keystore Name：填写p12文件名称，仅允许包含字母、数字、下划线（_）、中划线（-）、句号（.）。

   • Select file save path：设置密钥库文件存储路径。

   • Key store password：设置密钥库密码，必须由大写字母、小写字母、数字和特殊符号中的两种以上字符的组合，长度至少为8位。请记住该密码，后续签名配置需要使用。

   • Confirm password：再次输入密钥库密码。

   • Alias：密钥别名。请记住该别名，后续签名配置需要使用。

   • Advance Setting：密钥库文件的高级设置，选填。

     • ****Validity(years)：****选填，证书有效期，建议设置为25年及以上，覆盖应用/元服务的完整生命周期。
     • ****First and last name：****选填，通用名称，可填写应用名称或开发者姓名等。
     • Organizational unit：选填，组织单位，可填写部门名称或个人开发等。
     • ****Organization：****选填，组织名称，可填写公司全称或开发者姓名等。
     • ****City or locality：****选填，城市或地区。
     • ****State or province：****选填，州或省。
     • ****Country code(XX)：****选填，国家码。

     

     First and last name、Organizational unit、Organization、City or locality、State or province填写要求小于64个字符，不可使用双引号（"）、斜杠（\）、反引号（`）。

   

4. 在Generate Certificate Request File (CSR)窗口，设置CSR文件名和CSR文件存储路径后，点击Finish。

   • CSR File Name：填写CSR文件名称，仅允许包含字母、数字、下划线（_）、中划线（-）、句号（.）。
   • Select file save path：设置CSR文件存储路径。

   

5. 创建CSR文件成功，可以在存储路径下获取生成的密钥库文件（.p12）、证书请求文件（.csr）。

   

DevEco Studio 6.1.0 Beta2之前版本

1. 在主菜单栏单击Build > Generate Key and CSR。

   

   如果本地已有对应的密钥，无需新生成密钥，可以在Generate Key界面中单击下方的Skip跳过密钥生成过程，直接使用已有密钥生成证书请求文件。

2. 在Key store file中，可以单击Choose Existing选择已有的密钥库文件（存储有密钥的.p12文件）；如果没有密钥库文件，单击New进行创建。下面以新创建密钥库文件为例进行说明。

   

3. 在Create Key Store窗口，填写密钥库信息后，单击OK。

   • Key store file：设置密钥库文件存储路径，并填写p12文件名。
   • Password：设置密钥库密码，必须由大写字母、小写字母、数字和特殊符号中的两种以上字符的组合，长度至少为8位。请记住该密码，后续签名配置需要使用。
   • Confirm password：再次输入密钥库密码。

   

4. 在Generate Key and CSR界面，继续填写密钥信息后，单击Next。

   • Alias：必填，别名，用于标识密钥名称。请记住该别名，后续签名配置需要使用。
   • Password：必填，密码，与密钥库密码保持一致，无需手动输入。
   • ****Validity(years)：****选填，证书有效期，建议设置为25年及以上，覆盖应用/元服务的完整生命周期。
   • ****First and last name：****选填，通用名称，可填写应用名称或开发者姓名等。
   • Organizational unit：选填，组织单位，可填写部门名称或个人开发等。
   • ****Organization：****选填，组织名称，可填写公司全称或开发者姓名等。
   • ****City or locality：****选填，城市或地区。
   • ****State or province：****选填，州或省。
   • ****Country code(XX)：****选填，国家码。

   

   First and last name、Organizational unit、Organization、City or locality、State or province要求：字符长度为（0，64），且不可使用双引号（"）、斜杠（\）、反引号（`）。

   

5. 在Generate Key and CSR界面，设置CSR文件存储路径和CSR文件名。

   

6. 单击Finish，创建CSR文件成功，可以在存储路径下获取生成的密钥库文件（.p12）、证书请求文件（.csr）和material文件夹（存放密码加密材料等）。

   

申请调试证书

在AGC中申请和下载调试证书，具体请参考申请调试证书。

如您未在AGC中注册该应用，申请前需要在AGC中注册，具体请参考创建HarmonyOS应用。

申请调试Profile文件和添加权限信息

1. （可选）如需使用ACL权限，在AGC中申请ACL权限。同时，在DevEco Studio配置文件中添加权限信息。

   

   • ACL权限申请仅支持中国境内（香港特别行政区、澳门特别行政区、中国台湾除外）。
   • 若应用因特殊场景要求使用受限开放权限，请务必在此步骤进行申请，否则应用将在审核时被驳回。受限开放权限可申请的特殊场景请参考受限开放权限。
   • 确保应用申请受限开放权限时提供的场景和功能信息准确。如果应用内使用的受限开放权限超出您申请的范围，或申请权限后使用的功能和场景超出可使用的范围，将影响应用上架。

   在需要使用权限的模块的module.json5（Stage模型）/config.json（FA模型）文件中添加“requestPermissions”/“reqPermissions”字段，并在字段下添加对应的权限名等信息，以在Stage模型工程中增加"ohos.permission.ACCESS_DDK_USB"权限为例。

   {
     "module": {
       ...
       "requestPermissions": [{
         "name": "ohos.permission.ACCESS_DDK_USB",
       }],
       ...
     }
   }

   

2. 在AGC中申请和下载Profile文件，具体请参考申请调试Profile。

配置签名信息

1. 连接真机设备，确保DevEco Studio与真机设备已连接。

   

2. 在File > Project Structure > Project > Signing Configs窗口中，取消勾选“Automatically generate signature”和“Associate with registered application”，分别配置密钥（.p12文件）、Profile（.p7b文件）和数字证书（.cer文件）的路径等信息，配置完毕后点击Apply。

   • Store file：选择密钥库文件，文件后缀为.p12，该文件为生成密钥和证书请求文件中生成的.p12文件。
   • Store password：输入密钥库密码，该密码与生成密钥和证书请求文件中填写的密钥库密码保持一致。
   • Key alias：输入密钥的别名信息，与生成密钥和证书请求文件中填写的别名保持一致。
   • Key password：输入密钥的密码，与生成密钥和证书请求文件中填写的Store Password保持一致。
   • Sign alg：签名算法，固定为SHA256withECDSA。
   • Profile file：选择申请调试Profile文件和添加权限信息中生成的Profile文件，文件后缀为.p7b。
   • Certpath file：选择申请调试证书中生成的数字证书文件，文件后缀为.cer。

   

   • Store file，Profile file，Certpath file三个字段支持配置相对路径，以项目根目录为起点，配置文件所在位置的路径名称。
   • 密钥库文件、密钥库密码、密钥别名、密钥密码、Profile文件、数字证书文件必须配套使用，否则会导致签名失败。若失败请根据报错信息进行修改，再进行签名。

   

   配置完成后，将鼠标悬停在Provisioning Profile: DevEco Manage Profile后，可查看证书有效期、包名（bundle name）、企业名称（common name）、ACL权限（acl）、开放能力（capability）相关信息；或者进入工程级build-profile.json5文件，在“signingConfigs”下可查看到配置成功的签名信息。

   

3. 进入工程级build-profile.json5文件，在“signingConfigs”下可查看到配置成功的签名信息，点击右上角的“Run”按钮运行应用/元服务。

   

附录

自动签名支持的ACL权限

自动签名当前支持申请的ACL权限的清单如下所示。执行操作步骤后，DevEco Studio将校验当前配置的ACL权限是否在以下列表中，然后通过应用市场（AGC）申请对应的Profile文件，用于签名打包，从而避免繁琐的手动签名步骤。

从DevEco Studio 6.1.0 Beta2版本开始，自动签名支持配置的ACL权限具体参考受限开放权限。

6.0.2 Beta********1

新增权限

• ohos.permission.SUBSCRIBE_NOTIFICATION
• ohos.permission.ACCESS_USER_FULL_DISK
• ohos.permission.CUSTOM_SCREEN_RECORDING
• ohos.permission.GET_IP_MAC_INFO

6.0.1 Release****（6.0.1.260）****

新增权限

• ohos.permission.SET_SYSTEMSHARE_APPLAUNCHTRUSTLIST
• ohos.permission.HOOK_KEY_EVENT
• ohos.permission.WEB_NATIVE_MESSAGING

6.0.0 Beta3

新增权限

• ohos.permission.CUSTOMIZE_SAVE_BUTTON
• ohos.permission.GET_ABILITY_INFO
• ohos.permission.LINKTURBO
• ohos.permission.GET_WIFI_LOCAL_MAC
• ohos.permission.GET_ETHERNET_LOCAL_MAC
• ohos.permission.USE_FLOAT_BALL
• ohos.permission.READ_LOCAL_DEVICE_NAME
• ohos.permission.ACCESS_NET_TRACE_INFO
• ohos.permission.KEEP_BACKGROUND_RUNNING_SYSTEM
• ohos.permission.atomicService.MANAGE_STORAGE
• ohos.permission.MANAGE_SCREEN_TIME_GUARD

5.1.0 Release

新增权限

• ohos.permission.ACCESS_DDK_USB_SERIAL
• ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL
• ohos.permission.USE_FRAUD_APP_PICKER

5.0.5 Release

新增权限

• ohos.permission.kernel.DISABLE_GOTPLT_RO_PROTECTION
• ohos.permission.MANAGE_APN_SETTING

5.0.3 Release

新增权限

• ohos.permission.READ_WRITE_USB_DEV
• ohos.permission.USE_FRAUD_CALL_LOG_PICKER
• ohos.permission.USE_FRAUD_MESSAGES_PICKER
• ohos.permission.ACCESS_DISK_PHY_INFO
• ohos.permission.SET_PAC_URL
• ohos.permission.PERSONAL_MANAGE_RESTRICTIONS
• ohos.permission.START_PROVISIONING_MESSAGE
• ohos.permission.PRELOAD_FILE
• ohos.permission.kernel.ALLOW_WRITABLE_CODE_MEMORY
• ohos.permission.kernel.DISABLE_CODE_MEMORY_PROTECTION
• ohos.permission.kernel.ALLOW_EXECUTABLE_FORT_MEMORY
• ohos.permission.GET_WIFI_PEERS_MAC
• ohos.permission.READ_WRITE_DESKTOP_DIRECTORY
• ohos.permission.MANAGE_PASTEBOARD_APP_SHARE_OPTION
• ohos.permission.MANAGE_UDMF_APP_SHARE_OPTION
• ohos.permission.READ_WRITE_USER_FILE

5.0.0 Release

支持权限

• ohos.permission.READ_CONTACTS
• ohos.permission.WRITE_CONTACTS
• ohos.permission.READ_AUDIO
• ohos.permission.WRITE_AUDIO
• ohos.permission.READ_IMAGEVIDEO
• ohos.permission.READ_PASTEBOARD
• ohos.permission.WRITE_IMAGEVIDEO
• ohos.permission.ACCESS_DDK_USB
• ohos.permission.ACCESS_DDK_HID
• ohos.permission.SYSTEM_FLOAT_WINDOW
• ohos.permission.FILE_ACCESS_PERSIST
• ohos.permission.INPUT_MONITORING
• ohos.permission.INTERCEPT_INPUT_EVENT
• ohos.permission.SHORT_TERM_WRITE_IMAGEVIDEO