編譯構建
- 該工具基于Maven3編譯構建,請確認環境已安裝配置Maven3環境,并且版本正確
mvn -version
- 下載代碼,命令行打開文件目錄至developtools_hapsigner/hapsigntool,執行命令進行編譯打包
mvn package
- 編譯后得到二進制文件,目錄為: ./hap_sign_tool/target
開發指導
鴻蒙開發指導書:[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md
]
場景介紹
OpenHarmony系統內置密鑰庫文件,文件名稱為OpenHarmony.p12,內含根CA證書、中間CA證書、最終實體證書等信息,工具基于該密鑰庫文件對OpenHarmony應用進行簽名。
按照有無應用簽名證書可分為以下兩種場景:
- 無應用簽名證書場景: 開發者使用該工具對應用包簽名時,需按照簽名步驟從第一步生成應用簽名證書密鑰對依次完成應用簽名證書生成、profile文件簽名、應用簽名流程。
- 有應用簽名證書場景: 開發者可直接從簽名步驟第三步對profile文件進行簽名開始開發,使用應用簽名證書和包含對應密鑰的本地密鑰庫文件對應用進行簽名。
命令說明
- 輸出命令幫助信息。
-help # 輸出命令幫助信息(不輸入參數默認輸出命令幫助信息)
- 輸出版本信息。
-version # 輸出版本信息
- 生成密鑰對。
generate-keypair : 生成密鑰對 ├── -keyAlias # 密鑰別名,必填項 ├── -keyPwd # 密鑰口令,可選項 ├── -keyAlg # 密鑰算法,必填項,包括RSA/ECC ├── -keySize # 密鑰長度,必填項,RSA算法的長度為2048/3072/4096,ECC算法的長度NIST-P-256/NIST-P-384 ├── -keystoreFile # 密鑰庫文件,必填項,JKS或P12格式 ├── -keystorePwd # 密鑰庫口令,可選項
- 生成證書簽名請求。
generate-csr : 生成證書簽名請求 ├── -keyAlias # 密鑰別名,必填項 ├── -keyPwd # 密鑰口令,可選項 ├── -subject # 證書主題,必填項 ├── -signAlg # 簽名算法,必填項,包括SHA256withRSA / SHA384withRSA / SHA256withECDSA / SHA384withECDSA ├── -keystoreFile # 密鑰庫文件,必填項,JKS或P12格式 ├── -keystorePwd # 密鑰庫口令,可選項 ├── -outFile # 輸出文件,可選項,如果不填,則直接輸出到控制臺
- 生成根CA/中間CA證書。
generate-ca : 生成根CA/中間CA證書,如果密鑰不存在,一起生成密鑰 ├── -keyAlias # 密鑰別名,必填項 ├── -keyPwd # 密鑰口令,可選項 ├── -keyAlg # 密鑰算法,必填項,包括RSA/ECC ├── -keySize # 密鑰長度,必填項,RSA算法的長度為2048/3072/4096,ECC算法的長度NIST-P-256/NIST-P-384 ├── -issuer # 頒發者的主題,可選項,如果不填,表示根CA ├── -issuerKeyAlias # 頒發者的密鑰別名,可選項,如果不填,表示根CA ├── -issuerKeyPwd # 頒發者的密鑰口令,可選項 ├── -subject # 證書主題,必填項 ├── -validity # 證書有效期,可選項,默認為3650天 ├── -signAlg # 簽名算法,必填項,包括SHA256withRSA / SHA384withRSA / SHA256withECDSA / SHA384withECDSA ├── -basicConstraintsPathLen # 路徑長度,可選項,默認為0 ├── -keystoreFile # 密鑰庫文件,必填項,JKS或P12格式 ├── -keystorePwd # 密鑰庫口令,可選項 ├── -issuerKeystoreFile # 簽發者密鑰庫文件,可選項,JKS或P12格式 ├── -issuerKeystorePwd # 簽發者密鑰庫口令,可選項 ├── -outFile # 輸出文件,可選項,如果不填,則直接輸出到控制臺
- 生成應用調試/發布證書。
generate-app-cert : 生成應用調試/發布證書 ├── -keyAlias # 密鑰別名,必填項 ├── -keyPwd # 密鑰口令,可選項 ├── -issuer # 頒發者的主題,必填項 ├── -issuerKeyAlias # 頒發者的密鑰別名,必填項 ├── -issuerKeyPwd # 頒發者的密鑰口令,可選項 ├── -subject # 證書主題,必填項 ├── -validity # 證書有效期,可選項,默認為3650天 ├── -signAlg # 簽名算法,必填項,包括SHA256withECDSA / SHA384withECDSA; ├── -issuerKeystoreFile # 簽發者密鑰庫文件,可選項,JKS或P12格式 ├── -issuerKeystorePwd # 簽發者密鑰庫口令,可選項 ├── -keystoreFile # 密鑰庫文件,必填項,JKS或P12格式 ├── -keystorePwd # 密鑰庫口令,可選項 ├── -outForm # 輸出證書文件的格式,包括 cert / certChain,可選項,默認為certChain ├── -rootCaCertFile # outForm為certChain時必填,根CA證書文件 ├── -subCaCertFile # outForm為certChain時必填,中間CA證書文件 ├── -outFile # 輸出證書文件(證書或證書鏈),可選項,如果不填,則直接輸出到控制臺
- 生成profile調試/發布證書。
generate-profile-cert : 生成profile調試/發布證書 ├── -keyAlias # 密鑰別名,必填項 ├── -keyPwd # 密鑰口令,可選項 ├── -issuer # 頒發者的主題,必填項 ├── -issuerKeyAlias # 頒發者的密鑰別名,必填項 ├── -issuerKeyPwd # 頒發者的密鑰口令,可選項 ├── -subject # 證書主題,必填項 ├── -validity # 證書有效期,可選項,默認為3650天 ├── -signAlg # 簽名算法,必填項,包括SHA256withECDSA / SHA384withECDSA; ├── -issuerKeystoreFile # 簽發者密鑰庫文件,可選項,JKS或P12格式 ├── -issuerKeystorePwd # 簽發者密鑰庫口令,可選項 ├── -keystoreFile # 密鑰庫文件,必填項,JKS或P12格式 ├── -keystorePwd # 密鑰庫口令,可選項 ├── -outForm # 輸出證書文件的格式,包括 cert / certChain,可選項,默認為certChain ├── -rootCaCertFile # outForm為certChain時必填,根CA證書文件 ├── -subCaCertFile # outForm為certChain時必填,中間CA證書文件 ├── -outFile # 輸出證書文件(證書或證書鏈),可選項,如果不填,則直接輸出到控制臺
- 通用證書生成,可以生成自定義證書。
generate-cert : 通用證書生成,可以生成自定義證書 ├── -keyAlias # 密鑰別名,必填項 ├── -keyPwd # 密鑰口令,可選項 ├── -issuer # 頒發者的主題,必填項 ├── -issuerKeyAlias # 頒發者的密鑰別名,必填項 ├── -issuerKeyPwd # 頒發者的密鑰口令,可選項 ├── -subject # 證書主題,必填項 ├── -validity # 證書有效期,可選項,默認為1095天 ├── -keyUsage # 密鑰用法,必選項,包括digitalSignature, nonRepudiation, keyEncipherment, ├ dataEncipherment, keyAgreement, certificateSignature, crlSignature, ├ encipherOnly和decipherOnly,如果證書包括多個密鑰用法,用逗號分隔 ├── -keyUsageCritical # keyUsage是否為關鍵項,可選項,默認為是 ├── -extKeyUsage # 擴展密鑰用法,可選項,包括clientAuthentication,serverAuthentication, ├ codeSignature,emailProtection,smartCardLogin,timestamp,ocspSignature ├── -extKeyUsageCritical # extKeyUsage是否為關鍵項,可選項,默認為否 ├── -signAlg # 簽名算法,必填項,包括SHA256withRSA/SHA384withRSA/SHA256withECDSA/SHA384withECDSA ├── -basicConstraints # 是否包含basicConstraints,可選項,默認為否 ├── -basicConstraintsCritical # basicConstraints是否包含為關鍵項,可選項,默認為否 ├── -basicConstraintsCa # 是否為CA,可選項,默認為否 ├── -basicConstraintsPathLen # 路徑長度,可選項,默認為0 ├── -issuerKeystoreFile # 簽發者密鑰庫文件,可選項,JKS或P12格式 ├── -issuerKeystorePwd # 簽發者密鑰庫口令,可選項 ├── -keystoreFile # 密鑰庫文件,必填項,JKS或P12格式 ├── -keystorePwd # 密鑰庫口令,可選項 ├── -outFile # 輸出證書文件,可選項,如果不填,則直接輸出到控制臺
- profile文件簽名。
sign-profile : profile文件簽名 ├── -mode # 簽名模式,必填項,包括localSign,remoteSign ├── -keyAlias # 密鑰別名,必填項 ├── -keyPwd # 密鑰口令,可選項 ├── -profileCertFile # Profile簽名證書(證書鏈,順序為最終實體證書-中間CA證書-根證書),必填項 ├── -inFile # 輸入原始的模板Profile文件,文件為json格式,所在目錄為developtools_hapsigner/autosign/UnsgnedReleasedProfileTemplate.json,必填項 ├── -signAlg # 簽名算法,必填項,包括SHA256withECDSA / SHA384withECDSA ├── -keystoreFile # 密鑰庫文件,localSign模式時為必填項,JKS或P12格式 ├── -keystorePwd # 密鑰庫口令,可選項 ├── -outFile # 輸出簽名后的profile文件,p7b格式,必填項
- profile文件驗簽。
verify-profile : profile文件驗簽
├── -inFile # 已簽名的profile文件,p7b格式,必填項
├── -outFil # 驗證結果文件(包含驗證結果和profile內容),json格式,可選項;如果不填,則直接輸出到控制臺
- 應用包和調試工具簽名。
sign-app : 應用包和二進制工具簽名
├── -mode # 簽名模式,必填項,包括localSign,remoteSign,remoteResign
├── -keyAlias # 密鑰別名,必填項
├── -keyPwd # 密鑰口令,可選項
├── -appCertFile # 應用簽名證書文件(證書鏈,順序為實體證書-中間CA證書-根證書),必填項
├── -profileFile # 簽名后的Provision Profile文件名,profileSigned為1時為p7b格式,profileSigned為0時為json格式,應用包簽名必填項,二進制工具簽名選填
├── -profileSigned # 指示profile文件是否帶有簽名,1表示有簽名,0表示沒有簽名,默認為1。可選項
├── -inForm # 輸入的原始文件的格式,枚舉值:zip、elf或bin;zip應用包對應zip,二進制工具對應elf,bin應用包為bin,默認zip;可選項
├── -inFile # 輸入的原始文件,應用包、elf或bin文件,必填項
├── -signAlg # 簽名算法,必填項,包括SHA256withECDSA / SHA384withECDSA
├── -keystoreFile # 密鑰庫文件,localSign模式時為必填項,JKS或P12格式
├── -keystorePwd # 密鑰庫口令,可選項
├── -outFile # 輸出簽名后的包文件,必填項
├── -signCode # 是否啟用代碼簽名,1表示開啟代碼簽名,0表示關閉代碼簽名??蛇x項。默認對hap、hsp、hqf、elf開啟代碼簽名,通過參數配置為0關閉。
- 應用包和調試工具文件驗簽。
verify-app : 應用包和二進制工具文件驗簽
├── -inFile # 已簽名的文件,應用包、elf或bin文件,必填項
├── -outCertChain # 簽名的證書鏈文件,必填項
├── -outProfile # 應用包中的profile文件,必填項
├── -inForm # 輸入的原始文件的格式,枚舉值:zip、elf或bin;zip應用包對應zip,二進制工具對應elf,bin應用包為bin,默認zip;可選項
簽名步驟
對應用包簽名的完整步驟為:
- 生成應用簽名證書密鑰對
- 生成應用簽名證書
- 對profile文件進行簽名
- 對應用包進行簽名
注意事項:
- 步驟一中的密鑰對算法推薦使用ECC,出于安全性考慮,應用簽名暫不使用RSA算法。
- 建議將待簽名應用包、profile文件、密鑰庫文件OpenHarmony.p12、根CA證書、中間CA證書、簽名工具放在同一個目錄下,方便操作。
生成應用簽名證書密鑰對
調用密鑰對生成接口,生成簽名密鑰并保存到密鑰庫。
命令實例:java -jar hap-sign-tool.jar generate-keypair -keyAlias "oh-app1-key-v1" -keyAlg "ECC" -keySize "NIST-P-256" -keystoreFile "OpenHarmony.p12" -keyPwd "123456" -keystorePwd "123456"
說明:
請記錄下keyAlias、keyStorePwd和keyPwd的值,在后續生成應用簽名證書和對應用包進行簽名操作會使用到。
該命令的參數說明:
generate-keypair : 生成應用簽名證書密鑰對 ├── -keyAlias #用于生成應用簽名證書的密鑰別名,存于OpenHarmony.p12密鑰庫文件中,該參數必填 ├── -keyAlg #密鑰算法,推薦使用ECC,該參數必填 ├── -keySize #密鑰長度,ECC算法的長度NIST-P-256/NIST-P-384,該參數必填 ├── -keyStoreFile #密鑰庫文件,推薦使用提供的OpenHarmony.p12密鑰庫文件,該參數必填 ├── -keyStorePwd #密鑰庫口令,OpenHarmony.p12口令默認為“123456”,必填項 ├── -keyPwd #密鑰口令,可選項,該參數不填默認生成的密鑰對無口令
生成應用簽名證書
調用應用簽名證書生成接口,使用本地中間CA證書簽發應用簽名證書。
命令實例:java -jar hap-sign-tool.jar generate-app-cert -keyAlias "oh-app1-key-v1" -signAlg "SHA256withECDSA" -issuer "C=CN,O=OpenHarmony,OU=OpenHarmony Team,CN= OpenHarmony Application CA" -issuerKeyAlias "openharmony application ca" -subject "C=CN,O=OpenHarmony,OU=OpenHarmony Team,CN=OpenHarmony Application Release" -keystoreFile "OpenHarmony.p12" -subCaCertFile "subCA.cer" -rootCaCertFile "rootCA.cer" -outForm "certChain" -outFile "app1.pem" -keyPwd "123456" -keystorePwd "123456" -issuerKeyPwd "123456" -validity "365"
該命令的參數說明:
generate-app-cert:生成應用簽名證書 ├── -keyAlias # 用于生成應用簽名證書的密鑰別名,請與第一步生成密鑰對的密鑰別名-keyAlias保持一致 ├── -signAlg # 簽名算法,必填項,包括 SHA256withECDSA / SHA384withECDSA ├── -issuer # 頒發者主題,填寫已提供的中間CA證書主題,該參數必填且不能修改 ├── -issuerKeyAlias # 頒發者密鑰別名,填寫中間CA證書密鑰別名,該參數必填且不能修改 ├── -subject # 證書主題,請參照命令實例中內容保證順序不變,該參數必填 ├── -issuerKeyPwd # 頒發者密鑰口令,填寫中間CA證書密鑰口令,該參數必填,指定“123456”,不可修改 ├── -keystoreFile # 密鑰庫文件,指定使用提供的OpenHarmony.p12密鑰庫文件,該參數必填且不可修改 ├── -rootCaCertFile # 根CA證書文件,指定為已提供的根CA證書,該參數必填且不可修改 ├── -subCaCertFile # 中間CA證書文件,指定為已提供的中間CA證書,該參數必填且不可修改 ├── -outForm # 輸出證書文件格式,推薦使用certChain ├── -outFile # 可選項,建議填寫,不填則默認輸出到控制臺 ├── -keyPwd # 密鑰口令,可選項,為第一步生成的密鑰對口令 ├── -keystorePwd # 密鑰庫口令,默認為“123456” ├── -validity # 證書有效期,可選項,默認為3650天
對profile文件進行簽名
調用profile文件簽名接口,使用Profile簽名密鑰對profile文件進行簽名。
命令實例:java -jar hap-sign-tool.jar sign-profile -keyAlias "openharmony application profile release" -signAlg "SHA256withECDSA" -mode "localSign" -profileCertFile "OpenHarmonyProfileRelease.pem" -inFile "UnsgnedReleasedProfileTemplate.json" -keystoreFile "OpenHarmony.p12" -outFile "app1-profile.p7b" -keyPwd "123456" -keystorePwd "123456"
該命令的參數說明:
sign-profile:簽名profile文件 ├── -keyAlias # 生成profile證書的密鑰別名,該參數必填且不能修改 ├── -signAlg # 簽名算法,包括 SHA256withECDSA / SHA384withECDSA,該參數必填 ├── -mode # 簽名模式,目前僅支持localSign,該參數必填 ├── -profileCertFile # Profile簽名證書,指定已提供的profile證書文件,該參數必填且不可修改 ├── -inFile # 輸入原始的模板Profile文件,文件為json格式,所在目錄為developtools_hapsigner/autosign/UnsgnedReleasedProfileTemplate.json,該參數必填 ├── -keystoreFile # 密鑰庫文件,指定使用提供的OpenHarmony.p12密鑰庫文件,該參數必填且不可修改 ├── -outFile # 輸出簽名后的profile文件,p7b格式,該參數必填 ├── -keyPwd # 密鑰口令,OpenHarmony.p12中的口令默認“123456” ├── -keystorePwd # 密鑰庫口令,OpenHarmony.p12口令默認為“123456”
對應用包進行簽名
調用應用包簽名接口,使用應用簽名密鑰為應用包簽名。
命令實例:java -jar hap-sign-tool.jar sign-app -keyAlias "oh-app1-key-v1" -signAlg "SHA256withECDSA" -mode "localSign" -appCertFile "app1.pem" -profileFile "app1-profile.p7b" -inFile "app1-unsigned.zip" -keystoreFile "OpenHarmony.p12" -outFile "app1-signed.hap" -keyPwd "123456" -keystorePwd "123456"
說明 :
以下參數說明默認為無應用簽名證書場景,當開發場景為有應用簽名證書場景時,下列參數需要修改: -keyAlias:密鑰別名,填寫已有應用簽名證書對應的密鑰別名,參數必填。 -appCertFile:應用簽名證書,填寫已有的應用簽名證書,參數必填。 -keystoreFile:密鑰庫文件,填寫已有應用簽名證書對應的密鑰庫文件,參數必填。 -keyPwd:密鑰口令,填寫密鑰庫文件中對應密鑰的口令。 -keystorePwd:密鑰庫口令,填寫密鑰庫文件的密鑰口令。
該命令的參數說明:
sign-app:簽名應用包 ├── -keyAlias # 密鑰別名,為第一步生成的密鑰信息別名,該參數必填 ├── -signAlg # 簽名算法,包括 SHA256withECDSA / SHA384withECDSA,該參數必填 ├── -mode # 簽名模式,目前僅支持localSign,該參數必填 ├── -appCertFile # 應用簽名證書(證書鏈,順序為最終實體證書-中間CA證書-根證書),填寫第二步生成的應用簽名證書,該參數必填 ├── -profileFile # 簽名后的profile文件,p7b格式,填寫第三步中生成的profile文件,必填項 ├── -inFile # 輸入原始應用包文件,該參數必填 ├── -keystoreFile # 密鑰庫文件,請與步驟一中密鑰庫文件保持一致,該參數必填且不可修改 ├── -outFile # 輸出簽名后的包文件,必填項 ├── -keyPwd # 密鑰口令,與第一步生成的密鑰對口令保持一致 ├── -keystorePwd # 密鑰庫口令,與第一步的密鑰庫口令保持一致
常見問題
- 執行第二步生成應用簽名證書命令時,控制臺打印結果,無文件輸出。
- 現象描述
生成證書時,只在控制臺打印證書內容,無對應文件輸出。 - 可能原因
outFile參數中路徑不正確 和 '-outFile'中的'-'非英文格式。 - 解決辦法
檢查并修正outFile參數為正確路徑,'-outFile'中的'-'為英文格式
- 現象描述
- 執行第三步對profile文件進行簽名時,提示簽名失敗。
- 現象描述
現象分為以下幾種:
(1)執行命令后提示"SIGN_ERROR, code: 107. Details: Failed to verify signature: Wrong key usage"
(2)執行命令后提示"NOT_SUPPORT_ERROR, code: 105. Details: Profile cert 'resultprofile1.pem' must a cert chain"
(3)執行命令后提示"VERIFY_ERROR, code: 108. Details: Failed to verify signature: unable to find valid certification path to requested target"
- 可能原因
(1)profile簽名證書(最終實體證書)證書鏈順序不正確。
(2)profile簽名證書(最終實體證書)不是證書鏈。
(3)證書主題順序不正確 或者 生成應用簽名證書時“-issuerKeyAlias”參數填寫錯誤。 - 解決辦法
(1)檢查并修正證書鏈順序,只能正序或反序,不可亂序。
(2)檢查簽名時的最終實體證書是否為證書鏈。
(3)檢查證書主題順序是否正確,順序須為C、O、OU、CN。
- 現象描述
- 對應用包進行簽名時提示簽名錯誤。
- 現象描述
執行命令后提示:NOT_SUPPORT_ERROR, code: 105. Details: SignAlg params is incorrect, signature algorithms include SHA256withECDSA,SHA384withECDSA
。 - 可能原因
簽名算法不支持,signAlg參數填寫錯誤。 - 解決辦法
最終實體證書密鑰對推薦使用ECC生成,hap簽名算法修改為ECC對應的SHA256withECDSA,SHA384withECDSA。
- 現象描述
- 簽名應用包失敗,提示證書CN字段為空。
- 現象描述
執行命令后提示:error: Common name of certificate is empty!
。 - 可能原因
當前使用的應用包簽名證書,不包含CN字段,導致簽名失敗。 - 解決辦法
根據業界證書規范,應用包簽名證書的CN字段必須不為空,請重新生成格式正確的證書。
- 現象描述
審核編輯 黃宇
-
OpenHarmony
+關注
關注
25文章
3660瀏覽量
16154 -
鴻蒙OS
+關注
關注
0文章
188瀏覽量
4368
發布評論請先 登錄
相關推薦
評論