src/security/inc/FSecCert_CertService.h

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