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 #include <ckmc/ckmc-type.h>
  21
  22 /**
  23  * @brief Derives a common symmetric key using ECDH and KBKDF.
  24  *
  25  * @since_tizen 7.5
  26  *
  27  * @remarks The derived key will be a symmetric one. It will be stored as a #CKMC_KEY_AES.
  28  * @remarks The function first generates a shared secret using ECDH and temporarily stores it in
  29  *          key-manager. Then it derives a symmetric key from it, stores it in key-manager too and
  30  *          removes the shared secret.
  31  * @remarks Shared secret length and KBKDF algorithm parameters are fixed in the code.
  32  * @remarks To simplify the API, it is assumed that the private key alias does not use a custom
  33  *          password.
  34  *
  35  * @param[in] private_key_alias Alias of the private key to be used in ECDH
  36  * @param[in] raw_public_key Peer's public key in DER format to be used in ECDH
  37  * @param[in] raw_public_key_len Length of the @a raw_public_key
  38  * @param[in] new_key_alias The name under which the new key will be known in key-manager
  39  *
  40  * @return @c 0 on success, otherwise a negative error value
  41  *
  42  * @retval #CKMC_ERROR_NONE Successful
  43  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a private_key_alias = NULL,
  44  *                                       @a raw_public_key = NULL, @a new_key_alias = NULL)
  45  * @retval #CKMC_ERROR_DB_LOCKED A user is not logged in to key-manager
  46  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a private_key_alias does not exist
  47  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a new_key_alias already exists
  48  * @retval #CKMC_ERROR_INVALID_FORMAT The format of @a raw_public_key is not valid
  49  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
  50  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
  51  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Secret decryption failed because @a private_key_alias
  52  *                                           needed a password and none was given
  53  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
  54  *
  55  * @pre User is already logged in to key-manager.
  56  *
  57  * @see ckmc_key_derive()
  58  */
  59 int ckmew_key_agreement(const char *private_key_alias,
  60                         const unsigned char *raw_public_key,
  61                         size_t raw_public_key_len,
  62                         const char *new_key_alias);
  63
  64 /**
  65  * @brief Derives a symmetric key from a password using PBKFD2 and stores it in key-manager
  66  *
  67  * @since_tizen 7.5
  68  *
  69  * @remarks The password is temporarily stored in key-manager. It is deleted after key derivation
  70  *          is performed.
  71  * @remarks The key-manager's policy for storing the derived key is fixed in the code.
  72  * @remarks The number of PBKDF2 iteration is fixed in the code.
  73  *
  74  * @param[in] password The password to derive the key from
  75  * @param[in] salt The salt used for PBKDF2
  76  * @param[in] salt_len Length of the @a salt
  77  * @param[in] new_key_len The desired length of the derived key
  78  * @param[in] new_key_alias The name under which the new key will be known in key-manager
  79  *
  80  * @return @c 0 on success, otherwise a negative error value
  81  *
  82  * @retval #CKMC_ERROR_NONE Successful
  83  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a password = NULL or
  84  *                                       @a salt = NULL)
  85  * @retval #CKMC_ERROR_NOT_SUPPORTED Unsupported key length
  86  * @retval #CKMC_ERROR_DB_LOCKED A user is not logged in to key-manager
  87  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a new_key_alias already exists
  88  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
  89  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
  90  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
  91  *
  92  * @pre User is already logged in to key-manager.
  93  *
  94  * @see ckmc_key_derive()
  95  */
  96 int ckmew_key_derive_pbkdf2(const char *password,
  97                             const unsigned char *salt,
  98                             size_t salt_len,
  99                             size_t new_key_len,
 100                             const char *new_key_alias);
 101
 102 /**
 103  * @platform
 104  *
 105  * @since_tizen 7.5
 106  *
 107  * @brief Constructs OCF certificate chain and returns it
 108  *
 109  * @privlevel platform
 110  * @privilege %http://tizen.org/privilege/devicecertificate
 111  *
 112  * @remarks The @a cert_chain should be freed using free().
 113  *
 114  * @param[out] cert_chain Certificate chain in binary, will be allocated by the library
 115  * @param[out] cert_chain_len The total length of certificate chain
 116  *
 117  * @return #DCM_ERROR_NONE on success, otherwise a negative error value
 118  *
 119  * @retval #DCM_ERROR_NONE Successful
 120  * @retval #DCM_ERROR_INVALID_PARAMETER Input parameter is invalid
 121  * @retval #DCM_ERROR_OUT_OF_MEMORY Out of memory during processing
 122  * @retval #DCM_ERROR_PERMISSION_DENIED Failed to access device certificate manager
 123  * @retval #DCM_ERROR_NOT_SUPPORTED Feature needed to run API is not supported
 124  * @retval #DCM_ERROR_SOCKET Socket error between client and server
 125  * @retval #DCM_ERROR_NO_DATA No certificate chain available
 126  * @retval #DCM_ERROR_UNKNOWN Unknown error
 127  */
 128 int ckmew_get_ocf_cert_chain(char **cert_chain, size_t *cert_chain_len);
 129
 130 /**
 131  * @platform
 132  *
 133  * @since_tizen 7.5
 134  *
 135  * @brief Signs given public key with OCF using E2EE signing scheme.
 136  *
 137  * @privlevel platform
 138  * @privilege %http://tizen.org/privilege/devicecertificate
 139  *
 140  * @remarks The public key will be retrieved from key-manager.
 141  * @remarks It is assumed that the public key is not encrypted with a custom password in
 142  *          key-manager and thus there's no need to pass additional argument.
 143  *
 144  * @param[in] public_key_alias Alias of the public key to be signed
 145  * @param[out] message The E2EE message composed from public key and E2EE prefixes. It has to be
 146  *             freed using ckmc_buffer_free()
 147  * @param[out] signature The OCF signature calculated for @a message. It has to be
 148  *             freed using ckmc_buffer_free()
 149  *
 150  * @return #DCM_ERROR_NONE on success, otherwise a negative error value
 151  *
 152  * @retval #DCM_ERROR_NONE Successful
 153  * @retval #DCM_ERROR_INVALID_PARAMETER Input parameter is invalid
 154  * @retval #DCM_ERROR_OUT_OF_MEMORY Out of memory during processing
 155  * @retval #DCM_ERROR_PERMISSION_DENIED Failed to access device certificate manager
 156  * @retval #DCM_ERROR_NOT_SUPPORTED Feature needed to run API is not supported
 157  * @retval #DCM_ERROR_SOCKET Socket error between client and server
 158  * @retval #DCM_ERROR_NO_DATA If OCF or public key are not available
 159  * @retval #DCM_ERROR_UNKNOWN Unknown error
 160  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 161  * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
 162  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 163  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 164  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 165  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 166  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect
 167  */
 168 int ckmew_sign_with_ocf(const char *public_key_alias,
 169                         ckmc_raw_buffer_s **message,
 170                         ckmc_raw_buffer_s **signature);