General Query (C/C++)

From API version 22, huksExternalCrypto provides the general query API. This API can be used to obtain general property information from a UKey device. For details about the scenarios, see General Query Overview and Specifications.

Linking the Dynamic Library in the CMake Script

target_link_libraries(entry PUBLIC libhuks_ndk.z.so libhuks_external_crypto.z.so)

How to Develop

Obtaining properties

Construct resourceId and propertyId, and call OH_Huks_OpenResource to open the resource.
Initialize the parameter set: Construct the parameter set paramSet by using OH_Huks_InitExternalCryptoParamSet, OH_Huks_AddExternalCryptoParams, and OH_Huks_BuildExternalCryptoParamSet.
Call OH_Huks_GetProperty to obtain the property information.
Call OH_Huks_GetExternalCryptoParam to extract the result from the output parameter set.
Call OH_Huks_FreeExternalCryptoParamSet to release the parameter set resource.

Development Cases

#include "huks/native_huks_external_crypto_api.h"
#include "huks/native_huks_external_crypto_type.h"
#include "napi/native_api.h"
#include <string.h>

OH_Huks_Result InitExternalCryptoParamSet(
    OH_Huks_ExternalCryptoParamSet **paramSet,
    const OH_Huks_ExternalCryptoParam *params,
    uint32_t paramCount)
{
    OH_Huks_Result ret = OH_Huks_InitExternalCryptoParamSet(paramSet);
    if (ret.errorCode != OH_HUKS_SUCCESS) {
        return ret;
    }
    ret = OH_Huks_AddExternalCryptoParams(*paramSet, params, paramCount);
    if (ret.errorCode != OH_HUKS_SUCCESS) {
        OH_Huks_FreeExternalCryptoParamSet(paramSet);
        return ret;
    }
    ret = OH_Huks_BuildExternalCryptoParamSet(paramSet);
    if (ret.errorCode != OH_HUKS_SUCCESS) {
        OH_Huks_FreeExternalCryptoParamSet(paramSet);
        return ret;
    }
    return ret;
}

static napi_value GetProperty(napi_env env, napi_callback_info info) 
{
    /* 1. Assume that the resource specified by resourceId has been opened. */
    const char *resourceIdStr = "{\"providerName\":\"testProviderName\",\"abilityName\":\"CryptoExtension\","
                              "\"bundleName\":\"com.example.cryptoapplication\",\"index\":{\"key\":\"testKey\"}}";
    const char *propertyIdStr = "SKF_GetDevInfo"; // Name of the property function defined in the GMT 0016-2023 standard
    
    struct OH_Huks_Blob resourceId = {
        (uint32_t)strlen(resourceIdStr),
        (uint8_t *)resourceIdStr
    };
    struct OH_Huks_Blob propertyId = {
        (uint32_t)strlen(propertyIdStr),
        (uint8_t *)propertyIdStr
    };
    
    /* 2. Construct input parameters. */
    OH_Huks_ExternalCryptoParam params[] = {};
    OH_Huks_ExternalCryptoParamSet *paramSetIn = nullptr;
    OH_Huks_ExternalCryptoParamSet *paramSetOut = nullptr;
    OH_Huks_Result ohResult;
    
    do {
        /* 3. Initialize and build the input parameter set. */
        ohResult = InitExternalCryptoParamSet(&paramSetIn, params,
            sizeof(params) / sizeof(OH_Huks_ExternalCryptoParam));
        if (ohResult.errorCode != OH_HUKS_SUCCESS) {
            break;
        }
        
        /* 4. Call OH_Huks_GetProperty to obtain the properties. */
        ohResult = OH_Huks_GetProperty(&resourceId, &propertyId, paramSetIn, &paramSetOut);
        if (ohResult.errorCode != OH_HUKS_SUCCESS) {
            break;
        }
        
        /* 5. Extract the result from the output parameter set.
         * The output parameter set is allocated internally by the function, and the found property data is stored in OH_HUKS_EXT_CRYPTO_TAG_EXTRA_DATA TAG.
         * The following shows how to iterate over the returned params and safely extract the returned property string (example).
         */
        if (paramSetOut != nullptr && paramSetOut->paramsCnt > 0) {
            for (uint32_t i = 0; i < paramSetOut->paramsCnt; i++) {
                OH_Huks_ExternalCryptoParam *param = &paramSetOut->params[i];
                /* Return data convention: The GetProperty result is stored in OH_HUKS_EXT_CRYPTO_TAG_EXTRA_DATA TAG (the JSON text is used as an example). */
                if (param->tag == OH_HUKS_EXT_CRYPTO_TAG_EXTRA_DATA) {
                    /* Note: param->blob.data may not end with '\0'. You need to copy the data and manually add the terminator. */
                    char *outStr = (char *)malloc(param->blob.size + 1);
                    if (outStr != NULL) {
                        memcpy(outStr, param->blob.data, param->blob.size);
                        outStr[param->blob.size] = '\0';
                        // Parse outStr (for example, using the JSON parsing library). The following is an example:
                        // parse_json(outStr);
                        free(outStr);
                    }
                }
            }
        }
    } while (0);
    
    /* 6. Release the resources. */
    OH_Huks_FreeExternalCryptoParamSet(&paramSetIn);
    OH_Huks_FreeExternalCryptoParamSet(&paramSetOut);
    
    napi_value ret;
    napi_create_int32(env, ohResult.errorCode, &ret);
    return ret;
}