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. */
    /* coverity[misra_c_2012_rule_11_1_violation] */
    ( void ) Notify;
 
    /* Check that the PKCS #11 module is initialized. */
    /* See explanation in prvCheckValidSessionAndModule for this exception. */
    /* coverity[misra_c_2012_rule_10_5_violation] */
    if( xP11Context.xIsInitialized != ( CK_BBOOL ) CK_TRUE )
    {
        xResult = CKR_CRYPTOKI_NOT_INITIALIZED;
    }
 
    /* Check arguments. */
    if( NULL == phSession )
    {
        xResult = CKR_ARGUMENTS_BAD;
    }
 
    /* 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;
    }
 
    /*
     * Make space for the context.
     */
    if( CKR_OK == xResult )
    {
        /* Get next open session slot. */
        if( xSemaphoreTake( xP11Context.xSessionMutex, portMAX_DELAY ) == pdTRUE )
        {
            for( ulSessionCount = 0; ulSessionCount < pkcs11configMAX_SESSIONS; ++ulSessionCount )
            {
                /* coverity[misra_c_2012_rule_10_5_violation] */
                if( pxP11Sessions[ ulSessionCount ].xOpened == ( CK_BBOOL ) CK_FALSE )
                {
                    xResult = CKR_OK;
                    pxSessionObj = &pxP11Sessions[ ulSessionCount ];
                    /* coverity[misra_c_2012_rule_10_5_violation] */
                    pxSessionObj->xOpened = ( CK_BBOOL ) CK_TRUE;
                    break;
                }
                else
                {
                    /* No available session. */
                    xResult = CKR_SESSION_COUNT;
                }
            }
 
            ( void ) xSemaphoreGive( xP11Context.xSessionMutex );
        }
        else
        {
            xResult = CKR_FUNCTION_FAILED;
        }
 
        if( CKR_OK == xResult )
        {
            pxSessionObj->xSignMutex = xSemaphoreCreateMutex();
 
            if( NULL == pxSessionObj->xSignMutex )
            {
                xResult = CKR_HOST_MEMORY;
            }
 
            pxSessionObj->xVerifyMutex = xSemaphoreCreateMutex();
 
            if( NULL == pxSessionObj->xVerifyMutex )
            {
                xResult = CKR_HOST_MEMORY;
            }
        }
    }
 
    if( CKR_OK == xResult )
    {
        /*
         * Assign the session.
         */
        pxSessionObj->ulState =
            ( 0UL != ( flags & CKF_RW_SESSION ) ) ? CKS_RW_PUBLIC_SESSION : CKS_RO_PUBLIC_SESSION;
    }
 
    /*
     *   Initialize the operation in progress.
     */
    if( CKR_OK == xResult )
    {
        pxSessionObj->xOperationDigestMechanism = pkcs11NO_OPERATION;
        pxSessionObj->xOperationVerifyMechanism = pkcs11NO_OPERATION;
        pxSessionObj->xOperationSignMechanism = pkcs11NO_OPERATION;
    }
 
    if( CKR_OK != xResult )
    {
        PKCS11_PRINT( ( "Failed to open a new session with error %d \r\n", xResult ) );
 
        if( pxSessionObj != NULL )
        {
            if( pxSessionObj->xSignMutex != NULL )
            {
                vSemaphoreDelete( pxSessionObj->xSignMutex );
            }
 
            if( pxSessionObj->xVerifyMutex != NULL )
            {
                vSemaphoreDelete( pxSessionObj->xVerifyMutex );
            }
 
            ( void ) memset( pxSessionObj, 0, sizeof( P11Session_t ) );
            *phSession = CK_INVALID_HANDLE;
        }
    }
    else
    {
        /* Increment by one, as invalid handles in PKCS #11 are 0. */
        ++ulSessionCount;
        *phSession = ulSessionCount;
    }
 
    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. Else, see PKCS #11 specification for more information.