C_FindObjects

Initializes an object search operation.

CK_DECLARE_FUNCTION( CK_RV, C_FindObjects )( CK_SESSION_HANDLE hSession,
                                             CK_OBJECT_HANDLE_PTR phObject,
                                             CK_ULONG ulMaxObjectCount,
                                             CK_ULONG_PTR pulObjectCount )
{
    P11Session_t * pxSession = prvSessionPointerFromHandle( hSession );
    CK_RV xResult = prvCheckValidSessionAndModule( pxSession );
 
    /* MISRA Ref 10.5.1 [Essential type casting] */
    /* More details at: https://github.com/FreeRTOS/corePKCS11/blob/main/MISRA.md#rule-105 */
    /* coverity[misra_c_2012_rule_10_5_violation] */
    CK_OBJECT_HANDLE xPalHandle = CK_INVALID_HANDLE;
 
    /*
     * Check parameters.
     */
    if( ( NULL == phObject ) ||
        ( NULL == pulObjectCount ) )
    {
        LogError( ( "Failed to find objects. The object handle or the object "
                    "count pointer was NULL." ) );
        xResult = CKR_ARGUMENTS_BAD;
    }
 
    if( xResult == CKR_OK )
    {
        if( pxSession->pxFindObjectLabel == NULL )
        {
            LogError( ( "Failed to find objects. The PKCS #11 stack must be "
                        "initialized before any operations." ) );
            xResult = CKR_OPERATION_NOT_INITIALIZED;
        }
 
        if( 1u != ulMaxObjectCount )
        {
            xResult = CKR_ARGUMENTS_BAD;
            LogError( ( "Failed to find objects. Searching for anything other "
                        "than 1 object at a time is not supported." ) );
        }
    }
 
    if( xResult == CKR_OK )
    {
        /* Try to find the object in module's list first. */
        prvFindObjectInListByLabel( pxSession->pxFindObjectLabel, pxSession->xFindObjectLabelLen, &xPalHandle, phObject );
 
        /* Check with the PAL if the object was previously stored. */
        if( *phObject == CK_INVALID_HANDLE )
        {
            LogDebug( ( "Could not find the object handle in the list. "
                        "Trying to search PKCS #11 PAL for object." ) );
            xPalHandle = PKCS11_PAL_FindObject( pxSession->pxFindObjectLabel, pxSession->xFindObjectLabelLen );
        }
 
        if( xPalHandle != CK_INVALID_HANDLE )
        {
            LogDebug( ( "Found object in PAL. Adding object handle to list." ) );
            xResult = prvAddObjectToList( xPalHandle, phObject, pxSession->pxFindObjectLabel, pxSession->xFindObjectLabelLen );
            *pulObjectCount = 1;
        }
        else
        {
            /* Note: Objects living in header files are not destroyed. */
            /* According to the PKCS #11 standard, not finding an object results in a CKR_OK return value with an object count of 0. */
            *pulObjectCount = 0;
        }
    }
 
    /* Clean up memory if there was an error finding the object. */
    if( xResult != CKR_OK )
    {
        if( pxSession != NULL )
        {
            mbedtls_free( pxSession->pxFindObjectLabel );
            pxSession->pxFindObjectLabel = NULL;
            pxSession->xFindObjectLabelLen = 0;
        }
    }
 
    return xResult;
}
 

See also

C_FindObjectsInit() which must be called before calling C_FindObjects() and C_FindObjectsFinal(), which must be called after.

Note

FindObjects parameters are shared by a session. Calling C_FindObjectsInit(), C_FindObjects(), and C_FindObjectsFinal() with the same session across different tasks may lead to unexpected results.

Parameters

[in]	hSession	Handle of a valid PKCS #11 session.
[out]	phObject	Points to the handle of the object to be found.
[in]	ulMaxObjectCount	The size of the phObject object handle array. In this port, this value should always be set to 1, as searching for multiple objects is not supported.
[out]	pulObjectCount	The actual number of objects that are found. In this port, if an object is found this value will be 1, otherwise if the object is not found, it will be set to 0.

Note

In the event that an object does not exist, CKR_OK will be returned, but pulObjectCount will be set to 0.

Returns

CKR_OK if successful.