C_OpenSession

Opens a connection between an application and a particular token or sets up an application callback for token insertion.

CK_DECLARE_FUNCTION( CK_RV, C_OpenSession )( CK_SLOT_ID slotID,
                                             CK_FLAGS flags,
                                             CK_VOID_PTR pApplication,
                                             CK_NOTIFY Notify,
                                             CK_SESSION_HANDLE_PTR phSession )
{
    CK_RV xResult = CKR_OK;
    P11Session_t * pxSessionObj = NULL;
    uint32_t ulSessionCount = 0;
 
    ( void ) ( slotID );
    ( void ) ( pApplication );
 
    /* Allow unused parameters to be cast to void to silence compiler warnings.
     * Even if they are a function pointer. */
    /* MISRA Ref 11.1.1 [Object type casting] */
    /* More details at: https://github.com/FreeRTOS/corePKCS11/blob/main/MISRA.md#rule-111 */
    ( void ) Notify;
 
    /* Check that the PKCS #11 module is initialized. */
    /* 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] */
    if( xP11Context.xIsInitialized != ( CK_BBOOL ) CK_TRUE )
    {
        xResult = CKR_CRYPTOKI_NOT_INITIALIZED;
        LogError( ( "Could not open a session. PKCS #11 must be initialized "
                    "before any operations." ) );
    }
 
    /* Check arguments. */
    if( NULL == phSession )
    {
        xResult = CKR_ARGUMENTS_BAD;
        LogError( ( "Could not open a session. phSession cannot be a NULL pointer." ) );
    }
 
    /* For legacy reasons, the CKF_SERIAL_SESSION bit MUST always be set. */
    if( ( CKR_OK == xResult ) && ( 0UL == ( CKF_SERIAL_SESSION & flags ) ) )
    {
        xResult = CKR_SESSION_PARALLEL_NOT_SUPPORTED;
        LogError( ( "Could not open a session. CKR_SESSION_PARALLEL_NOT_SUPPORTED "
                    "must always be a set flag." ) );
    }
 
    /*
     * Make space for the context.
     */
    if( CKR_OK == xResult )
    {
        /* Get next open session slot. */
        if( mbedtls_mutex_lock( &xP11Context.xSessionMutex ) == 0 )
        {
            for( ulSessionCount = 0; ulSessionCount < pkcs11configMAX_SESSIONS; ++ulSessionCount )
            {
                /* 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] */
                if( pxP11Sessions[ ulSessionCount ].xOpened == ( CK_BBOOL ) CK_FALSE )
                {
                    xResult = CKR_OK;
                    pxSessionObj = &pxP11Sessions[ ulSessionCount ];
                    /* 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] */
                    pxSessionObj->xOpened = ( CK_BBOOL ) CK_TRUE;
                    break;
                }
                else
                {
                    xResult = CKR_SESSION_COUNT;
                }
            }
 
            ( void ) mbedtls_mutex_unlock( &xP11Context.xSessionMutex );
        }
        else
        {
            xResult = CKR_FUNCTION_FAILED;
            LogError( ( "Could not open a session. Unsuccessful in taking xSessionMutex." ) );
        }
 
        if( CKR_OK == xResult )
        {
            mbedtls_mutex_init( &pxSessionObj->xSignMutex );
            mbedtls_mutex_init( &pxSessionObj->xVerifyMutex );
        }
    }
 
    if( CKR_OK == xResult )
    {
        /*
         * Assign the session.
         */
        pxSessionObj->ulState =
            ( 0UL != ( flags & CKF_RW_SESSION ) ) ? CKS_RW_PUBLIC_SESSION : CKS_RO_PUBLIC_SESSION;
        LogDebug( ( "Assigned a 0x%0lX Type Session.", ( unsigned long int ) pxSessionObj->ulState ) );
    }
 
    /*
     *   Initialize the operation in progress.
     */
    if( CKR_OK == xResult )
    {
        pxSessionObj->xOperationDigestMechanism = pkcs11NO_OPERATION;
        pxSessionObj->xOperationVerifyMechanism = pkcs11NO_OPERATION;
        pxSessionObj->xOperationSignMechanism = pkcs11NO_OPERATION;
        LogDebug( ( "Assigned Mechanisms to no operation in progress." ) );
    }
 
    if( xResult == CKR_SESSION_COUNT )
    {
        /* No available session. */
        LogError( ( "Could not open a session. All sessions have "
                    "been taken. Consider increasing value of "
                    "pkcs11configMAX_SESSIONS." ) );
    }
 
    if( CKR_OK == xResult )
    {
        /* Increment by one, as invalid handles in PKCS #11 are 0. */
        ++ulSessionCount;
        *phSession = ulSessionCount;
        LogDebug( ( "Current session count at %lu", ( unsigned long int ) ( ulSessionCount - 1UL ) ) );
    }
 
    return xResult;
}

Note

PKCS #11 module must have been previously initialized with a call to C_Initialize() before calling C_OpenSession().

Parameters

[in]	slotID	This parameter is unused in this port.
[in]	flags	Session flags - CKF_SERIAL_SESSION is a mandatory flag.
[in]	pApplication	This parameter is unused in this port.
[in]	Notify	This parameter is unused in this port.
[in]	phSession	Pointer to the location that the created session's handle will be placed.

Returns

CKR_OK if successful.