diff --git a/security/device_certificate/certmanager/include/cm_native_api.h b/security/device_certificate/certmanager/include/cm_native_api.h index 942df1710..549e5667d 100644 --- a/security/device_certificate/certmanager/include/cm_native_api.h +++ b/security/device_certificate/certmanager/include/cm_native_api.h @@ -4,7 +4,7 @@ * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * - * http://www.apache.org/licenses/LICENSE-2.0 + * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, @@ -12,27 +12,25 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - -/** - * @file cm_native_api.h - * - * @brief Defines the Certificate Manager APIs. - * - * @library libohcert_manager.so - * @kit DeviceCertificateKit - * @syscap SystemCapability.Security.CertificateManager - * @since 22 - */ - /** * @addtogroup CertManager * @{ * * @brief Describes the OpenHarmony Certificate Manager capabilities, including certificate and credential management - * operations, provided for applications. + * operations, provided for applications. * * @since 22 */ +/** + * @file cm_native_api.h + * + * @brief Declares the APIs used to obtain details of specific certificates. + * + * @library libohcert_manager.so + * @kit DeviceCertificateKit + * @syscap SystemCapability.Security.CertificateManager + * @since 22 + */ #ifndef CM_NATIVE_API_H #define CM_NATIVE_API_H @@ -43,22 +41,26 @@ extern "C" { #endif + /** - * @brief Get the detail of USB key certificate. - * - * @param keyUri Indicates the USB key certificate uri. - * @param ukeyInfo Indicates USB key certificate attribute information. - * @param certificateList Indicates the detail information of USB key certificate. - * @return {@link OH_CM_ErrorCode#OH_CM_SUCCESS} 0 - The operation is successful. - * {@link OH_CM_ErrorCode#OH_CM_HAS_NO_PERMISSION} 201 - Permission verification failed. - * {@link OH_CM_ErrorCode#OH_CM_CAPABILITY_NOT_SUPPORTED} 801 - Capability not supported. - * {@link OH_CM_ErrorCode#OH_CM_PARAMETER_VALIDATION_FAILED} 17500011 - Indicates that the - * input parameters validation failed. for example, the parameter format is incorrect or the value range is invalid. - * {@link OH_CM_ErrorCode#OH_CM_INNER_FAILURE} 17500001 - Internal error. Possible causes: - * 1. IPC communication failed; 2. Memory operation error; 3. File operation error. - * {@link OH_CM_ErrorCode#OH_CM_NOT_FOUND} 17500002 - Indicates that the certificate does not exist. - * {@link OH_CM_ErrorCode#OH_CM_ACCESS_UKEY_SERVICE_FAILED} 17500010 - Indicates that - * access USB key service failed. + * @brief Obtains the detail list of USB certificate credentials. + * + * @param keyUri Pointer to the URI that stores the USB certificate credentials, in string format. + * @param ukeyInfo Pointer to the property information of the USB certificate credential. + * @param certificateList Pointer to the USB certificate credential detail list obtained. + * @return {@link OH_CM_ErrorCode}: + * **OH_CM_SUCCESS = 0**: Operation successful. + * **OH_CM_HAS_NO_PERMISSION = 201**: Permission verification failed. + * **OH_CM_CAPABILITY_NOT_SUPPORTED = 801**: The device is not supported. + * **OH_CM_PARAMETER_VALIDATION_FAILED = 17500011**: Input parameter verification failed. Possible causes: + * 1. Incorrect parameter format. + * 2. Invalid parameter value range. + * **OH_CM_INNER_FAILURE = 17500001**: Internal error. Possible causes: + * 1. IPC failure. + * 2. Memory operation error. + * 3. File operation error. + * **OH_CM_NOT_FOUND = 17500002**: The certificate does not exist. + * **OH_CM_ACCESS_UKEY_SERVICE_FAILED = 17500010**: Failed to access the USB certificate credential. * @permission ohos.permission.ACCESS_CERT_MANAGER * @since 22 */ @@ -66,52 +68,60 @@ int32_t OH_CertManager_GetUkeyCertificate(const OH_CM_Blob *keyUri, const OH_CM_UkeyInfo *ukeyInfo, OH_CM_CredentialDetailList *certificateList); /** - * @brief Get the detail of application private certificate. - * - * @param keyUri Indicates the private certificate uri. - * @param certificate Indicates the detail information of private certificate. - * @return {@link OH_CM_ErrorCode#OH_CM_SUCCESS} 0 - The operation is successful. - * {@link OH_CM_ErrorCode#OH_CM_HAS_NO_PERMISSION} 201 - Permission verification failed. - * {@link OH_CM_ErrorCode#OH_CM_PARAMETER_VALIDATION_FAILED} 17500011 - Indicates that the input - * parameters validation failed. for example, the parameter format is incorrect or the value range is invalid. - * {@link OH_CM_ErrorCode#OH_CM_INNER_FAILURE} 17500001 - Internal error. Possible causes: - * 1. IPC communication failed; 2. Memory operation error; 3. File operation error. - * {@link OH_CM_ErrorCode#OH_CM_NOT_FOUND} 17500002 - Indicates that the certificate does not exist. + * @brief Obtains the details of a private certificate credential of a specific application. + * + * @param keyUri Pointer to the URI that stores the application's private certificate credentials, in string format. + * @param certificate Pointer to the details of the application's private credentials obtained. + * @return {@link OH_CM_ErrorCode}: + * **OH_CM_SUCCESS = 0**: Operation successful. + * **OH_CM_HAS_NO_PERMISSION = 201**: Permission verification failed. + * **OH_CM_PARAMETER_VALIDATION_FAILED = 17500011**: Input parameter verification failed. Possible causes: + * 1. Incorrect parameter format. + * 2. Invalid parameter value range. + * **OH_CM_INNER_FAILURE = 17500001**: Internal error. Possible causes: + * 1. IPC failure. + * 2. Memory operation error. + * 3. File operation error. + * **OH_CM_NOT_FOUND = 17500002**: The certificate does not exist. * @permission ohos.permission.ACCESS_CERT_MANAGER * @since 22 */ int32_t OH_CertManager_GetPrivateCertificate(const OH_CM_Blob *keyUri, OH_CM_Credential *certificate); /** - * @brief Get the detail of user public certificate. - * - * @param keyUri Indicates the private certificate uri. - * @param certificate Indicates the detail information of public certificate. - * @return {@link OH_CM_ErrorCode#OH_CM_SUCCESS} 0 - The operation is successful. - * {@link OH_CM_ErrorCode#OH_CM_HAS_NO_PERMISSION} 201 - Permission verification failed. - * {@link OH_CM_ErrorCode#OH_CM_PARAMETER_VALIDATION_FAILED} 17500011 - Indicates that the input - * parameters validation failed. for example, the parameter format is incorrect or the value range is invalid. - * {@link OH_CM_ErrorCode#OH_CM_INNER_FAILURE} 17500001 - Internal error. Possible causes: - * 1. IPC communication failed; 2. Memory operation error; 3. File operation error. - * {@link OH_CM_ErrorCode#OH_CM_NOT_FOUND} 17500002 - Indicates that the certificate does not exist. - * {@link OH_CM_ErrorCode#OH_CM_NO_AUTHORIZATION} 17500005 - The application is not authorized by the user. + * @brief Obtains the details of a public certificate credential of a specific user. + * + * @param keyUri Pointer to the URI that stores the user's public certificate credentials, in string format. + * @param certificate Pointer to the details of the user's public certificate credential obtained. + * @return {@link OH_CM_ErrorCode}: + * **OH_CM_SUCCESS = 0**: Operation successful. + * **OH_CM_HAS_NO_PERMISSION = 201**: Permission verification failed. + * **OH_CM_PARAMETER_VALIDATION_FAILED = 17500011**: Input parameter verification failed. Possible causes: + * 1. Incorrect parameter format. + * 2. Invalid parameter value range. + * **OH_CM_INNER_FAILURE = 17500001**: Internal error. Possible causes: + * 1. IPC failure. + * 2. Memory operation error. + * 3. File operation error. + * **OH_CM_NOT_FOUND = 17500002**: The certificate does not exist. + * **OH_CM_NO_AUTHORIZATION = 17500005**: The application is not authorized. * @permission ohos.permission.ACCESS_CERT_MANAGER * @since 22 */ int32_t OH_CertManager_GetPublicCertificate(const OH_CM_Blob *keyUri, OH_CM_Credential *certificate); /** - * @brief Destroys a credential detail list. - * - * @param certificateList Indicates the pointer to the credential detail list to destroy. + * @brief Destroys the certificate detail list. + * + * @param certificateList Pointer to the certificate credential detail list to be destroyed. * @since 22 */ void OH_CertManager_FreeUkeyCertificate(OH_CM_CredentialDetailList *certificateList); /** - * @brief Destroys a credential detail. - * - * @param certificate Indicates the pointer to the credential detail to destroy. + * @brief Destroys the certificate details. + * + * @param certificate Pointer to the certificate credential details to be destroyed. * @since 22 */ void OH_CertManager_FreeCredential(OH_CM_Credential *certificate); @@ -121,4 +131,4 @@ void OH_CertManager_FreeCredential(OH_CM_Credential *certificate); #endif /** @} */ -#endif /* CM_NATIVE_API_H */ \ No newline at end of file +#endif /* CM_NATIVE_API_H */ diff --git a/security/device_certificate/certmanager/include/cm_native_type.h b/security/device_certificate/certmanager/include/cm_native_type.h index 4b177d4ce..189b65f32 100644 --- a/security/device_certificate/certmanager/include/cm_native_type.h +++ b/security/device_certificate/certmanager/include/cm_native_type.h @@ -4,7 +4,7 @@ * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * - * http://www.apache.org/licenses/LICENSE-2.0 + * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, @@ -12,27 +12,25 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - -/** - * @file cm_native_type.h - * - * @brief Defines the structure and enumeration. - * - * @library libohcert_manager.so - * @kit DeviceCertificateKit - * @syscap SystemCapability.Security.CertificateManager - * @since 22 - */ - /** * @addtogroup CertManagerType * @{ * * @brief Defines the macros, enumerated values, data structures, - * and error codes used by OpenHarmony Certificate Manager APIs. + * and error codes used by OpenHarmony Certificate Manager APIs. * * @since 22 */ +/** + * @file cm_native_type.h + * + * @brief Provides the enums, structs, macros, and error codes used by **CertManager** APIs. + * + * @library libohcert_manager.so + * @kit DeviceCertificateKit + * @syscap SystemCapability.Security.CertificateManager + * @since 22 + */ #ifndef CM_NATIVE_TYPE_H #define CM_NATIVE_TYPE_H @@ -47,94 +45,92 @@ extern "C" { #define OH_CM_MAX_LEN_CERTIFICATE_CHAIN 24588 #define OH_CM_MAX_LEN_URI 256 -#define OH_CM_MAX_LEN_CERT_ALIAS 129 -#define OH_CM_MAX_LEN_TYPE_NAME 1025 +#define OH_CM_MAX_LEN_CERT_ALIAS 129 +#define OH_CM_MAX_LEN_TYPE_NAME 1025 /** - * @brief Enumerates the error codes. - * + * @brief Enumerates error codes. + * * @since 22 */ typedef enum { /** - * The operation is successful. + * Operation succeeded. */ OH_CM_SUCCESS = 0, /** - * Indicates that the application has no permission to call the API. + * Permission verification failed. */ OH_CM_HAS_NO_PERMISSION = 201, /** - * Capability not supported. + * Not supported by the device. */ OH_CM_CAPABILITY_NOT_SUPPORTED = 801, /** - * Indicates that internal error. Possible causes: 1. IPC communication failed; - * 2. Memory operation error; 3. File operation error. + * Internal error. Possible causes: 1. IPC failure. 2. Memory operation error. 3. File operation error. */ OH_CM_INNER_FAILURE = 17500001, /** - * Indicates that the certificate does not exist. + * The certificate does not exist. */ OH_CM_NOT_FOUND = 17500002, /** - * Indicates that the keystore is in an invalid format or the keystore password is incorrect. + * The keystore format is invalid or the keystore password is incorrect. */ OH_CM_INVALID_CERT_FORMAT = 17500003, /** - * Indicates that the number of certificates or credentials reaches the maximum allowed. + * The number of certificates or credentials reaches the upper limit. */ OH_CM_MAX_CERT_COUNT_REACHED = 17500004, /** - * Indicates that the application is not authorized by the user. + * The application is not authorized. */ OH_CM_NO_AUTHORIZATION = 17500005, /** - * Indicates that the device enters advanced security mode. + * The device enters the advanced security mode. */ OH_CM_DEVICE_ENTER_ADVSECMODE = 17500007, /** - * Indicates that the device does not support the specified certificate store path. + * The device does not support the specified certificate storage path. */ OH_CM_STORE_PATH_NOT_SUPPORTED = 17500009, /** - * Indicates that access USB key service failed. + * Failed to access the USB certificate credential. */ OH_CM_ACCESS_UKEY_SERVICE_FAILED = 17500010, /** - * Indicates that the input parameters validation failed. - * for example, the parameter format is incorrect or the value range is invalid. + * Parameter verification fails. For example, the parameter format or range is invalid. */ - OH_CM_PARAMETER_VALIDATION_FAILED = 17500011 + OH_CM_PARAMETER_VALIDATION_FAILED = 17500011, } OH_CM_ErrorCode; /** - * @brief Enumerates the certificate purpose. - * + * @brief Enumerates the certificate credential purposes. + * * @since 22 */ typedef enum { /** - * Indicates the default purpose. + * Default purpose, which is used for credential signing. */ OH_CM_CERT_PURPOSE_DEFAULT = 0, /** - * Indicates all certificate purpose, used for query certificates function. + * All purposes, which are used to query credential functionalities. */ OH_CM_CERT_PURPOSE_ALL = 1, /** - * Indicates certificate for signature. + * Signing purpose. */ OH_CM_CERT_PURPOSE_SIGN = 2, /** - * Indicates certificate for encrypt. + * Encryption purpose. */ - OH_CM_CERT_PURPOSE_ENCRYPT = 3 + OH_CM_CERT_PURPOSE_ENCRYPT = 3, } OH_CM_CertificatePurpose; /** - * @brief Defines the structure for storing data. - * + * @brief Defines a struct for a binary large object (BLOB). + * * @since 22 */ typedef struct { @@ -143,19 +139,19 @@ typedef struct { */ uint32_t size; /** - * Pointer to the memory in which the data is stored. + * Pointer to the memory in which the data is stored. */ uint8_t *data; } OH_CM_Blob; /** - * @brief Defines the structure for certificate detail of credential . - * + * @brief Defines a struct for the certificate credential details. + * * @since 22 */ typedef struct { /** - * Indicates whether the credential contains certificate data. + * Whether a certificate data exists. */ uint32_t isExist; /** @@ -167,58 +163,60 @@ typedef struct { */ char alias[OH_CM_MAX_LEN_CERT_ALIAS]; /** - * Indicates the uri of Credential. + * Indicates the uri of Credential. */ char keyUri[OH_CM_MAX_LEN_URI]; /** - * Indicates the number of certificates included in the credential. + * Number of certificates contained in the credential. */ uint32_t certNum; /** - * Indicates the number of key included in the credential. + * Number of keys contained in the credential. */ uint32_t keyNum; /** - * Indicates the certificate binary data which max length is defined by OH_CM_MAX_LEN_CERTIFICATE_CHAIN. + * Binary data of a credential. The value contains up to 20480 bytes. */ OH_CM_Blob credData; /** - * Indicates the certificate purpose. + * Purpose of a certificate credential. */ OH_CM_CertificatePurpose certPurpose; } OH_CM_Credential; /** - * @brief Defines credential detail list . - * + * @brief Defines a struct for the certificate credential detail list. + * * @since 22 */ typedef struct { /** - * Indicates the credential count. + * Number of certificate credential details. */ uint32_t credentialCount; /** - * Indicates the credential data. + * Indicates the credential data. */ OH_CM_Credential *credential; } OH_CM_CredentialDetailList; /** - * @brief Defines the USB key certificate attribute information. - * + * @brief Defines a struct for the USB certificate credential information. + * * @since 22 */ typedef struct { /** - * Indicates the purpose of certificate. + * Purpose of a certificate credential. */ OH_CM_CertificatePurpose certPurpose; } OH_CM_UkeyInfo; + + #ifdef __cplusplus } #endif /** @} */ -#endif /* CM_NATIVE_TYPE_H */ \ No newline at end of file +#endif /* CM_NATIVE_TYPE_H */