src/cert-svc/cpkcs12.h

   1 /**
   2  * Copyright (c) 2016 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]  filepath      File path to check
  38  * @param[out] has_password  #1 if password protectedm, else #0
  39  *
  40  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
  41  *
  42  * @see certsvc_instance_new()
  43  * @see certsvc_instance_free()
  44  * @see certsvc_string_new()
  45  * @see certsvc_string_free()
  46  */
  47 int certsvc_pkcs12_has_password(CertSvcInstance instance,
  48                                                                 CertSvcString filepath,
  49                                                                 int *has_password);
  50
  51 /**
  52  * Couter-routine for certsvc_pkcs12_private_key_dup.
  53  *
  54  * @param[in] buffer   Memory claimed by private key
  55  */
  56 void certsvc_pkcs12_private_key_free(char *buffer);
  57
  58 /**
  59  * Load to memory of private key in cert-svc store with @a gname.
  60  *
  61  * @param[in]  instance   CertSvcInstance object
  62  * @param[in]  storeType  cert-svc store type to query
  63  * @param[in]  gname      Single certificate identifier. It has to be end user's
  64  *                        to extract private key
  65  * @param[out] buffer     Private key buffer which must be freed after use
  66  * @param[out] size       Size of the returned buffer. Zero when no key is found
  67  *
  68  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
  69  *
  70  * @see certsvc_instance_new()
  71  * @see certsvc_instance_free()
  72  * @see certsvc_string_new()
  73  * @see certsvc_string_free()
  74  * @see #CertStoreType
  75  */
  76 int certsvc_pkcs12_private_key_dup_from_store(CertSvcInstance instance,
  77                 CertStoreType storeType,
  78                 CertSvcString gname,
  79                 char **buffer,
  80                 size_t *size);
  81
  82 /**
  83  * Set the status for the specified certificate in cert-svc store.
  84  *
  85  * @param[in] instance     CertSvcInstance object
  86  * @param[in] storeType    cert-svc store type to query
  87  * @param[in] is_root_app  Should be #ENABLED if master application is changing the status,
  88  *                         else #DISABLED for other applications
  89  * @param[in] gname        Single certificate identifier
  90  * @param[in] status       Status of the certificate to set. [#ENABLED | #DISABLED]
  91  *
  92  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
  93  *
  94  * @see certsvc_instance_new()
  95  * @see certsvc_instance_free()
  96  * @see certsvc_string_new()
  97  * @see certsvc_string_free()
  98  * @see #CertStoreType
  99  * @see #CertStatus
 100  */
 101 int certsvc_pkcs12_set_certificate_status_to_store(CertSvcInstance instance,
 102                 CertStoreType storeType,
 103                 int is_root_app,
 104                 CertSvcString gname,
 105                 CertStatus status);
 106
 107 /**
 108  * Get the status for the specified certificate in cert-svc store.
 109  *
 110  * @param[in]  instance   CertSvcInstance object
 111  * @param[in]  storeType  cert-svc store type to query
 112  * @param[in[  gname      Single certificate identifier
 113  * @param[out] status     Status of the certificate. Enabled:1, Disabled:0, Fail:-1
 114  *
 115  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
 116  *
 117  * @see certsvc_instance_new()
 118  * @see certsvc_instance_free()
 119  * @see certsvc_string_new()
 120  * @see certsvc_string_free()
 121  * @see #CertStroeType
 122  */
 123 int certsvc_pkcs12_get_certificate_status_from_store(CertSvcInstance instance,
 124                 CertStoreType storeType,
 125                 CertSvcString gname,
 126                 CertStatus *status);
 127
 128 /**
 129  * Get the certificates in cert-svc store.
 130  *
 131  * @param[in]  instance     CertSvcInstance object
 132  * @param[in]  storeType    cert-svc store type to query
 133  * @param[in]  is_root_app  Should be #ENABLED if master application is changing the
 134  *                          status, else #DISABLED for other applications
 135  * @param[out] certList     cert list in store returned in linked list. Free by
 136  *                          certsvc_pkcs12_free_certificate_list_loaded_from_store()
 137  *                          after use
 138  * @param[out] length       length of output @a certList
 139  *
 140  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
 141  *
 142  * @see certsvc_instance_new()
 143  * @see certsvc_instance_free()
 144  * @see #CertStoreType
 145  * @see #CertSvcStoreCertList
 146  */
 147 int certsvc_pkcs12_get_certificate_list_from_store(CertSvcInstance instance,
 148                 CertStoreType storeType,
 149                 int is_root_app,
 150                 CertSvcStoreCertList **certList,
 151                 size_t *length);
 152
 153 /**
 154  * Get the end user certificates in cert-svc store.
 155  *
 156  * @param[in]  instance   CertSvcInstance object
 157  * @param[in]  storeType  cert-svc store type to query
 158  * @param[out] certList   cert list in store returned in linked list. Free by
 159  *                        certsvc_pkcs12_free_certificate_list_loaded_from_store() after use
 160  * @param[out] length     length of output @a certList
 161  *
 162  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
 163  *
 164  * @see certsvc_instance_new()
 165  * @see certsvc_instance_free()
 166  * @see #CertStoreType
 167  * @see #CertSvcStoreCertList
 168  */
 169 int certsvc_pkcs12_get_end_user_certificate_list_from_store(CertSvcInstance instance,
 170                 CertStoreType storeType,
 171                 CertSvcStoreCertList **certList,
 172                 size_t *length);
 173
 174 /**
 175  * Get the root/trusted certificates in cert-svc store.
 176  *
 177  * @param[in]  instance   CertSvcInstance object
 178  * @param[in]  storeType  cert-svc store type to query
 179  * @param[out] certList   cert list in store returned in linked list. Free by
 180  *                        certsvc_pkcs12_free_certificate_list_loaded_from_store() after use
 181  * @param[out] length     length of output @a certList
 182  *
 183  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
 184  *
 185  * @see certsvc_instance_new()
 186  * @see certsvc_instance_free()
 187  * @see certsvc_pkcs12_free_certificate_list_loaded_from_store()
 188  * @see #CertStoreType
 189  * @see #CertSvcStoreCertList
 190  */
 191 int certsvc_pkcs12_get_root_certificate_list_from_store(CertSvcInstance instance,
 192                 CertStoreType storeType,
 193                 CertSvcStoreCertList **certList,
 194                 size_t *length);
 195
 196 /**
 197  * Free all @a CertSvcStoreCertList in linked list of data structure.
 198  *
 199  * @param[in] instance  CertSvcInstance object
 200  * @param[in] certList  The structure which need to be freed
 201  *
 202  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
 203  *
 204  * @see certsvc_instance_new()
 205  * @see certsvc_instance_free()
 206  * @see certsvc_pkcs12_get_certificate_list_from_store()
 207  * @see certsvc_pkcs12_get_end_user_certificate_list_from_store()
 208  * @see certsvc_pkcs12_get_root_certificate_list_from_store()
 209  * @see #CertSvcStoreCertList
 210  */
 211 int certsvc_pkcs12_free_certificate_list_loaded_from_store(CertSvcInstance instance,
 212                 CertSvcStoreCertList **certList);
 213
 214 /**
 215  * Get the certificate with the gname provided from cert-svc store.
 216  *
 217  * @param[in]  instance     CertSvcInstance object
 218  * @param[in]  storeType    cert-svc store type to query
 219  * @param[in]  gname        Single certificate identifier
 220  * @param[out] certificate  output in @a CertSvcCertificate format
 221  *
 222  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
 223  *
 224  * @see certsvc_instance_new()
 225  * @see certsvc_instance_free()
 226  * @see certsvc_certificate_free()
 227  * @see #CertStoreType
 228  */
 229 int certsvc_pkcs12_get_certificate_from_store(CertSvcInstance instance,
 230                 CertStoreType storeType,
 231                 const char *gname,
 232                 CertSvcCertificate *certificate);
 233
 234 /**
 235  * Get the encoded certificate buffer with the gname provided from cert-svc store.
 236  *
 237  * @param[in]  instance   CertSvcInstance object
 238  * @param[in]  storeType  cert-svc store type to query
 239  * @param[in]  gname      Single certificate identifier
 240  * @param[out] buffer     The base64 encoded certificate which must be freed after
 241  *                        use
 242  * @param[out] size       Size of the buffer
 243  *
 244  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
 245  *
 246  * @see certsvc_instance_new()
 247  * @see certsvc_instance_free()
 248  * @see certsvc_string_new()
 249  * @see certsvc_string_free()
 250  * @see #CertStoreType
 251  */
 252 int certsvc_pkcs12_get_certificate_info_from_store(CertSvcInstance instance,
 253                 CertStoreType storeType,
 254                 CertSvcString gname,
 255                 char **buffer,
 256                 size_t *size);
 257
 258 /**
 259  * Import PKCS#12 bundle(with .pfx or .p12) or certificate(base64 form with .crt
 260  * or .pem suffix) from file to specified store. If password isn't needed, create
 261  * CertSvcString @a password with null input on certsvc_string_new(). Refer
 262  * certsvc_string_new() API description
 263  *
 264  * @param[in] instance   CertSvcInstance object
 265  * @param[in] storeType  cert-svc store type to query
 266  * @param[in] path       Path of the certificate which needs to be imported
 267  * @param[in] password   Password if the file to import is password-protected which can be
 268  *                       empty CertSvcString in case of not-password-protected
 269  * @param[in] alias      Primary key for certificate bundle identification (can't be empty)
 270  *
 271  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
 272  *
 273  * @see certsvc_instance_new()
 274  * @see certsvc_instance_free()
 275  * @see certsvc_string_new()
 276  * @see certsvc_string_free()
 277  * @see #CertStoreType
 278  */
 279 int certsvc_pkcs12_import_from_file_to_store(CertSvcInstance instance,
 280                 CertStoreType storeType,
 281                 CertSvcString path,
 282                 CertSvcString password,
 283                 CertSvcString alias);
 284
 285
 286 /**
 287  * Import PKCS#12 bundle(with .pfx or .p12) or certificate(base64 form with .crt
 288  * or .pem suffix) from file to specified store and return imported list of certificates.
 289  * If password isn't needed, create CertSvcString @a password with null input on
 290  * certsvc_string_new(). Refer certsvc_string_new() API description
 291  *
 292  * @param[in] instance   CertSvcInstance object
 293  * @param[in] storeType  cert-svc store type to query
 294  * @param[in] path       Path of the certificate which needs to be imported
 295  * @param[in] password   Password if the file to import is password-protected which can be
 296  *                       empty CertSvcString in case of not-password-protected
 297  * @param[in] alias      Primary key for certificate bundle identification (can't be empty)
 298  * @param[out] certList   cert list in store returned in linked list. Free by
 299  *                        certsvc_pkcs12_free_certificate_list_loaded_from_store() after use
 300  * @param[out] length     length of output @a certList
 301  *
 302  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
 303  *
 304  * @see certsvc_instance_new()
 305  * @see certsvc_instance_free()
 306  * @see certsvc_string_new()
 307  * @see certsvc_string_free()
 308  * @see #CertStoreType
 309  */
 310 int certsvc_pkcs12_import_from_file_to_store_ret_list(CertSvcInstance instance,
 311                 CertStoreType storeType,
 312                 CertSvcString path,
 313                 CertSvcString password,
 314                 CertSvcString alias,
 315                 CertSvcStoreCertList **certList,
 316                 size_t *length);
 317
 318 /**
 319  * Delete the certificate with gname provided from cert-svc store.
 320  *
 321  * @param[in] instance   CertSvcInstance object
 322  * @param[in] storeType  cert-svc store type to query
 323  * @param[in] gname      Single certificate identifier
 324  *
 325  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
 326  *
 327  * @see certsvc_instance_new()
 328  * @see certsvc_instance_free()
 329  * @see certsvc_string_new()
 330  * @see certsvc_string_free()
 331  * @see #CertStoreType
 332  */
 333 int certsvc_pkcs12_delete_certificate_from_store(CertSvcInstance instance,
 334                 CertStoreType storeType,
 335                 CertSvcString gname);
 336
 337 /**
 338  * Check the uniqueness of the alias in cert-svc store.
 339  *
 340  * @param[in]  instance   CertSvcInstance object
 341  * @param[in]  storeType  cert-svc store type to query
 342  * @param[in]  alias      Certificates bundle identifier used when importing
 343  * @param[out] is_unique  #CERTSVC_TRUE if the alias is unique, else #CERTSVC_FALSE
 344  *
 345  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
 346  *
 347  * @see certsvc_instance_new()
 348  * @see certsvc_instance_free()
 349  * @see certsvc_string_new()
 350  * @see certsvc_string_free()
 351  * @see #CertStoreType
 352  */
 353 int certsvc_pkcs12_check_alias_exists_in_store(CertSvcInstance instance,
 354                 CertStoreType storeType,
 355                 CertSvcString alias,
 356                 int *is_unique);
 357
 358 /**
 359  * Get list of certificates from PKCS#12 bundle or single certificate which
 360  * is saved in cert-svc store with the alias.
 361  *
 362  * @param[in]  instance         CertSvcInstance object
 363  * @param[in]  alias            Certificates bundle identifier used when importing
 364  * @param[out] certificateList  List of certificates. Free by
 365  *                              certsvc_certificate_list_free() after use
 366  *
 367  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
 368  *
 369  * @see certsvc_instance_new()
 370  * @see certsvc_instance_free()
 371  * @see certsvc_string_new()
 372  * @see certsvc_string_free()
 373  * @see certsvc_certificate_free()
 374  * @see certsvc_certificate_list_free()
 375  * @see #CertStoreType
 376  * @see #CertSvcStoreCertList
 377  */
 378 int certsvc_pkcs12_load_certificate_list_from_store(CertSvcInstance instance,
 379                 CertStoreType storeType,
 380                 CertSvcString alias,
 381                 CertSvcCertificateList *certificateList);
 382
 383 /**
 384  * Get the alias name with the gname provided.
 385  *
 386  * @param[in]  instance  CertSvcInstance object
 387  * @param[in]  gname     Single certificate identifier which is associated with alias
 388  * @param[out] alias     Certificates bundle identifier used when importing which must
 389  *                       be freed after use
 390  *
 391  * @return #CERTSVC_SUCCESS on success, otherwise a zero or negative error value
 392  *
 393  * @see certsvc_instance_new()
 394  * @see certsvc_instance_free()
 395  * @see certsvc_string_new()
 396  * @see certsvc_string_free()
 397  * @see #CertStoreType
 398  */
 399 int certsvc_pkcs12_get_alias_name_for_certificate_in_store(CertSvcInstance instance,
 400                 CertStoreType storeType,
 401                 CertSvcString gname,
 402                 char **alias);
 403
 404 #ifdef __cplusplus
 405 }
 406 #endif
 407
 408 #endif