cs_der_keys_and_csrs.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2017 ARM Ltd.
00003 //  
00004 // Licensed under the Apache License, Version 2.0 (the "License");
00005 // you may not use this file except in compliance with the License.
00006 // You may obtain a copy of the License at
00007 //  
00008 //     http://www.apache.org/licenses/LICENSE-2.0
00009 //  
00010 // Unless required by applicable law or agreed to in writing, software
00011 // distributed under the License is distributed on an "AS IS" BASIS,
00012 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013 // See the License for the specific language governing permissions and
00014 // limitations under the License.
00015 // ----------------------------------------------------------------------------
00016 
00017 #ifndef __CS_DER_KEYS_H__
00018 #define __CS_DER_KEYS_H__
00019 
00020 #include <stdlib.h>
00021 #include <stdbool.h>
00022 #include <stdint.h>
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 #include "kcm_status.h"
00029 #include "kcm_defs.h"
00030 
00031 
00032 /* CS key object handle */
00033 typedef uintptr_t cs_key_handle_t;
00034 
00035 /* === EC max sizes === */
00036 #define KCM_EC_SECP256R1_MAX_PRIV_KEY_DER_SIZE           150
00037 #define KCM_EC_SECP256R1_MAX_PUB_KEY_RAW_SIZE            65
00038 #define KCM_EC_SECP256R1_MAX_PUB_KEY_DER_SIZE            91
00039 #define KCM_ECDSA_SECP256R1_MAX_SIGNATURE_SIZE_IN_BYTES  (256/8)*2 + 10 //74 bytes
00040 
00041 /** EC key context
00042 * Contains the private and public keys buffers
00043 * and their actual sizes
00044 *
00045 * FIXME: this sturct should be private
00046 */
00047 typedef struct _cs_ec_key_context {
00048     uint8_t priv_key[KCM_EC_SECP256R1_MAX_PRIV_KEY_DER_SIZE];
00049     size_t priv_key_size;
00050     uint8_t pub_key[KCM_EC_SECP256R1_MAX_PUB_KEY_DER_SIZE];
00051     size_t pub_key_size;
00052 } cs_ec_key_context_s;
00053 
00054 /**Verify private Key In DER format. For now only EC keys supported
00055 *
00056 *@key_data - DER format private key data.
00057 *@key_data_length - key data size
00058 * @return
00059 *     KCM_STATUS_SUCCESS on success, otherwise appropriate error from  kcm_status_e.
00060 */
00061 
00062 kcm_status_e  cs_der_priv_key_verify(const uint8_t* key, size_t key_length);
00063 
00064 /**Verify public Key In DER format. For now only EC keys supported
00065 *
00066 *@key_data - DER format puclic key data.
00067 *@key_data_length - key data size
00068 * @return
00069 *     KCM_STATUS_SUCCESS on success, otherwise appropriate error from  kcm_status_e.
00070 */
00071 
00072 kcm_status_e  cs_der_public_key_verify(const uint8_t* key, size_t key_length);
00073 
00074 /** Verify the ECDSA signature of a previously hashed message.
00075 *
00076 * @param[in] der_pub_key:         The public key buffer for verification.
00077 * @param[in] der_pub_key_len:     The size of public key buffer.
00078 * @param[in] hash_dgst:           The message buffer.
00079 * @param[in] hash_dgst_len:   The length of the message buffer.
00080 * @param[in] sign:                The signature buffer
00081 * @param[in] signature size:      The size of signature buffer.
00082 *
00083 *    @returns
00084 *        KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00085 */
00086 kcm_status_e  cs_ecdsa_verify(const uint8_t *der_pub_key, size_t der_pub_key_len, const uint8_t *hash_dgst, size_t hash_dgst_len,const uint8_t *sign, size_t  signature_size);
00087 
00088 
00089 /**Calculate signature on hash digest using ecdsa private key.
00090 *
00091 *@der_priv_key[in] - DER private key data.
00092 *@der_priv_key_length[in] - key data size
00093 *@hash_dgst[in] - hash digest buffer
00094 *@size_of_hash_dgst[in] - size of hash digest buffer
00095 *@out_sign[in/out] - output buffer for calculated signature
00096 *@signature_data_max_size[in] - size of signature buffer
00097 *@signature_data_act_size_out[out] - actual size of output signature buffer
00098 * @return
00099 *     KCM_STATUS_SUCCESS on success, otherwise appropriate error from  kcm_status_e.
00100 */
00101 kcm_status_e  cs_ecdsa_sign(const uint8_t *der_priv_key, size_t der_priv_key_length, const uint8_t *hash_dgst, size_t size_of_hash_dgst, uint8_t *out_sign, size_t  signature_data_max_size, size_t * signature_data_act_size_out);
00102 
00103 /**Extracts public raw key data from public der key
00104 *
00105 *@der_key[in] - DER public key data.
00106 *@der_key_length[in] - public key data size
00107 *@raw_key_data_out[out] - raw key out buffer
00108 *@raw_key_data_max_size[in] - size of raw key out buffer
00109 *@raw_key_data_act_size_out[out] - actual output size of raw key
00110 * @return
00111 *     KCM_STATUS_SUCCESS on success, otherwise appropriate error from  kcm_status_e.
00112 */
00113 kcm_status_e  cs_get_pub_raw_key_from_der(const uint8_t *der_key, size_t der_key_length, uint8_t *raw_key_data_out, size_t raw_key_data_max_size, size_t *raw_key_data_act_size_out);
00114 
00115 /**Verifies correlation between private and public key.
00116 *
00117 *@priv_key_data[in] - DER private key data.
00118 *@priv_key_data_size[in] - private key data size
00119 *@pub_key_data[in] - DER private key data.
00120 *@pub_key_data_size[in] - private key data size
00121 * @return
00122 *     KCM_STATUS_SUCCESS on success, otherwise appropriate error from  kcm_status_e.
00123 */
00124 kcm_status_e  cs_verify_key_pair(const uint8_t *priv_key_data, size_t priv_key_data_size, const uint8_t *pub_key_data, size_t pub_key_data_size);
00125 
00126 /** Generate a key pair complying the given crypto scheme DER.
00127 *
00128 * @param curve_name The curve name
00129 * @param priv_key_out Out buffer for private key to generate in DER format.
00130 * @param priv_key_max_size Size of the private key buffer
00131 * @param priv_key_act_size_out Actual private key size in bytes.
00132 * @param pub_key_out Out buffer for public key to generate in DER format. Send NULL if no public key needed.
00133 * @param pub_key_max_size Size of the public key buffer
00134 * @param pub_key_act_size_out Actual public key size in bytes.
00135 *
00136 * @returns
00137 * Operation status.
00138 */
00139 kcm_status_e  cs_key_pair_generate(kcm_crypto_key_scheme_e curve_name,
00140                                   uint8_t *priv_key_out,
00141                                   size_t priv_key_max_size,
00142                                   size_t *priv_key_act_size_out,
00143                                   uint8_t *pub_key_out,
00144                                   size_t pub_key_max_size,
00145                                   size_t *pub_key_act_size_out);
00146 
00147 /** Generate a general CSR from the given private key.
00148 * @param priv_key The private key buffer in DER format.
00149 * @param priv_key_size The private key buffer size.
00150 * @param csr_params Pointer to CSR request params struct.
00151 * @param csr_buff_out Out buffer for CSR to generate in DER format.
00152 * @param csr_buff_max_size Size of the CSR buffer
00153 * @param csr_buff_act_size_out Actual CSR size in bytes.
00154 *
00155 * @returns
00156 * Operation status.
00157 */
00158 kcm_status_e  cs_csr_generate(const uint8_t *priv_key,
00159                              size_t priv_key_size,
00160                              const kcm_csr_params_s *csr_params,
00161                              uint8_t *csr_buff_out,
00162                              size_t csr_buff_max_size,
00163                              size_t *csr_buff_act_size_out);
00164 
00165 /** Generate private key and CSR from the given crypto scheme DER.
00166 * @param curve_name The curve name
00167 * @param csr_params Pointer to CSR request params struct.
00168 * @param priv_key_out Out buffer for private key to generate in DER format.
00169 * @param priv_key_max_size Size of the private key buffer
00170 * @param priv_key_act_size_out Actual private key size in bytes.
00171 * @param pub_key_out Out buffer for public key to generate in DER format. Send NULL if no public key needed.
00172 * @param pub_key_max_size Size of the public key buffer
00173 * @param pub_key_act_size_out Actual public key size in bytes.
00174 * @param csr_buff_out Out buffer for CSR to generate in DER format.
00175 * @param csr_buff_max_size Size of the CSR buffer
00176 * @param csr_buff_act_size_out Actual CSR size in bytes.
00177 *
00178 * @returns
00179 * Operation status.
00180 */
00181 kcm_status_e  cs_generate_keys_and_csr(kcm_crypto_key_scheme_e curve_name,
00182                                       const kcm_csr_params_s *csr_params,
00183                                       uint8_t *priv_key_out,
00184                                       size_t priv_key_max_size,
00185                                       size_t *priv_key_act_size_out,
00186                                       uint8_t *pub_key_out,
00187                                       size_t pub_key_max_size,
00188                                       size_t *pub_key_act_size_out,
00189                                       uint8_t *csr_buff_out,
00190                                       const size_t csr_buff_max_size,
00191                                       size_t *csr_buff_act_size_out);
00192 
00193 /** Allocates and initializes a key object and return the key handle.
00194 *
00195 *   @param key_h_out[out] A handle to a key object in store.
00196 *
00197 *   @returns
00198 *       KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00199 */
00200 kcm_status_e  cs_ec_key_new(cs_key_handle_t *key_h_out);
00201 
00202 /** Frees the allocated bytes of the key handle.
00203 *
00204 *   @param key_h[in] A pointer to the handle that represents the key object in store.
00205 *
00206 *   @returns
00207 *       KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00208 */
00209 kcm_status_e  cs_ec_key_free(cs_key_handle_t *key_h);
00210 
00211 /** Generates key pair and a CSR from a given certificate name.
00212 *   The function will search for the certificate in store.
00213 *
00214 *   @param certificate[in] A pointer to a valid buffer that holds the certificate bytes
00215 *   @param certificate_size[in] The certificate octets length
00216 *   @param key_h[out] A handle to the CSR key object.
00217 *   @param csr_out[out] A pointer to a newly allocated buffer that accommodate the CSR
00218 *   @param csr_max_size[in] The max size in bytes of csr_out buffer
00219 *   @param csr_actual_size_out[in] The actual size in bytes of csr_out buffer
00220 *
00221 *   @returns
00222 *       KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00223 */
00224 kcm_status_e  cs_generate_keys_and_create_csr_from_certificate(
00225     const uint8_t *certificate,
00226     size_t certificate_size,
00227     cs_key_handle_t csr_key_h,
00228     uint8_t *csr_buff_out,
00229     const size_t csr_buff_max_size,
00230     size_t *csr_buff_act_size_out);
00231 
00232 
00233 /*! The API checks correlation of a certificate
00234 *
00235 *    @param[in] crypto_handle          crypto handle.
00236 *    @param[in] certificate_data       public key buffer(optional).
00237 *    @param[in] certificate_data_len   length of public key buffer.
00238 
00239 storage.
00240 *
00241 *    @returns
00242 *        KCM_STATUS_SUCCESS in case of success or one of the `::kcm_status_e` errors otherwise.
00243 */
00244 
00245 kcm_status_e  cs_verify_items_correlation(cs_key_handle_t crypto_handle, const uint8_t *certificate_data, size_t certificate_data_len);
00246 
00247 #ifdef __cplusplus
00248 }
00249 #endif
00250 
00251 #endif  //__CS_DER_KEYS_H__