src/security/inc/FSecCert_CertService.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_CertService.h
  19  * @brief       This header file contains the declarations of CertService APIs.
  20  *
  21  * This header file contains the declarations of CertService APIs.
  22  */
  23
  24 #ifndef _FSEC_CERT_INTERNAL_CERT_SERVICE_H_
  25 #define _FSEC_CERT_INTERNAL_CERT_SERVICE_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       _CertService
  36  * @brief       This class is provide Services API for Certificate Management.
  37  * @since 2.1
  38  *
  39  * The %_CertService class is used for to provide Certificate Management's Services 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_ _CertService
  45 {
  46 public:
  47         /**
  48          *  This function opens the context identified by calling application.
  49          *
  50          * @since 2.1
  51          * @return                      An error code.
  52          * @param[in]           type                            Calling application type.
  53          * @param[out]      pCertCtx                    Pointer to context as out parameter.
  54          * @exception           E_SUCCESS                       The method is successful.
  55          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
  56          * @exception           E_OUT_OF_MEMORY     The memory is insufficient.
  57          */
  58         static result OpenContext(_CertContextType type, CertChainCtx* pCertCtx);
  59
  60         /**
  61          *      This function closes the opened context.
  62          *
  63          * @since 2.1
  64          * @return                      An error code.
  65          * @param[in]           certCtx                         Handle to certificate context.
  66          * @exception           E_SUCCESS                       The method is successful.
  67          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
  68          */
  69         static result CloseContext(CertChainCtx certCtx);
  70
  71         /**
  72          *  This function adds the input certificate in the opened certificate context.
  73          *
  74          * @since 2.1
  75          * @return                      An error code.
  76          * @param[in]           certCtx                         Handle to the certificate context.
  77          * @param[in]           pCertBuf                        Certificate pBuffer.
  78          * @param[in]           certLen                         Certificate pBuffer length.
  79          * @exception           E_SUCCESS                       The method is successful.
  80          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
  81          * @exception           E_OUT_OF_MEMORY     The memory is insufficient.
  82          * @exception           E_SYSTEM                        A system error has occurred.
  83          *                                                                              - Certificate Link list operation error.
  84          */
  85         static result AddCertificate(CertChainCtx certCtx, byte* pCertBuf, int certLen);
  86
  87         /**
  88          *  This function verifies the certificate chain in certificate context with respect to installed root certificates in the device.
  89          *
  90          * @since 2.1
  91          * @return                      An error code.
  92          * @param[in]           certCtx                 Handle to certificate chain context.
  93          * @param[out]          pDomain                 Root certificate domain type.
  94          * @exception           E_SUCCESS               The method is successful.
  95          * @exception           E_INVALID_ARG   The specified input parameter is invalid.
  96          * @exception           E_SYSTEM                A system error has occurred.
  97          *                                                                      - Certificate Link list operation error.
  98          */
  99         static result VerifyChain(CertChainCtx certCtx, _CertDomainType* pDomain);
 100
 101         /**
 102          *  This function verifies the certificate chain in certificate context with respect to installed root certificates in the DB.
 103          *
 104          * @since 2.1
 105          * @return                      An error code.
 106          * @param[in]           pCertCtx            Handle to certificate chain context.
 107          * @exception           E_SUCCESS                       The method is successful.
 108          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 109          * @exception           E_OUT_OF_MEMORY     The memory is insufficient.
 110          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 111          */
 112         static result VerifyCertificateChain(CertChainCtx pCertCtx);
 113
 114         /**
 115          *      This function gets number of certificates in certificate chain represented by context.
 116          *
 117          * @since 2.1
 118          * @return                      An error code.
 119          * @param[in]           certCtx                         Handle to certificate context.
 120          * @param[out]          pDepth                          Chain depth information.
 121          * @exception           E_SUCCESS                       The method is successful.
 122          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 123          */
 124         static result GetChainDepth(CertChainCtx certCtx, int* pDepth);
 125
 126         /**
 127          *      This function gets nth certificate handle of the chain represented by input context
 128          *
 129          * @since 2.1
 130          * @return                      An error code.
 131          * @param[in]           certCtx                         Handle to certificate context.
 132          * @param[in]           nth                                     Position of certificate.
 133          * @param[out]          phCerticate                     Pointer to handle of certificate.
 134          * @exception           E_SUCCESS                       The method is successful.
 135          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 136          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 137          */
 138         static result GetNthCert(CertChainCtx certCtx, int nth, CertificateHandle* phCerticate);
 139
 140         /**
 141          *       This function breaks certificate chain buffer into individual certificate.
 142          *   It is assumed here that there is no Private Key in the Chain.
 143          *   Chain can contain multiple certificate including Device, Intermediate and CA Certificate.
 144          *   This will return a Structure HCertChainCtx containing all the certificates.
 145          *
 146          * @since 2.1
 147          * @return                      An error code.
 148          * @param[in]           pCertChainBuffer        Certificate chain buffer.
 149          * @param[in]           certChainLength         Certificate chain buffer length.
 150          * @param[out]          pCertCtx                        Certificate chain list containing individual certificate.
 151          * @exception           E_SUCCESS                       The method is successful.
 152          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 153          * @exception           E_OUT_OF_MEMORY     The memory is insufficient.
 154          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 155          */
 156         static result GetParsedCertificateChainN(char* pCertChainBuffer, int certChainLength, CertChainCtx* pCertCtx);
 157
 158         /**
 159          * This function retrieves the device certificate chain on the basis of Subject name of Device Certificate.
 160          * This function retrieves the certificate chain on the basis of Subject name of Device Certificate as function
 161          * parameters. If there are multiple cert chain from the same issuer, it will get all the cert chain and check
 162          * with subject name to decide which chain is need to be returned.
 163          *
 164          * @since 2.1
 165          * @return                      An error code.
 166          * @param[in]           pSubjectName            Pointer to Subject name.
 167          * @param[in]           subjectNameLength       Length of Subject name.
 168          * @param[out]          pCertChainCtx           Pointer to certificate chain.
 169          * @param[out]          pPrivateKeyCtx          Pointer to private key info.
 170          * @exception           E_SUCCESS                               The method is successful.
 171          * @exception           E_INVALID_ARG                   The specified input parameter is invalid.
 172          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 173          * @exception           E_SYSTEM                                An unexpected system error has occurred.
 174          */
 175         static result GetUserCertChainBySubjectName(char* pSubjectName, int subjectNameLength, CertChainCtx* pCertChainCtx, PrivateKeyCtx* pPrivateKeyCtx);
 176
 177         /**
 178          *      This function returns the handle of certificate of input binary or base64 certificate pBuffer.
 179          *
 180          * @since 2.1
 181          * @return                      An error code.
 182          * @param[in]           pBuffer                         Buffer of certificate.
 183          * @param[in]           bufLen                          Length of input pBuffer.
 184          * @param[out]          pCertHandle                     Handle to the certificate out.
 185          * @exception           E_SUCCESS                       The method is successful.
 186          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 187          * @exception           E_OUT_OF_MEMORY     The memory is insufficient.
 188          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 189          */
 190         static result OpenCertificate(char* pBuffer, int bufLen, CertificateHandle* pCertHandle);
 191
 192         /**
 193          *      This function closes the handle of certificate .
 194          *
 195          * @since 2.1
 196          * @return                      An error code.
 197          * @param[in]           pCertHandle                     Handle to the certificate to close.
 198          * @exception           E_SUCCESS                       The method is successful.
 199          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 200          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 201          * @remarks        This function is not applicable to handle which is received by context APIs.
 202          */
 203         static result CloseCertificate(CertificateHandle* pCertHandle);
 204
 205         /**
 206          *  This function verifies a certificate using given Public key.
 207          *
 208          * @since 2.1
 209          * @return                      An error code.
 210          * @param[in]           certHandle                      Handle to certificate.
 211          * @param[in]           pPublickey                      Certificate Public Key.
 212          * @param[in]           keyLen                          Certificate Public Key length.
 213          * @exception           E_SUCCESS                       The method is successful.
 214          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 215          * @exception           E_SYSTEM                        A system error has occurred.
 216          *                                                                              - Certificate Link list operation error.
 217          */
 218         static result VerifyCert(CertificateHandle certHandle, byte* pPublickey, int keyLen);
 219
 220         /**
 221          *      This function gets certificate pBuffer using the certificate handle.
 222          *
 223          * @since 2.1
 224          * @return                      An error code.
 225          * @param[in]           certHandle                      Handle to certificate.
 226          * @param[out]          pBuffer                         Pointer to certificate pBuffer.
 227          * @param[out]          certLen                         Output pBuffer length of certificate.
 228          * @exception           E_SUCCESS                       The method is successful.
 229          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 230          * @exception           E_OUT_OF_MEMORY     The memory is insufficient.
 231          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 232          */
 233         static result GetCertBufferN(CertificateHandle certHandle, char*& pBuffer, int* certLen);
 234
 235         /**
 236          *      This function returns database Id of Ca certificate for given certificate handle.
 237          *
 238          * @since 2.1
 239          * @return                      An error code.
 240          * @param[in]           certHandle                      Handle to the certificate.
 241          * @param[in]           certType                        Type of certificate store.
 242          * @param[out]          certId                          Reference to integer to get certificate data Id.
 243          * @exception           E_SUCCESS                       The method is successful.
 244          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 245          * @exception           E_OUT_OF_MEMORY     The memory is insufficient.
 246          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 247          */
 248         static result GetCaCertificateId(CertificateHandle certHandle, _CaCertType certType, int& certId);
 249
 250         /**
 251          *      This function returns database Id of User certificate for given certificate handle.
 252          *
 253          * @since 2.1
 254          * @return                      An error code.
 255          * @param[in]           certHandle                      Handle to the certificate.
 256          * @param[out]          certId                          Reference to integer to get certificate data Id.
 257          * @exception           E_SUCCESS                       The method is successful.
 258          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 259          * @exception           E_OUT_OF_MEMORY     The memory is insufficient.
 260          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 261          */
 262         static result GetUserCertificateId(CertificateHandle certHandle, int& certId);
 263
 264         /**
 265          *      This function returns information of certificate requested by _CertFieldType parameter.
 266          *
 267          * @since 2.1
 268          * @return                      An error code.
 269          * @param[in]           certHandle                      Handle to the certificate.
 270          * @param[in]           field                           Type of combination of information required.
 271          * @param[out]          pCertInfo                       Pointer to certificate information structure.
 272          * @exception           E_SUCCESS                       The method is successful.
 273          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 274          * @exception           E_OUT_OF_MEMORY     The memory is insufficient.
 275          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 276          */
 277         static result GetCertInfo(CertificateHandle certHandle, _CertFieldType field, _CertFieldInfos* pCertInfo);
 278
 279         /**
 280          *      This function returns Public key of certificate in DER format.
 281          *
 282          * @since 2.1
 283          * @return                      An error code.
 284          * @param[in]           certHandle          Handle to the certificate.
 285          * @param[out]      pBuffer                             Buffer to contain public key.
 286          * @param[in,out]       pBufLen                         Length of Public Key.
 287          * @exception           E_SUCCESS                       The method is successful.
 288          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 289          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 290          */
 291         static result GetCertPublicKey(CertificateHandle certHandle, char* pBuffer, int* pBufLen);
 292
 293         /**
 294          *      This function returns Signature of certificate.
 295          *
 296          * @since 2.1
 297          * @return                      An error code.
 298          * @param[in]           certHandle          Handle to the certificate.
 299          * @param[out]      pBuffer                             Buffer to contain Signature.
 300          * @param[in,out]       bufLen                          Length of Signature.
 301          * @exception           E_SUCCESS                       The method is successful.
 302          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 303          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 304          */
 305         static result GetCertSignature(CertificateHandle certHandle, char* pBuffer, int* pBufLen);
 306
 307         /**
 308          *      This function returns Version of X509 certificate.
 309          *
 310          * @since 2.1
 311          * @return                      certificate version number as integer, -1 in case of failure.
 312          * @param[in]           certHandle        Handle to the certificate.
 313          * @remarks         The specific error code can be accessed using the GetLastResult() method.
 314          */
 315         static int GetCertVersion(CertificateHandle certHandle);
 316
 317         /**
 318          *       This function provides certificate subject name given by a certificate handlder. It is complete certificate subject name buffer.
 319          *
 320          * @since 2.1
 321          * @return                      An error code.
 322          * @param[in]       certificateHandle   Handle to certificate.
 323          * @param[out]      ppSubjectNameRef    Subject name buffer.
 324          * @param[out]      pSubjectNameLength  Subject name length.
 325          * @exception           E_SUCCESS                       The method is successful.
 326          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 327          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 328          */
 329         static result GetSubjectNameN(CertificateHandle certificateHandle, byte*& ppSubjectNameRef, int* pSubjectNameLength);
 330
 331         /**
 332          *       This function provides certificate issuer name given by a certificate handlder. It is complete certificate issuer name buffer.
 333          *
 334          * @since 2.1
 335          * @return                      An error code.
 336          * @param[in]       certificateHandle       Handle to certificate.
 337          * @param[out]      pIssuerNameRef          Issuer name buffer.
 338          * @param[out]      pIssuerNameLength       Subject name length.
 339          * @exception           E_SUCCESS                               The method is successful.
 340          * @exception           E_INVALID_ARG                   The specified input parameter is invalid.
 341          * @exception           E_SYSTEM                                An unexpected system error has occurred.
 342          */
 343         static result GetIssuerNameN(CertificateHandle certificateHandle, byte*& pIssuerNameRef, int* pIssuerNameLength);
 344
 345         /**
 346          *      This function checks certificates validity.
 347          *
 348          * @since 2.1
 349          * @return                      An error code.
 350          * @param[in]           certHandle          Handle to the certificate.
 351          * @param[out]          pValidity                       Validity of certificate; Valid, Expired or Validity Yet to start.
 352          * @exception           E_SUCCESS                       The method is successful.
 353          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 354          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 355          */
 356         static result CheckCertValidity(CertificateHandle certHandle, _CertValidityType* pValidity);
 357
 358         /**
 359          *      This function checks certificate type.
 360          *
 361          * @since 2.1
 362          * @return                      An error code.
 363          * @param[in]           certHandle          Handle to the certificate.
 364          * @param[out]          pCertType                       Type of certificate.
 365          * @exception           E_SUCCESS                       The method is successful.
 366          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 367          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 368          */
 369         static result CheckCertType(CertificateHandle certHandle, _CaCertType* pCertType);
 370
 371         /**
 372          *       This function breaks certificate chain buffer into individual certificate.
 373          *   It is assumed here that there is no Private Key in the Chain.
 374          *   Chain can contain multiple certificate including Device, Intermediate and CA Certificate.
 375          *   This will return a Structure ppCertChainList containing all the certificates.
 376          *
 377          * @since 2.1
 378          * @return                      An error code.
 379          * @param[in]           pCertChainBuffer                Certificate chain buffer.
 380          * @param[in]           certChainLength                 Certificate chain buffer length.
 381          * @param[out]          ppCertChainListRef              Certificate chain list containing individual certificate.
 382          * @exception           E_SUCCESS                               The method is successful.
 383          * @exception           E_INVALID_ARG                   The specified input parameter is invalid.
 384          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 385          * @exception           E_SYSTEM                                An unexpected system error has occurred.
 386          */
 387         static result MakeCertChainFromBufferN(char* pCertChainBuffer, int certChainLength, _CertRootList*& ppCertChainListRef);
 388
 389         /**
 390          * This function gets the certificate list information by requested format.
 391          *
 392          * @since 2.1
 393          * @return                      An error code.
 394          * @param[in]           certFormat          Format of requested certificates.
 395          * @param[in,out]       pCertList           Pointer to pointer of Certificate list structure.
 396          * @param[out]          count               Number of certificates in the list.
 397          * @exception           E_SUCCESS                       The method is successful.
 398          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 399          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 400          */
 401         static result GetCertListByFormatN(_CertFormat certFormat, _CertificateListInfo*& pCertList, int* count);
 402
 403         /**
 404          *        This function gets the root certificate list information by requested certificate ID
 405          *
 406          * @since 2.1
 407          * @return                      An error code.
 408          * @param[in]           certId              Format of requested device certificates.
 409          * @param[out]          pCertList           Pointer to pointer of Certificate list structure.
 410          * @exception           E_SUCCESS                       The method is successful.
 411          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 412          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 413          */
 414         static result GetCaCertListByCertIdN(int certId, _CertificateListInfo*& pCertList);
 415
 416         /**
 417          *       This function retrieves domain certificate information.
 418          *
 419          * @since 2.1
 420          * @return                      If success this function returns certId installed certificates, -1 in case of failure.
 421          * @param[out]          ppDcInfo                        information about domain certificate.
 422          * @remarks         The specific error code can be accessed using the GetLastResult() method.
 423          */
 424         static int GetDomainCertInfoN(_CertFieldInfos*& prDcInfo);
 425
 426         /**
 427          *       This function retrieves certificate information given by a certificate ID.
 428          *
 429          * @since 2.1
 430          * @return                      An error code.
 431          * @param[in]           certId                          Certificate ID.
 432          * @param[out]          pDcInfo                         Pointer to certificate information structure.
 433          * @exception           E_SUCCESS                       The method is successful.
 434          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 435          * @exception           E_SYSTEM                        An unexpected system error has occurred.
 436          */
 437         static result GetCaCertInfoByCertId(int certId, _CertFieldInfos* pDcInfo);
 438
 439         /**
 440          *        This function gets the user certificate list information by requested format.
 441          *
 442          * @since 2.1
 443          * @return                      An error code.
 444          * @param[in]           certFormat                  Format of requested user certificates.
 445          * @param[out]          pUserCertListInfoTypesRef   Pointer to pointer of Certificate list structure.
 446          * @param[out]          pCount                      Number of certificates in the list.
 447          * @exception           E_SUCCESS                                       The method is successful.
 448          * @exception           E_INVALID_ARG                           The specified input parameter is invalid.
 449          * @exception           E_OUT_OF_MEMORY             The memory is insufficient.
 450          * @exception           E_SYSTEM                                        An unexpected system error has occurred.
 451          */
 452         static result GetUserCertListInfoTypesByFormatN(_CertFormat certFormat, _CertificateListInfo*& pUserCertListInfoTypesRef, int* pCount);
 453
 454         /**
 455          * This function retrieves all user certificate information.
 456          *
 457          * @since 2.1
 458          * @return                      This function returns certId of installed user certificates.
 459          * @param[out]          pCertFieldInfosRef        User certificate information.
 460          * @remarks         The specific error code can be accessed using the GetLastResult() method.
 461          */
 462         static int GetUserCertFieldInfoN(_CertFieldInfos*& pCertFieldInfosRef);
 463
 464         /**
 465          *       This function provides the path of CRT file, which contains all the installed certificate in PEM format.
 466          *
 467          * @since 2.1
 468          * @return                      Path of CRT file containing all certificates in PEM format.
 469          */
 470         static Tizen::Base::String GetCertificateCrtFilePath(void);
 471
 472         /**
 473          *       This function frees the certificate list given by a certificate list.
 474          *
 475          * @since 2.1
 476          * @return                      An error code.
 477          * @param[in]           pCertList           Pointer to certificate link list.
 478          * @exception           E_SUCCESS                       The method is successful.
 479          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 480          */
 481         static result FreeCertList(_CertificateListInfo* pCertList);
 482
 483         /**
 484          *       This function frees the certificate info given by a struct _CertInfo.
 485          *
 486          * @since 2.1
 487          * @return                      An error code.
 488          * @param[in]           pCertInfo           Pointer to certificate info.
 489          * @exception           E_SUCCESS                       The method is successful.
 490          */
 491         static result FreeCertificateInfo(_CertInfo* pCertInfo);
 492
 493         /**
 494          *       This function frees the root certificate list.
 495          *
 496          * @since 2.1
 497          * @return                      An error code.
 498          * @param[in]       pRootCertList       Pointer to root certificate link list.
 499          * @exception           E_SUCCESS           The method is successful.
 500          * @exception           E_INVALID_ARG       The specified input parameter is invalid.
 501          */
 502         static result FreeRootCertList(_CertRootList* pRootCertList);
 503
 504         /**
 505          *      This function closes the opened private key context.
 506          *
 507          * @since 2.1
 508          * @return                      An error code.
 509          * @param[in]           certCtx                         Handle to private key context.
 510          * @exception           E_SUCCESS                       The method is successful.
 511          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 512          */
 513         static result ClosePrivateKeyContext(PrivateKeyCtx privateKeyCtx);
 514
 515 private:
 516         _CertService(void);
 517
 518         _CertService(const _CertService& rhs);
 519
 520         ~_CertService(void);
 521
 522         _CertService& operator =(const _CertService& rhs);
 523
 524 }; //_CertService
 525
 526 } } } //Tizen::Security::Cert
 527
 528 #endif  // _FSEC_CERT_INTERNAL_CERT_SERVICE_H_