src/e2ee-adaptation-layer/e2ee-adaptation-layer.h

   1 /*
   2  * Copyright (c) 2023 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License
  15  */
  16
  17 #pragma once
  18
  19 #include <stddef.h>
  20
  21 /**
  22  * @brief Derives a common symmetric key using ECDH and KBKDF.
  23  *
  24  * @since_tizen 7.5
  25  *
  26  * @remarks The derived key will be a symmetric one. It will be stored as a #CKMC_KEY_AES.
  27  * @remarks The function first generates a shared secret using ECDH and temporarily stores it in
  28  *          key-manager. Then it derives a symmetric key from it, stores it in key-manager too and
  29  *          removes the shared secret.
  30  * @remarks Shared secret length and KBKDF algorithm parameters are fixed in the code.
  31  * @remarks To simplify the API, it is assumed that the private key alias does not use a custom
  32  *          password.
  33  *
  34  * @param[in] private_key_alias Alias of the private key to be used in ECDH
  35  * @param[in] raw_public_key Peer's public key in DER format to be used in ECDH
  36  * @param[in] raw_public_key_len Length of the @a raw_public_key
  37  * @param[in] new_key_alias The name under which the new key will be known in key-manager
  38  *
  39  * @return @c 0 on success, otherwise a negative error value
  40  *
  41  * @retval #CKMC_ERROR_NONE Successful
  42  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a private_key_alias = NULL,
  43  *                                       @a raw_public_key = NULL, @a new_key_alias = NULL)
  44  * @retval #CKMC_ERROR_DB_LOCKED A user is not logged in to key-manager
  45  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a private_key_alias does not exist
  46  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a new_key_alias already exists
  47  * @retval #CKMC_ERROR_INVALID_FORMAT The format of @a raw_public_key is not valid
  48  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
  49  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
  50  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Secret decryption failed because @a private_key_alias
  51  *                                           needed a password and none was given
  52  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
  53  *
  54  * @pre User is already logged in to key-manager.
  55  *
  56  * @see ckmc_key_derive()
  57  */
  58 int ckmew_key_agreement(const char *private_key_alias,
  59                         const unsigned char *raw_public_key,
  60                         size_t raw_public_key_len,
  61                         const char *new_key_alias);
  62
  63 /**
  64  * @brief Derives a symmetric key from a password using PBKFD2 and stores it in key-manager
  65  *
  66  * @since_tizen 7.5
  67  *
  68  * @remarks The password is temporarily stored in key-manager. It is deleted after key derivation
  69  *          is performed.
  70  * @remarks The key-manager's policy for storing the derived key is fixed in the code.
  71  * @remarks The number of PBKDF2 iteration is fixed in the code.
  72  *
  73  * @param[in] password The password to derive the key from
  74  * @param[in] salt The salt used for PBKDF2
  75  * @param[in] salt_len Length of the @a salt
  76  * @param[in] new_key_len The desired length of the derived key
  77  * @param[in] new_key_alias The name under which the new key will be known in key-manager
  78  *
  79  * @return @c 0 on success, otherwise a negative error value
  80  *
  81  * @retval #CKMC_ERROR_NONE Successful
  82  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a password = NULL or
  83  *                                       @a salt = NULL)
  84  * @retval #CKMC_ERROR_NOT_SUPPORTED Unsupported key length
  85  * @retval #CKMC_ERROR_DB_LOCKED A user is not logged in to key-manager
  86  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a new_key_alias already exists
  87  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
  88  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
  89  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
  90  *
  91  * @pre User is already logged in to key-manager.
  92  *
  93  * @see ckmc_key_derive()
  94  */
  95 int ckmew_key_derive_pbkdf2(const char *password,
  96                             const unsigned char *salt,
  97                             size_t salt_len,
  98                             size_t new_key_len,
  99                             const char *new_key_alias);