src/security/inc/FSecCert_CertServer.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   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 /**
  18  * @file        FSecCert_CertServer.h
  19  * @brief       This header file contains the declarations of CertServer APIs.
  20  *
  21  * This header file contains the declarations of CertServer APIs.
  22  */
  23
  24 #ifndef _FSEC_CERT_SERVER_H_
  25 #define _FSEC_CERT_SERVER_H_
  26
  27 #include <FOspConfig.h>
  28
  29 #include <FSecCert_CertTypes.h>
  30
  31 namespace Tizen { namespace Security { namespace Cert
  32 {
  33
  34 /**
  35  * @class       _CertServer
  36  * @brief       This class is provide Server API for Certificate Management.
  37  * @since 2.1
  38  *
  39  * The %_CertServer class is used for to provide Certificate Management's Server API.
  40  *
  41  * For more information on the class features, see <a href="../com.osp.cppappprogramming.help/html/dev_guide/security/certificate_namespace.htm">Certificates</a>.
  42  *
  43  */
  44 class _OSP_EXPORT_ _CertServer
  45 {
  46 public:
  47         /**
  48          * This function initializes the Db tables and removes and installs certificates .
  49          *
  50          * @since 2.1
  51          * @return                      An error code.
  52          * @exception           E_SUCCESS                       The method is successful.
  53          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
  54          * @exception           E_SYSTEM                        A system error has occurred.
  55          *                                                                              - File operation failed.
  56          */
  57         static result InitializeDb(void);
  58
  59         /**
  60          * This function initializes the Db tables. If tables are not created already, this function creates the Db tables.
  61          *
  62          * @since 2.1
  63          * @return                      An error code.
  64          * @exception           E_SUCCESS                       The method is successful.
  65          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
  66          * @exception           E_SYSTEM                        A system error has occurred.
  67          *                                                                              - File operation failed.
  68          */
  69         static result Initialize(void);
  70
  71         /**
  72          *      This function reinstall Db.
  73          *
  74          * @since 2.1
  75          * @return                      An error code.
  76          * @exception           E_SUCCESS                       The method is successful.
  77          * @exception           E_SYSTEM                        A system error has occurred.
  78          *                                                                              - File operation error.
  79          *                                                                              - DB operation failed.
  80          */
  81         static result ReInitializeDb(void);
  82
  83         /**
  84          *      This function restores the root CA certificate DB.
  85          *
  86          * @since 2.2
  87          * @return                      An error code.
  88          * @exception           E_SUCCESS                       The method is successful.
  89          * @exception           E_SYSTEM                        A system error has occurred.
  90          *                                                                              - File operation error.
  91          *                                                                              - DB operation failed.
  92          */
  93         static void RestoreRootCaIntegrity(void);
  94
  95         /**
  96          * This function drops the tables and removes all certificate files from the storage.
  97          *
  98          * @since 2.1
  99          * @return                      An error code.
 100          * @exception           E_SUCCESS                       The method is successful.
 101          * @exception           E_SYSTEM                        A system error has occurred.
 102          *                                                                              - File operation failed.
 103          */
 104         static result DropTables(void);
 105
 106         /**
 107          *  This function resets (deletes and creates) db tables.
 108          *
 109          * @since 2.1
 110          * @return                      An error code.
 111          * @exception           E_SUCCESS                       The method is successful.
 112          * @exception           E_SYSTEM                        A system error has occurred.
 113          *                                                                              - File operation error.
 114          *                                                                              - DB operation failed.
 115          */
 116         static result ResetTables(void);
 117
 118         /**
 119          *  This function removes all certificates.
 120          *
 121          * @since 2.1
 122          * @return                      An error code.
 123          * @exception           E_SUCCESS                       The method is successful.
 124          * @exception           E_SYSTEM                        A system error has occurred.
 125          *                                                                              - File operation error.
 126          *                                                                              - DB operation failed.
 127          */
 128         static result MasterReset(void);
 129
 130         /**
 131           * This function installs the certificates into the Db table identified by input type.
 132           *
 133           * @since 2.1
 134           * @return             If success this function returns number of certificates installed in Db tables,
 135           *                 -1 in case of failure, 0 in case of no certificates present in directory.
 136           * @param[in]          type                            Type of certificates to install in Db table.
 137           * @exception          E_SUCCESS                       The method is successful.
 138           * @exception          E_INVALID_ARG           The specified input parameter is invalid.
 139           * @exception          E_OUT_OF_MEMORY         The memory is insufficient.
 140           * @exception          E_SYSTEM                        A system error has occurred.
 141           *                                                                             - File operation failed.
 142           *                                                                             - DB operation failed.
 143           * @remarks        The specific error code can be accessed using the GetLastResult() method.
 144           */
 145         static int InsertCert(_CaCertType type);
 146
 147         /**
 148          *      This function installs all certificates identified by a given certificate type.
 149          *
 150          * @since 2.1
 151          * @return                      An error code.
 152          * @param[in]           certTrustTypes          Certificate type.
 153          * @param[out]          pCertCount                      Number of installed certificates by this function.
 154          * @exception           E_SUCCESS                       The method is successful.
 155          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 156          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 157          * @exception           E_SYSTEM                        A system error has occurred.
 158          *                                                                              - File operation failed.
 159          *                                                                              - DB operation failed.
 160          */
 161         static result InsertCerts(int certTrustTypes, int* pCertCount);
 162
 163         /**
 164          * This function installs the Default root certificate from pBuffer into Db table identified by type and format of the certificate.
 165          *
 166          * @since 2.1
 167          * @return                      An error code.
 168          * @param[in]           type                    Type of the certificate to install in Db table.
 169          * @param[in]           format                  Format of input certificate pBuffer (X.509).
 170          * @param[in]           pCertBuf                Input certificate pBuffer.
 171          * @param[in]           certLen                 Input certificate pBuffer length.
 172          * @exception           E_SUCCESS               The method is successful.
 173          * @exception           E_INVALID_ARG   The specified input parameter is invalid.
 174          * @exception           E_OUT_OF_MEMORY The memory is insufficient.
 175          * @exception           E_SYSTEM                A system error has occurred.
 176          *                                                                      - File operation failed.
 177          *                                                                      - DB operation failed.
 178          */
 179         static result InsertDefaultCaCertificate(_CaCertType type, _CertFormat format, byte* pCertBuf, int certLen);
 180
 181         /**
 182          * This function installs the Default user CA certificates from storage identified.
 183          *
 184          * @since 2.1
 185          * @return                      This function returns count of installed Device certificates.
 186          * @remarks         The specific error code can be accessed using the GetLastResult() method.
 187          *
 188          */
 189         static int InsertUserCaCertificatesToRootDb(void);
 190
 191         /**
 192          *   This function verify certificate chain using DB.
 193          *   Note : It is a certificate chain which contains User certificate without private key.
 194          *   Chain can contain multiple certificate including Device, Intermediate and CA Certificate.
 195          *   If Root CA/Intermediate CA is not present in DB then it should be provided with chain, to be able to verify the certificate.
 196          *
 197          * @since 2.1
 198          * @return                      An error code.
 199          * @param[in]           pCertCtx            Certificate chain context.
 200          * @exception           E_SUCCESS                       The method is successful.
 201          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 202          * @exception           E_OUT_OF_MEMORY     The memory is insufficient.
 203          * @exception           E_SYSTEM                        A system error has occurred.
 204          *                                                                              - File operation failed.
 205          *                                                                              - DB operation failed.
 206          */
 207         static result InsertCertificateChainContext(CertChainCtx pCertCtx);
 208
 209         /**
 210          * This function installs the root certificate from pBuffer into Db table identified by type and format of the certificate.
 211          *
 212          * @since 2.1
 213          * @return              An error code.
 214          * @param[in]           type                            Type of the certificate to install in Db table.
 215          * @param[in]           format                          Format of input certificate pBuffer (X.509).
 216          * @param[in]           pCertBuf                        Input certificate pBuffer.
 217          * @param[in]           certLen                         Input certificate pBuffer length.
 218          * @exception           E_SUCCESS                       The method is successful.
 219          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 220          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 221          * @exception           E_SYSTEM                        A system error has occurred.
 222          *                                                                              - File operation failed.
 223          *                                                                              - DB operation failed.
 224          */
 225         static result InsertCaCertificate(_CaCertType type, _CertFormat format, byte* pCertBuf, int certLen);
 226
 227         /**
 228          * This function installs the user root certificate from buffer into Db table identified by format of the certificate.
 229          *
 230          * @since 2.1
 231          * @return              An error code.
 232          * @param[in]           format                          Format of input certificate buffer (X.509).
 233          * @param[in]           pCert                           Input certificate buffer.
 234          * @param[in]           certLen                         Length of input certificate buffer.
 235          * @exception           E_SUCCESS                       The method is successful.
 236          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 237          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 238          */
 239         static result InsertUserCaCertificate(_CertFormat format, char* pCert, int certLen);
 240
 241         /**
 242          *       This function installs User Root Certificate given by a certificate file path.
 243          *
 244          * @since 2.1
 245          * @return              An error code.
 246          * @param[in]           pFilePath                       Certificate file path where the certificate file is located.
 247          * @exception           E_SUCCESS                       The method is successful.
 248          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 249          * @exception           E_OUT_OF_MEMORY     The memory is insufficient.
 250          * @exception           E_SYSTEM                        A system error has occurred.
 251          *                                                                              - File operation failed.
 252          *                                                                              - DB operation failed.
 253          */
 254         static result InsertUserCaCertificate(byte* pFilePath);
 255
 256         /**
 257          * This function inserts user certificate chain into DB and store certificate and private key(encrypted) in file system.
 258          * The certificate chain should contain chain of certificate, be in order "DeviceCertificate||CA(n)Certificate||.....". Excluding/including Root CA.
 259          * If CA is not present in chain then it should be previously installed. Format of Certificate chain/key should be DER encoded.
 260          * Only one private key must be supplied in private key parameter.
 261          *
 262          * @since 2.1
 263          * @return              An error code.
 264          * @param[in]           pCertChainBuffer                User certificate chain buffer.
 265          * @param[in]           certChainLength                 Certificate chain buffer length.
 266          * @param[in]           pUserPrivateKey                 User private Key buffer.
 267          * @param[in]           userPrivateKeyLength    User private key length.
 268          * @exception           E_SUCCESS                               The method is successful.
 269          * @exception           E_INVALID_ARG                   The specified input parameter is invalid.
 270          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 271          * @exception           E_SYSTEM                                A system error has occurred.
 272          *                                                                                      - File operation failed.
 273          *                                                                                      - DB operation failed.
 274          */
 275         static result InsertUserCertChainPrivateKey(char* pCertChainBuffer, int certChainLength, char* pUserPrivateKey, int userPrivateKeyLength);
 276
 277         /**
 278          * This function inserts user certificate chain including private key into DB and store certificate and private key(encrypted) in file system.
 279          * The certificate chain should contain chain of certificate, be in order "user key || DeviceCertificate||CA(n)Certificate||.....". Excluding/including Root CA.
 280          * If CA is not present in chain then it should be previously installed. Format of Certificate chain/key buffer should be DER encoded.
 281          * Only one private key must be supplied in private key parameter.
 282          *
 283          * @since 2.1
 284          * @return              An error code.
 285          * @param[in]           pCertChainPrivateKeyBuffer  User private key and certificate chain buffer.
 286          * @param[in]           certChainPrivateKeyLength   Private key  and certificate chain buffer length.
 287          * @exception           E_SUCCESS                                       The method is successful.
 288          * @exception           E_INVALID_ARG                           The specified input parameter is invalid.
 289          * @exception           E_OUT_OF_MEMORY             The memory is insufficient.
 290          * @exception           E_SYSTEM                                        A system error has occurred.
 291          *                                                                                              - File operation failed.
 292          *                                                                                              - DB operation failed.
 293          */
 294         static result InsertCertificateChainWithPrivateKey(char* pCertChainPrivateKeyBuffer, int certChainPrivateKeyLength);
 295
 296         /**
 297          *      This function installs PKCS#12 contents into certificate DB and store certificate and private key(encrypted) in file system.
 298          *  Identified by filename and password provided by user.
 299          *
 300          * @since 2.1
 301          * @return              An error code.
 302          * @param[in]           pPkcs12FilePath                 Filename of PKCS#12 content.
 303          * @param[in]           pPkcs12ImportPassword   Password of the PKCS#12 content.
 304          * @exception           E_SUCCESS                               The method is successful.
 305          * @exception           E_INVALID_ARG                   The specified input parameter is invalid.
 306          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 307          * @exception           E_SYSTEM                                A system error has occurred.
 308          *                                                                                      - File operation failed.
 309          *                                                                                      - DB operation error.
 310          *                                                                                      - OpenSSL operation error.
 311          */
 312         static result InsertPkcs12Content(char* pPkcs12FilePath, char* pPkcs12ImportPassword);
 313
 314         /**
 315          *      This function updates Root CA certificate.
 316          *
 317          * @since 2.1
 318          * @return              An error code.
 319          * @param[in]           type                    CA Cert Type.
 320          * @param[in]           pOldCert                Old Certificate Buffer.
 321          * @param[in]           oldCertLen              Old Certificate length.
 322          * @param[in]           pNewCert                New Certificate Buffer.
 323          * @param[in]           newCertLen              New Certificate length.
 324          * @exception           E_SUCCESS                               The method is successful.
 325          * @exception           E_INVALID_ARG                   The specified input parameter is invalid.
 326          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 327          * @exception           E_SYSTEM                                An unexpected system error has occurred.
 328          * @remarks             if same certificate is in Db, replace the certificate using buffer2 and bufferLen2.
 329          */
 330         static result UpdateCaCertificate(_CaCertType type, char* pOldCert, int oldCertLen, char* pNewCert, int newCertLen);
 331
 332         /**
 333          *      This function deletes user certificate chain on the basis of Certificate ID.
 334          *
 335          * @since 2.1
 336          * @return              An error code.
 337          * @param[in]           certId                          Id of certificate as in DB.
 338          * @exception           E_SUCCESS                       The method is successful.
 339          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 340          * @exception           E_OUT_OF_MEMORY     The memory is insufficient.
 341          * @exception           E_SYSTEM                        A system error has occurred.
 342          *                                                                              - File operation error.
 343          *                                                                              - DB operation error.
 344          */
 345         static result RemoveUserCertChainByCertId(int certId);
 346
 347         /**
 348          *       This function un-installs User Root Certificate given by a certificate ID.
 349          *
 350          * @since 2.1
 351          * @return              An error code.
 352          * @param[in]           certId                          Certificate Id.
 353          * @exception           E_SUCCESS                       The method is successful.
 354          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 355          * @exception           E_OUT_OF_MEMORY     The memory is insufficient.
 356          * @exception           E_SYSTEM                        A system error has occurred.
 357          *                                                                              - File operation error.
 358          *                                                                              - DB operation error.
 359          */
 360         static result RemoveUserCaCertificateByCertId(int certId);
 361
 362         /**
 363          *      This function deletes the root certificate
 364          *
 365          * @since 2.1
 366          * @return              An error code.
 367          * @param[in]           type                Ca Cert Type.
 368          * @param[in]           pBuffer             Input Buffer.
 369          * @param[in]       bufLen              Buffer length.
 370          * @exception           E_SUCCESS                       The method is successful.
 371          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 372          * @exception           E_SYSTEM                        A system error has occurred.
 373          *                                                                              - File operation error.
 374          *                                                                              - DB operation error.
 375          * @remarks             if same certificate is in Db, remove the certificate.
 376          */
 377         static result RemoveCaCertificate(_CaCertType type, char* pBuffer, int bufLen);
 378
 379         /**
 380          * This function removes the certificates from storage identified by input certificate type.
 381          *
 382          * @since 2.1
 383          * @return                      An error code.
 384          * @param[in]           type                            Type of certificates to remove.
 385          * @exception           E_SUCCESS                       The method is successful.
 386          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 387          * @exception           E_SYSTEM                        A system error has occurred.
 388          *                                                                              - File operation error.
 389          *                                                                              - DB operation error.
 390          */
 391         static result RemoveCert(_CaCertType type);
 392
 393         /**
 394          *      This function removes all certificates identified by a given certificate type.
 395          *
 396          * @since 2.1
 397          * @return                      An error code.
 398          * @param[in]           certTrustTypes          Certificate types.
 399          * @exception           E_SUCCESS                       The method is successful.
 400          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 401          * @exception           E_SYSTEM                        A system error has occurred.
 402          *                                                                              - File operation error.
 403          *                                                                              - DB operation error.
 404          */
 405         static result RemoveCerts(int certTrustTypes);
 406
 407         /**
 408          * This function removes the Default user CA certificates from the storage identified.
 409          *
 410          * @since 2.1
 411          * @return                      An error code.
 412          * @exception           E_SUCCESS                       The method is successful.
 413          * @exception           E_SYSTEM                        A system error has occurred.
 414          *                                                                              - File operation error.
 415          *                                                                              - DB operation error.
 416          */
 417         static result RemoveUserCaCertificatesFromRootDb(void);
 418
 419         /**
 420          * This function retrieves the user certificate chain on the basis of Subject name of any Intermediate CA and
 421          * subject name of user Certificate. Subject name of Device certificate is optional parameter.
 422          * Subject name of any intermediate Certificate is compulsory parameter.
 423          * This function will retrieve the certificate chain on the basis of Subject name of any intermediate CA taken as
 424          * issuer name in function parameters. It can also extract Certificate chain on the basis of Subject name of device
 425          * certificate including chain containing the Intermediate Certificate Subject name.
 426          * If there are multiple cert chain from the same issuer, it will get all the cert chain and check with subject name
 427          * to decide which chain is need to be returned. For input parameter it takes subject name of any intermediate CA as
 428          * issuer name, and subject name of user certificate as optional parameter. Format of Subject and Issuer name will
 429          * be DER encoded.
 430          *
 431          * @since 2.1
 432          * @return              An error code.
 433          * @param[in]           pIssuerName                 Pointer to Issuer name.
 434          * @param[in]           issuerNameLength            Length of Issuer name.
 435          * @param[in]           pSubjectName                pointer to Subject name.
 436          * @param[in]           subjectNameLength           Length of Subject name.
 437          * @param[out]          pUserCertListInfoTypesRef       Pointer to certificate list.
 438          * @exception           E_SUCCESS                                       The method is successful.
 439          * @exception           E_INVALID_ARG                           The specified input parameter is invalid.
 440          * @exception           E_OUT_OF_MEMORY             The memory is insufficient.
 441          * @exception           E_SYSTEM                                        An unexpected system error has occurred.
 442          */
 443         static result GetUserCertChainByIssuerAndSubjectNameN(char* pIssuerName, int issuerNameLength, char* pSubjectName, int subjectNameLength, _CertificateListInfo*& pUserCertListInfoTypesRef);
 444
 445         /**
 446          *        This function gets the user certificate list information by requested certificate ID. It give info of certificate only.
 447          *
 448          * @since 2.1
 449          * @return              An error code.
 450          * @param[in]       certId                          Certificate Id as in Db.
 451          * @param[in]       encodingType                    Required encoding type of output buffer (PEM, Base64 or DER).
 452          * @param[out]      ppUserCertificateListInfoTypes  Pointer to pointer of Certificate list structure.
 453          * @exception           E_SUCCESS                                               The method is successful.
 454          * @exception           E_INVALID_ARG                                   The specified input parameter is invalid.
 455          * @exception           E_OUT_OF_MEMORY                 The memory is insufficient.
 456          * @exception           E_SYSTEM                                                An unexpected system error has occurred.
 457          */
 458         static result GetUserCertificateByCertIdN(int certId, _CertEncodingType encodingType, _CertInfo*& pUserCertificateInfoRef);
 459
 460         /**
 461          *        This function retrieves user certificate information by requested certificate ID.
 462          *
 463          * @since 2.1
 464          * @return              An error code.
 465          * @param[in]       certId              Certificate id of requested user certificates as in DB.
 466          * @param[out]      pCertFieldInfos             Pointer to pointer of Certificate infos structure.
 467          * @exception           E_SUCCESS                       The method is successful.
 468          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 469          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 470          */
 471         static result GetUserCertFieldInfoByCertId(int certId, _CertFieldInfos* pCertFieldInfos);
 472
 473         /**
 474          *      This function provides list of installed certificate by type.
 475          *
 476          * @since 2.1
 477          * @return                  If success give handle of root cert, null in case of failure.
 478          * @param[in]           type        _CaCertType, Type of certificate.
 479          * @param[out]          count           Number of installed certificate.
 480          * @remarks         The specific error code can be accessed using the GetLastResult() method.
 481          */
 482         static CertificateStoreCtx OpenCertificateStoreByType(_CaCertType type, int* pCount);
 483
 484         /**
 485          *      This function closes root Certificate Handle.
 486          *
 487          * @since 2.1
 488          * @return              An error code.
 489          * @param[in]           certificateStoreCtx          Certificate store context, can be get using OpenCertificateStoreByType function..
 490          * @exception           E_SUCCESS                       The method is successful.
 491          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 492          */
 493         static result CloseCertificateStore(CertificateStoreCtx certificateStoreCtx);
 494
 495         /**
 496          *      This function counts Root CA.
 497          *
 498          * @since 2.1
 499          * @return                      Count of Root CA, -1 in case of failure.
 500          * @param[in]           certificateStoreCtx          Certificate store context, can be get using OpenCertificateStoreByType function.
 501          * @remarks         The specific error code can be accessed using the GetLastResult() method.
 502          */
 503         static int GetCertificateCount(CertificateStoreCtx certificateStoreCtx);
 504
 505         /**
 506          *      This function returns the next root CA pBuffer.
 507          *
 508          * @since 2.1
 509          * @return              An error code.
 510          * @param[in]           certificateStoreCtx          Certificate store context, can be get using OpenCertificateStoreByType function..
 511          * @param[out]          pBuffer                         Output Buffer.
 512          * @param[in,out]       pBufferLen                      Buffer length.
 513          * @exception           E_SUCCESS                       The method is successful.
 514          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 515          */
 516         static result GetNextCertificate(CertificateStoreCtx certificateStoreCtx, int& curPos, char* pBuffer, int* pBufferLen);
 517
 518 private:
 519         _CertServer(void);
 520
 521         _CertServer(const _CertServer& rhs);
 522
 523         ~_CertServer(void);
 524
 525         _CertServer& operator =(const _CertServer& rhs);
 526
 527 }; //_CertServer
 528
 529 } } } //Tizen::Security::Cert
 530
 531 #endif  // _FSEC_CERT_SERVER_H_