sec_prot_certs.h

00001 /*
00002  * Copyright (c) 2016-2019, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef SEC_PROT_CERTS_H_
00019 #define SEC_PROT_CERTS_H_
00020 
00021 /*
00022  * Security protocols certificate interface. This is used by security protocols to
00023  * access certificate information.
00024  *
00025  * Own certificate chain contains the certificate chain that is sent on TLS handshake
00026  * to remote end. Typically this is one certificate long, and the certificate chains
00027  * to root CA certificate or to intermediate certificate known to other end. It is
00028  * also possible to send chain longer than one certificate.
00029  *
00030  * Key on own certificate chain must be the private key of the certificate used on
00031  * TLS handshake.
00032  *
00033  * Trusted certificate chains contains the root CA certificates and intermediate
00034  * certificates chains that are used to validate remote certificates.
00035  *
00036  */
00037 
00038 #define SEC_PROT_CERT_CHAIN_DEPTH             4
00039 
00040 typedef struct {
00041     uint8_t *cert[SEC_PROT_CERT_CHAIN_DEPTH];           /**< Certificate chain (from bottom up) */
00042     uint16_t cert_len[SEC_PROT_CERT_CHAIN_DEPTH];       /**< Certificate chain length */
00043     uint8_t *key;                                       /**< Private key */
00044     uint8_t key_len;                                    /**< Private key length*/
00045     ns_list_link_t link;                                /**< Link */
00046 } cert_chain_entry_t;
00047 
00048 typedef struct {
00049     const uint8_t *crl;                                 /**< Certificate Revocation List */
00050     uint16_t crl_len;                                   /**< Certificate Revocation List length */
00051     ns_list_link_t link;                                /**< Link */
00052 } cert_revocat_list_entry_t;
00053 
00054 typedef NS_LIST_HEAD (cert_chain_entry_t, link) cert_chain_list_t;
00055 typedef NS_LIST_HEAD (cert_revocat_list_entry_t, link) cert_revocat_lists_t;
00056 
00057 typedef struct {
00058     cert_chain_entry_t own_cert_chain;                  /**< Own certificate chain */
00059     cert_chain_list_t trusted_cert_chain_list;          /**< Trusted certificate chain lists */
00060     cert_revocat_lists_t cert_revocat_lists;            /**< Certificate Revocation Lists */
00061     uint16_t own_cert_chain_len;                        /**< Own certificate chain certificates length */
00062     bool ext_cert_valid_enabled : 1;                    /**< Extended certificate validation enabled */
00063 } sec_prot_certs_t;
00064 
00065 /**
00066  * sec_prot_certs_init initialize certificate information
00067  *
00068  * \param certs certificate information
00069  *
00070  * \return < 0 failure
00071  * \return >= 0 success
00072  */
00073 int8_t sec_prot_certs_init(sec_prot_certs_t *certs);
00074 
00075 /**
00076  * sec_prot_certs_delete delete certificate information
00077  *
00078  * \param certs certificate information
00079  *
00080  */
00081 void sec_prot_certs_delete(sec_prot_certs_t *certs);
00082 
00083 /**
00084  * sec_prot_certs_ext_certificate_validation_set enable or disable extended certificate validation
00085  *
00086  * \param certs    certificate information
00087  * \param enabled  true to enable extended validation, false to disable
00088  *
00089  * \return < 0 failure
00090  * \return >= 0 success
00091  *
00092  */
00093 int8_t sec_prot_certs_ext_certificate_validation_set(sec_prot_certs_t *certs, bool enabled);
00094 
00095 /**
00096  * sec_prot_certs_ext_certificate_validation_get get extended certificate validation setting
00097  *
00098  * \param certs    certificate information
00099  *
00100  * \return true/false enabled or not
00101  *
00102  */
00103 bool sec_prot_certs_ext_certificate_validation_get(const sec_prot_certs_t *certs);
00104 
00105 /**
00106  * sec_prot_certs_own_cert_chain_len_get get length of own certificate chain
00107  *
00108  * \param certs    certificate information
00109  *
00110  * \return length of all the certificates in the own certificate chain
00111  */
00112 uint16_t sec_prot_certs_own_cert_chain_len_get(const sec_prot_certs_t *certs);
00113 
00114 /**
00115  * sec_prot_certs_chain_entry_create allocate memory for certificate chain entry
00116  *
00117  * \return certificate chain entry or NULL
00118  */
00119 cert_chain_entry_t *sec_prot_certs_chain_entry_create(void);
00120 
00121 /**
00122  * sec_prot_certs_chain_entry_init initialize certificate chain entry
00123  *
00124  * \param entry certificate chain entry
00125  */
00126 void sec_prot_certs_chain_entry_init(cert_chain_entry_t *entry);
00127 
00128 /**
00129  * sec_prot_certs_chain_entry_delete deletes certificate chain entry
00130  *
00131  * \param entry certificate chain entry
00132  */
00133 void sec_prot_certs_chain_entry_delete(cert_chain_entry_t *entry);
00134 
00135 /**
00136  * sec_prot_certs_cert_set set certificate to chain entry
00137  *
00138  * \param entry certificate chain entry
00139  * \param index index for certificate
00140  * \param cert certificate
00141  * \param cert_len certificate length
00142  *
00143  * \return < 0 failure
00144  * \return >= 0 success
00145  */
00146 int8_t sec_prot_certs_cert_set(cert_chain_entry_t *entry, uint8_t index, uint8_t *cert, uint16_t cert_len);
00147 
00148 /**
00149  * sec_prot_certs_cert_get get certificate from chain entry
00150  *
00151  * \param entry certificate chain entry
00152  * \param index index for certificate
00153  * \param cert_len certificate length
00154  *
00155  * \return pointer to certificate or NULL
00156  */
00157 uint8_t *sec_prot_certs_cert_get(const cert_chain_entry_t *entry, uint8_t index, uint16_t *cert_len);
00158 
00159 /**
00160  * sec_prot_certs_cert_chain_entry_len_get get length of certificate chain on cert chain entry
00161  *
00162  * \param entry certificate chain entry
00163  *
00164  * \return total length of all the certificates in the entry
00165  */
00166 uint16_t sec_prot_certs_cert_chain_entry_len_get(const cert_chain_entry_t *entry);
00167 
00168 /**
00169  * sec_prot_certs_priv_key_set set certificate (chain) private key
00170  *
00171  * \param entry certificate chain entry
00172  * \param key key
00173  * \param key_len key length
00174  *
00175  * \return < 0 failure
00176  * \return >= 0 success
00177  */
00178 int8_t sec_prot_certs_priv_key_set(cert_chain_entry_t *entry, uint8_t *key, uint8_t key_len);
00179 
00180 /**
00181  * sec_prot_certs_priv_key_get get certificate (chain) private key
00182  *
00183  * \param entry certificate chain entry
00184  * \param key_len key length
00185  *
00186  * \return pointer to key or NULL
00187  */
00188 uint8_t *sec_prot_certs_priv_key_get(const cert_chain_entry_t *entry, uint8_t *key_len);
00189 
00190 /**
00191  * sec_prot_certs_chain_list_add add certificate chain entry to certificate chain list
00192  *
00193  * \param cert_chain_list certificate chain entry list
00194  * \param entry certificate chain entry
00195  */
00196 void sec_prot_certs_chain_list_add(cert_chain_list_t *cert_chain_list, cert_chain_entry_t *entry);
00197 
00198 /**
00199  * sec_prot_certs_chain_list_delete delete certificate chain list
00200  *
00201  * \param cert_chain_list certificate chain entry list
00202  */
00203 void sec_prot_certs_chain_list_delete(cert_chain_list_t *chain_list);
00204 
00205 /**
00206  * sec_prot_certs_chain_list_entry_delete deletes entry from certificate chain list
00207  *
00208  * \param cert_chain_list certificate chain entry list
00209  * \param entry deleted certificate chain entry
00210  *
00211  */
00212 void sec_prot_certs_chain_list_entry_delete(cert_chain_list_t *chain_list, cert_chain_entry_t *entry);
00213 
00214 /**
00215  * sec_prot_certs_chain_list_entry_find finds entry from certificate chain list
00216  *
00217  * \param cert_chain_list certificate chain entry list
00218  * \param entry searched certificate chain entry
00219  *
00220  * \return certificate chain entry or NULL
00221  *
00222  */
00223 cert_chain_entry_t *sec_prot_certs_chain_list_entry_find(cert_chain_list_t *chain_list, cert_chain_entry_t *entry);
00224 
00225 /**
00226  * sec_prot_certs_revocat_list_entry_create allocate memory for certificate revocation list entry
00227  *
00228  * \return certificate revocation list entry or NULL
00229  */
00230 cert_revocat_list_entry_t *sec_prot_certs_revocat_list_entry_create(void);
00231 
00232 /**
00233  * sec_prot_certs_revocat_list_entry_init initialize certificate revocation list entry
00234  *
00235  * \param entry certificate revocation list entry
00236  */
00237 void sec_prot_certs_revocat_list_entry_init(cert_revocat_list_entry_t *entry);
00238 
00239 /**
00240  * sec_prot_certs_revocat_list_entry_delete deletes certificate revocation list entry
00241  *
00242  * \param entry certificate revocation list entry
00243  */
00244 void sec_prot_certs_revocat_list_entry_delete(cert_revocat_list_entry_t *entry);
00245 
00246 /**
00247  * sec_prot_certs_revocat_list_set set certificate revocation list to list entry
00248  *
00249  * \param entry certificate revocation list entry
00250  * \param crl certificate revocation list
00251  * \param crl_len certificate revocation list length
00252  *
00253  * \return < 0 failure
00254  * \return >= 0 success
00255  */
00256 int8_t sec_prot_certs_revocat_list_set(cert_revocat_list_entry_t *entry, const uint8_t *crl, uint16_t crl_len);
00257 
00258 /**
00259  * sec_prot_certs_revocat_list_set set certificate revocation list from list entry
00260  *
00261  * \param entry certificate revocation list entry
00262  * \param crl_len certificate revocation list length
00263  *
00264  * \return pointer to crl or NULL
00265  */
00266 const uint8_t *sec_prot_certs_revocat_list_get(const cert_revocat_list_entry_t *entry, uint16_t *crl_len);
00267 
00268 /**
00269  * sec_prot_certs_revocat_lists_add add certificate revocation list entry to certificate revocation lists
00270  *
00271  * \param cert_revocat_lists certificate revocation lists
00272  * \param entry certificate revocation list entry
00273  */
00274 void sec_prot_certs_revocat_lists_add(cert_revocat_lists_t *cert_revocat_lists, cert_revocat_list_entry_t *entry);
00275 
00276 /**
00277  * sec_prot_certs_revocat_lists_entry_delete delete certificate revocation list entry from certificate revocation lists
00278  *
00279  * \param cert_revocat_lists certificate revocation lists
00280  * \param entry certificate revocation list entry
00281  *
00282  */
00283 void sec_prot_certs_revocat_lists_entry_delete(cert_revocat_lists_t *cert_revocat_lists, cert_revocat_list_entry_t *entry);
00284 
00285 /**
00286  * sec_prot_certs_revocat_lists_entry_find find certificate revocation list entry from certificate revocation lists
00287  *
00288  * \param cert_revocat_lists certificate revocation lists
00289  * \param entry certificate revocation list entry
00290  *
00291  * \return certificate revocation list entry or NULL
00292  */
00293 cert_revocat_list_entry_t *sec_prot_certs_revocat_lists_entry_find(cert_revocat_lists_t *cert_revocat_lists, cert_revocat_list_entry_t *entry);
00294 
00295 /**
00296  * sec_prot_certs_chain_list_delete delete certificate chain list
00297  *
00298  * \param cert_revocat_lists certificate revocation lists
00299  */
00300 void sec_prot_certs_revocat_lists_delete(cert_revocat_lists_t *cert_revocat_lists);
00301 
00302 #endif /* SEC_PROT_CERTS_H_ */