vcore/src/cert-svc/cpkcs12.h

   1 /**
   2  * Copyright (c) 2015 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  * @file        cpkcs12.h
  18  * @author      Jacek Migacz (j.migacz@samsung.com)
  19  * @author      Bartlomiej Grzelewski (b.grzelewski@samsung.com)
  20  * @brief       This is part of C api for PKCS#12/PFX storage routines.
  21  */
  22 #ifndef _CERTSVC_CPKCS12_H_
  23 #define _CERTSVC_CPKCS12_H_
  24
  25 #include <cert-svc/cinstance.h>
  26 #include <cert-svc/cstring.h>
  27 #include <cert-svc/ccert.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /**
  34  * Check whenever PKCS#12 container is password protected.
  35  *
  36  * @param[in] instance CertSvcInstance object.
  37  * @param[in] path Path to container file.
  38  * @param[out] has_password CERTSVC_TRUE (if container is password protected) or CERTSVC_FALSE.
  39  * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT
  40  */
  41 int certsvc_pkcs12_has_password(CertSvcInstance instance,
  42                                 CertSvcString filepath,
  43                                 int *has_password);
  44
  45 /**
  46  * Couter-routine for certsvc_pkcs12_private_key_dup.
  47  *
  48  * @param[in] pointer Memory claimed by private key.
  49  */
  50 void certsvc_pkcs12_private_key_free(char *buffer);
  51
  52 /**
  53  * This function will load to memory private file content. This functin will
  54  * not parse it in any way.
  55  * This memory must be freed by certsvc_private_key_free.
  56  *
  57  * @param[in] instance CertSvcInstance object.
  58  * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
  59  * @param[in] gname Container bundle identifier.
  60  * @param[out] certBuffer Poiner to newly-allocated memory with private key data.
  61  * @param[out] certsize Size of the newly-allocated buffer. Zero means there is no key.
  62  * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT
  63  */
  64 int certsvc_pkcs12_private_key_dup_from_store(CertSvcInstance instance,
  65                                               CertStoreType storeType,
  66                                               CertSvcString gname,
  67                                               char **certBuffer,
  68                                               size_t *certsize);
  69
  70 /**
  71  * This function will set the status for the specified certificate in a particular
  72  * store to enabled / disabled.
  73  *
  74  * @param[in] instance CertSvcInstance object.
  75  * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
  76  * @param[in] is_root_app Set to ENABLED/DISABLED. Should be ENABLED if master application is changing the status, else DISABLED for other applications.
  77  * @param[in] gname Referred as group name, is the key for accessing the certificate.
  78  * @param[in] status Allows to set the status of the certificate to enabled / disabled.
  79  * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
  80  */
  81 int certsvc_pkcs12_set_certificate_status_to_store(CertSvcInstance instance,
  82                                             CertStoreType storeType,
  83                                             int is_root_app,
  84                                             CertSvcString gname,
  85                                             CertStatus status);
  86
  87 /**
  88  * This function will get the status for the specified certificate in a particular
  89  * store.
  90  *
  91  * @param[in] instance CertSvcInstance object.
  92  * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
  93  * @param[in] gname Referred as group name, is the key for accessing the certificate.
  94  * @param[out] status refers to weather the certificate is enabled/disabled.
  95  * @return Disable=0, Enable=1, Fail=-1
  96  */
  97 int certsvc_pkcs12_get_certificate_status_from_store(CertSvcInstance instance,
  98                                               CertStoreType storeType,
  99                                               CertSvcString gname,
 100                                               CertStatus *status);
 101
 102 /**
 103  * This function will get the Alias name, Path to certificate, Certificate status of all
 104  * the certificates present in the specified certificate store.
 105  *
 106  * @param[in] instance CertSvcInstance object.
 107  * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
 108  * @param[out] certList Linked-list having all the information about each certificate present in a store.
 109  * @param[out] length Provides the length of the linked list.
 110  * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
 111  */
 112 int certsvc_pkcs12_get_certificate_list_from_store(CertSvcInstance instance,
 113                                             CertStoreType storeType,
 114                                             int is_root_app,
 115                                             CertSvcStoreCertList** certList,
 116                                             size_t *length);
 117
 118 /**
 119  * This function will get the Alias name, Path to certificate, Certificate status of all
 120  * the end user certificates present in the specified certificate store.
 121  *
 122  * @param[in] instance CertSvcInstance object.
 123  * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
 124  * @param[out] certList Linked-list having all the information about each certificate present in a store.
 125  * @param[out] length Provides the length of the linked list.
 126  * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
 127  */
 128 int certsvc_pkcs12_get_end_user_certificate_list_from_store(CertSvcInstance instance,
 129                                             CertStoreType storeType,
 130                                             CertSvcStoreCertList** certList,
 131                                             size_t* length);
 132
 133 /**
 134  * This function will get the Alias name, Path to certificate, Certificate status of all
 135  * the root/trusted certificates present in the specified certificate store.
 136  *
 137  * @param[in] instance CertSvcInstance object.
 138  * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
 139  * @param[out] certList Linked-list having all the information about each certificate present in a store.
 140  * @param[out] length Provides the length of the linked list.
 141  * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
 142  */
 143 int certsvc_pkcs12_get_root_certificate_list_from_store(CertSvcInstance instance,
 144                                             CertStoreType storeType,
 145                                             CertSvcStoreCertList** certList,
 146                                             size_t* length);
 147
 148 /**
 149  * This function will free all the linked list of data structure holding the information about
 150  * all the certificates present in a store which was previously by calling the
 151  * certsvc_get_certificate_list_from_store() function.
 152  *
 153  * @param[in] instance CertSvcInstance object.
 154  * @param[in] certList The structure which need to be freed.
 155  * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
 156  */
 157 int certsvc_pkcs12_free_certificate_list_loaded_from_store(CertSvcInstance instance,
 158                                                     CertSvcStoreCertList** certList);
 159
 160 /**
 161  * This function will provide the certificate back for the gname provided.
 162  *
 163  * @param[in] instance CertSvcInstance object.
 164  * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
 165  * @param[in[ gname Referred as group name, is the key for accessing the certificate.
 166  * @param[out] certificate Certificate holding the information.
 167  * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_BAD_ALLOC
 168  */
 169 int certsvc_pkcs12_get_certificate_from_store(CertSvcInstance instance,
 170                                        CertStoreType storeType,
 171                                        const char *gname,
 172                                        CertSvcCertificate *certificate);
 173
 174 /**
 175  * This function will give back the the encoded certificate buffer for the matching
 176  * alias present in the specified store.
 177  *
 178  * @param[in] instance CertSvcInstance object.
 179  * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
 180  * @param[in] gname Referred as group name, is the key for accessing the certificate.
 181  * @param[out] certBuffer Buffer containing the encoded certificate.
 182  * @param[out] certSize Size of the buffer.
 183  * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
 184  */
 185 int certsvc_pkcs12_get_certificate_info_from_store(CertSvcInstance instance,
 186                                             CertStoreType storeType,
 187                                             CertSvcString gname,
 188                                             char** certBuffer,
 189                                             size_t* certSize);
 190
 191 /**
 192  * This function will import a .pfx/.p12 file to specified store (WIFI, VPN, EMAIL).
 193  *
 194  * @param[in] instance CertSvcInstance object.
 195  * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
 196  * @param[in] path Path of the certificate which needs to be imported.
 197  * @param[in] password Password to open the pfx/p12 file.
 198  * @param[in] alias Logical name for certificate bundle identification (can't be empty).
 199  * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
 200  */
 201 int certsvc_pkcs12_import_from_file_to_store(CertSvcInstance instance,
 202                                              CertStoreType storeType,
 203                                              CertSvcString path,
 204                                              CertSvcString password,
 205                                              CertSvcString alias);
 206
 207 /**
 208  * This function will delete the certificate from the path specified present in the specified store.
 209  *
 210  * @param[in] instance CertSvcInstance object.
 211  * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
 212  * @param[in] gname Referred as group name, is the key for accessing the certificate.
 213  * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_IO_ERROR, CERTSVC_WRONG_ARGUMENT, CERTSVC_INVALID_STORE_TYPE
 214  */
 215 int certsvc_pkcs12_delete_certificate_from_store(CertSvcInstance instance,
 216                                           CertStoreType storeType,
 217                                           CertSvcString gname);
 218
 219 /**
 220  * Query PKCS#12 storage to find out whenever new alias proposal is unique.
 221  *
 222  * @param[in] instance CertSvcInstance object.
 223  * @param[in] storeType Refers to VPN_STORE / WIFI_STORE / EMAIL_STORE / SYSTEM_STORE / ALL_STORE.
 224  * @param[in] proposal Desired alias name.
 225  * @param[out] is_unique CERTSVC_TRUE (if there isn't such alias already) or CERTSVC_FALSE.
 226  * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
 227  */
 228 int certsvc_pkcs12_check_alias_exists_in_store(CertSvcInstance instance,
 229                                          CertStoreType storeType,
 230                                          CertSvcString alias,
 231                                          int *is_unique);
 232
 233 /**
 234  * Get a list of certificates from PKCS#12 bundle. You may free this list by:
 235  * certsvc_certificate_list_free. You may free certificates from list with:
 236  * certsvc_certificate_free.
 237  *
 238  * @param[in] instance CertSvcInstance object.
 239  * @param[in] pfxIdString Identification of pfx/pkcs file.
 240  * @param[out] certificateList List of certificates.
 241  * @return CERTSVC_SUCCESS, CERTSVC_BAD_ALLOC, CERTSVC_FAIL, CERTSVC_IO_ERROR
 242  */
 243 int certsvc_pkcs12_load_certificate_list_from_store(CertSvcInstance instance,
 244                                                     CertStoreType storeType,
 245                                                     CertSvcString pfxIdString,
 246                                                     CertSvcCertificateList *certificateList);
 247
 248 /**
 249  * Gets the alias name for the gname passed.
 250  *
 251  * @param[in] instance CertSvcInstance object.
 252  * @param[in] gname Certificate identification of pfx/pkcs file.
 253  * @param[out] alias Alias name for the given gname.
 254  * @return CERTSVC_SUCCESS, CERTSVC_FAIL, CERTSVC_WRONG_ARGUMENT
 255  */
 256 int certsvc_pkcs12_get_alias_name_for_certificate_in_store(CertSvcInstance instance,
 257                                                     CertStoreType storeType,
 258                                                     CertSvcString gname,
 259                                                     char **alias);
 260
 261 #ifdef __cplusplus
 262 }
 263 #endif
 264
 265 #endif