Branch data     Line data    Source code

       1                 :            : /**
       2                 :            :  * \file psa/crypto_compat.h
       3                 :            :  *
       4                 :            :  * \brief PSA cryptography module: Backward compatibility aliases
       5                 :            :  *
       6                 :            :  * This header declares alternative names for macro and functions.
       7                 :            :  * New application code should not use these names.
       8                 :            :  * These names may be removed in a future version of Mbed Crypto.
       9                 :            :  *
      10                 :            :  * \note This file may not be included directly. Applications must
      11                 :            :  * include psa/crypto.h.
      12                 :            :  */
      13                 :            : /*
      14                 :            :  *  Copyright The Mbed TLS Contributors
      15                 :            :  *  SPDX-License-Identifier: Apache-2.0
      16                 :            :  *
      17                 :            :  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
      18                 :            :  *  not use this file except in compliance with the License.
      19                 :            :  *  You may obtain a copy of the License at
      20                 :            :  *
      21                 :            :  *  http://www.apache.org/licenses/LICENSE-2.0
      22                 :            :  *
      23                 :            :  *  Unless required by applicable law or agreed to in writing, software
      24                 :            :  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
      25                 :            :  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      26                 :            :  *  See the License for the specific language governing permissions and
      27                 :            :  *  limitations under the License.
      28                 :            :  */
      29                 :            : 
      30                 :            : #ifndef PSA_CRYPTO_COMPAT_H
      31                 :            : #define PSA_CRYPTO_COMPAT_H
      32                 :            : 
      33                 :            : #ifdef __cplusplus
      34                 :            : extern "C" {
      35                 :            : #endif
      36                 :            : 
      37                 :            : /*
      38                 :            :  * To support both openless APIs and psa_open_key() temporarily, define
      39                 :            :  * psa_key_handle_t to be equal to mbedtls_svc_key_id_t. Do not mark the
      40                 :            :  * type and its utility macros and functions deprecated yet. This will be done
      41                 :            :  * in a subsequent phase.
      42                 :            :  */
      43                 :            : typedef mbedtls_svc_key_id_t psa_key_handle_t;
      44                 :            : 
      45                 :            : #define PSA_KEY_HANDLE_INIT MBEDTLS_SVC_KEY_ID_INIT
      46                 :            : 
      47                 :            : /** Check whether an handle is null.
      48                 :            :  *
      49                 :            :  * \param handle  Handle
      50                 :            :  *
      51                 :            :  * \return Non-zero if the handle is null, zero otherwise.
      52                 :            :  */
      53                 :          0 : static inline int psa_key_handle_is_null( psa_key_handle_t handle )
      54                 :            : {
      55                 :          0 :     return( mbedtls_svc_key_id_is_null( handle ) );
      56                 :            : }
      57                 :            : 
      58                 :            : /** Open a handle to an existing persistent key.
      59                 :            :  *
      60                 :            :  * Open a handle to a persistent key. A key is persistent if it was created
      61                 :            :  * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
      62                 :            :  * always has a nonzero key identifier, set with psa_set_key_id() when
      63                 :            :  * creating the key. Implementations may provide additional pre-provisioned
      64                 :            :  * keys that can be opened with psa_open_key(). Such keys have an application
      65                 :            :  * key identifier in the vendor range, as documented in the description of
      66                 :            :  * #psa_key_id_t.
      67                 :            :  *
      68                 :            :  * The application must eventually close the handle with psa_close_key() or
      69                 :            :  * psa_destroy_key() to release associated resources. If the application dies
      70                 :            :  * without calling one of these functions, the implementation should perform
      71                 :            :  * the equivalent of a call to psa_close_key().
      72                 :            :  *
      73                 :            :  * Some implementations permit an application to open the same key multiple
      74                 :            :  * times. If this is successful, each call to psa_open_key() will return a
      75                 :            :  * different key handle.
      76                 :            :  *
      77                 :            :  * \note This API is not part of the PSA Cryptography API Release 1.0.0
      78                 :            :  * specification. It was defined in the 1.0 Beta 3 version of the
      79                 :            :  * specification but was removed in the 1.0.0 released version. This API is
      80                 :            :  * kept for the time being to not break applications relying on it. It is not
      81                 :            :  * deprecated yet but will be in the near future.
      82                 :            :  *
      83                 :            :  * \note Applications that rely on opening a key multiple times will not be
      84                 :            :  * portable to implementations that only permit a single key handle to be
      85                 :            :  * opened. See also :ref:\`key-handles\`.
      86                 :            :  *
      87                 :            :  *
      88                 :            :  * \param key           The persistent identifier of the key.
      89                 :            :  * \param[out] handle   On success, a handle to the key.
      90                 :            :  *
      91                 :            :  * \retval #PSA_SUCCESS
      92                 :            :  *         Success. The application can now use the value of `*handle`
      93                 :            :  *         to access the key.
      94                 :            :  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
      95                 :            :  *         The implementation does not have sufficient resources to open the
      96                 :            :  *         key. This can be due to reaching an implementation limit on the
      97                 :            :  *         number of open keys, the number of open key handles, or available
      98                 :            :  *         memory.
      99                 :            :  * \retval #PSA_ERROR_DOES_NOT_EXIST
     100                 :            :  *         There is no persistent key with key identifier \p key.
     101                 :            :  * \retval #PSA_ERROR_INVALID_ARGUMENT
     102                 :            :  *         \p key is not a valid persistent key identifier.
     103                 :            :  * \retval #PSA_ERROR_NOT_PERMITTED
     104                 :            :  *         The specified key exists, but the application does not have the
     105                 :            :  *         permission to access it. Note that this specification does not
     106                 :            :  *         define any way to create such a key, but it may be possible
     107                 :            :  *         through implementation-specific means.
     108                 :            :  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
     109                 :            :  * \retval #PSA_ERROR_CORRUPTION_DETECTED
     110                 :            :  * \retval #PSA_ERROR_STORAGE_FAILURE
     111                 :            :  * \retval #PSA_ERROR_DATA_INVALID
     112                 :            :  * \retval #PSA_ERROR_DATA_CORRUPT
     113                 :            :  * \retval #PSA_ERROR_BAD_STATE
     114                 :            :  *         The library has not been previously initialized by psa_crypto_init().
     115                 :            :  *         It is implementation-dependent whether a failure to initialize
     116                 :            :  *         results in this error code.
     117                 :            :  */
     118                 :            : psa_status_t psa_open_key( mbedtls_svc_key_id_t key,
     119                 :            :                            psa_key_handle_t *handle );
     120                 :            : 
     121                 :            : /** Close a key handle.
     122                 :            :  *
     123                 :            :  * If the handle designates a volatile key, this will destroy the key material
     124                 :            :  * and free all associated resources, just like psa_destroy_key().
     125                 :            :  *
     126                 :            :  * If this is the last open handle to a persistent key, then closing the handle
     127                 :            :  * will free all resources associated with the key in volatile memory. The key
     128                 :            :  * data in persistent storage is not affected and can be opened again later
     129                 :            :  * with a call to psa_open_key().
     130                 :            :  *
     131                 :            :  * Closing the key handle makes the handle invalid, and the key handle
     132                 :            :  * must not be used again by the application.
     133                 :            :  *
     134                 :            :  * \note This API is not part of the PSA Cryptography API Release 1.0.0
     135                 :            :  * specification. It was defined in the 1.0 Beta 3 version of the
     136                 :            :  * specification but was removed in the 1.0.0 released version. This API is
     137                 :            :  * kept for the time being to not break applications relying on it. It is not
     138                 :            :  * deprecated yet but will be in the near future.
     139                 :            :  *
     140                 :            :  * \note If the key handle was used to set up an active
     141                 :            :  * :ref:\`multipart operation <multipart-operations>\`, then closing the
     142                 :            :  * key handle can cause the multipart operation to fail. Applications should
     143                 :            :  * maintain the key handle until after the multipart operation has finished.
     144                 :            :  *
     145                 :            :  * \param handle        The key handle to close.
     146                 :            :  *                      If this is \c 0, do nothing and return \c PSA_SUCCESS.
     147                 :            :  *
     148                 :            :  * \retval #PSA_SUCCESS
     149                 :            :  *         \p handle was a valid handle or \c 0. It is now closed.
     150                 :            :  * \retval #PSA_ERROR_INVALID_HANDLE
     151                 :            :  *         \p handle is not a valid handle nor \c 0.
     152                 :            :  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
     153                 :            :  * \retval #PSA_ERROR_CORRUPTION_DETECTED
     154                 :            :  * \retval #PSA_ERROR_BAD_STATE
     155                 :            :  *         The library has not been previously initialized by psa_crypto_init().
     156                 :            :  *         It is implementation-dependent whether a failure to initialize
     157                 :            :  *         results in this error code.
     158                 :            :  */
     159                 :            : psa_status_t psa_close_key(psa_key_handle_t handle);
     160                 :            : 
     161                 :            : #ifdef __cplusplus
     162                 :            : }
     163                 :            : #endif
     164                 :            : 
     165                 :            : #endif /* PSA_CRYPTO_COMPAT_H */