inc/FSecCertICertificate.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                FSecCertICertificate.h
  20  * @brief               This is the header file for the %ICertificate interface.
  21  *
  22  * This header file contains the declarations of the %ICertificate interface.
  23  */
  24 #ifndef _FSEC_CERT_ICERTIFICATE_H_
  25 #define _FSEC_CERT_ICERTIFICATE_H_
  26
  27 #include <FBaseString.h>
  28 #include <FBaseByteBuffer.h>
  29 #include <FSecIPublicKey.h>
  30
  31 namespace Tizen { namespace Security { namespace Cert
  32 {
  33
  34 /**
  35  * @enum CertificateType
  36  *
  37  * Defines the type of certificate.
  38  *
  39  * @since               2.0
  40  */
  41 enum CertificateType
  42 {
  43         ROOT_CA,                        /**< The Factory-supplied certificates for SSL: ROOT CA */
  44         OPERATOR_DOMAIN,                /**< The Operator Domain */
  45         TRUSTED_THIRD_PARTY_DOMAIN,     /**< The Trusted Third Party Domain */
  46         USER_CERT,                      /**< The User Certificates */
  47         UNKNOWN_TYPE = 10,              /**< The unknown type */
  48 }; //CertificateType
  49
  50 /**
  51  * @enum ValidityPeriod
  52  *
  53  * Defines the validity period.
  54  *
  55  * @since               2.0
  56  */
  57 enum ValidityPeriod
  58 {
  59         VALIDITY_PERIOD_VALID,          /**< The validity period */
  60         VALIDITY_PERIOD_EXPIRED,        /**< The expiry period */
  61         VALIDITY_PERIOD_NOT_YET_VALID,  /**< The period that is not yet valid */
  62 }; //ValidityPeriod
  63
  64 /**
  65  * @interface   ICertificate
  66  * @brief               This interface manages a variety of identity certificates.
  67  *
  68  * @since               2.0
  69  *
  70  * The %ICertificate interface is an abstraction for certificates having different formats. For example, different types of certificates, such as X.509 and PGP, share
  71  * general functionalities, namely encoding and verifying, and some type of information like public keys. Despite containing different sets of information and having different ways for storing, and retrieving them,
  72  * the X.509, X.968, and WTLS certificates can all be implemented by using the %ICertificate interface.
  73  *
  74  * An identity certificate is a binding of a principal to a public key, which is vouched for by another principal.
  75  * A principal represents an entity, such as an individual user, a group, or a corporation. @n
  76  *
  77  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/security/certificate_namespace.htm">Certificates</a>.
  78  *
  79  * The following example demonstrates how to use the %ICertificate interface.
  80  *
  81  *
  82  *  @code
  83  *
  84  *  void
  85  *  MyCertificate::Sample(void)
  86  *  {
  87  *              X509Certificate *pCertificate   = null;
  88  *              String                  serialNumber;
  89  *              String                  algorithm;
  90  *              String                  start;
  91  *              String                  end;
  92  *              String                  subjectName;
  93  *              String                  issuerName;
  94  *              ByteBuffer              *pSignature = null;
  95  *              ByteBuffer              *pFingerprint = null;
  96  *              ByteBuffer              input;
  97  *              result                  r = E_FAILURE;
  98  *
  99  *              String fileName(Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/UTsSecurity/Security/Domain3Certs/TestCert1-1.der");
 100  *              File                    file;
 101  *              FileAttributes  attribute;
 102  *
 103  *              r = file.Construct(fileName, L"r");
 104  *              if (IsFailed(r))
 105  *              {
 106  *                      goto CATCH;
 107  *              }
 108  *
 109  *              r = file.GetAttributes(fileName, attribute);
 110  *              if (IsFailed(r))
 111  *              {
 112  *                      goto CATCH;
 113  *              }
 114  *
 115  *              r = input.Construct((int)attribute.GetFileSize());
 116  *              if (IsFailed(r))
 117  *              {
 118  *                      goto CATCH;
 119  *              }
 120  *
 121  *              r = file.Read(input);
 122  *              if (IsFailed(r))
 123  *              {
 124  *                      goto CATCH;
 125  *              }
 126  *
 127  *              input.Flip();
 128  *
 129  *              pCertificate    = new X509Certificate;
 130  *              pCertificate->Construct(input);
 131  *
 132  *              serialNumber    = pCertificate->GetSerialNumber();
 133  *              algorithm               = pCertificate->GetSignatureAlgorithm();
 134  *              start                   = pCertificate->GetNotBefore();
 135  *              end                             = pCertificate->GetNotAfter();
 136  *              subjectName             = pCertificate->GetSubject();
 137  *              issuerName              = pCertificate->GetIssuer();
 138  *
 139  *              pSignature = pCertificate->GetSignatureN();
 140  *              if (pSignature == null)
 141  *              {
 142  *                      goto CATCH;
 143  *              }
 144  *
 145  *              pFingerprint = pCertificate->GetFingerprintN();
 146  *              if (pFingerprint == null)
 147  *              {
 148  *                      goto CATCH;
 149  *              }
 150  *
 151  *              r = E_SUCCESS;
 152  *
 153  *      CATCH:
 154  *              if (pCertificate)
 155  *              {
 156  *                      delete pCertificate;
 157  *              }
 158  *              if (pSignature)
 159  *              {
 160  *                      delete pSignature;
 161  *              }
 162  *              if (pFingerprint)
 163  *              {
 164  *                      delete pFingerprint;
 165  *              }
 166  *      }
 167  *
 168  *  @endcode
 169  *
 170  */
 171
 172 class _OSP_EXPORT_ ICertificate
 173 {
 174
 175 public:
 176         /**
 177          * This is the destructor for this class.
 178          *
 179          * @since               2.0
 180          */
 181         virtual ~ICertificate(void) {}
 182
 183         /**
 184          * Gets the format name for this certificate.
 185          *
 186          * @since               2.0
 187          *
 188          * @return              The format of this certificate
 189          */
 190         virtual Tizen::Base::String GetFormat(void) const = 0;
 191
 192         /**
 193          * Gets the certificate type.
 194          *
 195          * @since               2.0
 196          *
 197          * @return              The type of this certificate
 198          * @exception   E_SUCCESS               The method is successful.
 199          * @exception   E_SYSTEM                A system error has occurred. @n
 200          *                              The certificate link list operation has failed.
 201          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 202          */
 203         virtual CertificateType GetType(void) const = 0;
 204
 205         /**
 206          * Gets the encoded form of the certificate. @n
 207          * It is assumed that each certificate type has a single form of encoding. For example, X.509 certificates can be encoded as ASN.1 DER.
 208          *
 209          * @since               2.0
 210          *
 211          * @return              A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 212          *                              else @c null if an error occurs
 213          * @exception   E_SUCCESS                       The method is successful.
 214          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 215          * @exception   E_SYSTEM                        A system error has occurred. @n
 216          *                                  The certificate link list operation or the
 217          *                                  Tizen::Base::ByteBuffer operation has failed.
 218          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 219          */
 220         virtual Tizen::Base::ByteBuffer* GetEncodedDataN(void) const = 0;
 221
 222         /**
 223          * Gets the fingerprint of the certificate. @n
 224          * It is the hashed value of the encoding of the certificate.
 225          *
 226          * @since               2.0
 227          *
 228          * @return              A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 229          *                              else @c null if an error occurs
 230          * @exception   E_SUCCESS                       The method is successful.
 231          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 232          * @exception   E_SYSTEM                        A system error has occurred. @n
 233          *                                                                      The certificate parsing operation or
 234          *                                                                      the Tizen::Base::ByteBuffer operation has failed.
 235          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 236          */
 237         virtual Tizen::Base::ByteBuffer* GetFingerprintN(void) const = 0;
 238
 239         /**
 240          *  Verifies whether the certificate is signed using the private key corresponding to the specified public key.
 241          *
 242          *      @since          2.0
 243          *
 244          *      @return         @c true if the certificate is signed using the private key corresponding to the specified public key, @n
 245          *                              else @c false
 246          *      @param[in]      publicKey                       A reference to IPublicKey
 247          *      @exception      E_SUCCESS                       The method is successful.
 248          *      @exception      E_INVALID_ARG           The specified @c publicKey is invalid or empty.
 249          *      @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 250          *      @exception      E_SYSTEM                        A system error has occurred. @n
 251          *                                                                      The certificate parsing operation has failed.
 252          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 253          */
 254         virtual bool Verify(const Tizen::Security::IPublicKey& publicKey) = 0;
 255
 256         /**
 257          * Gets the public key of this certificate.
 258          *
 259          * @since               2.0
 260          *
 261          * @return              A pointer to the IPublicKey interface, @n
 262          *                              else @c null if an error occurs
 263          * @exception   E_SUCCESS                       The method is successful.
 264          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 265          * @exception   E_KEY_NOT_FOUND         The key is not found.
 266          * @exception   E_SYSTEM                        A system error has occurred. @n
 267          *                                                                      The Tizen::Base::ByteBuffer operation has failed.
 268          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 269          */
 270         virtual Tizen::Security::IPublicKey* GetPublicKeyN(void) const = 0;
 271
 272         /**
 273          * Gets the @c serialNumber value from the certificate. @n
 274          * The serial number is an integer assigned by the Certification Authority (CA) to each certificate. It is unique for each certificate issued by a
 275          * given CA (that is, the issuer name and serial number must identify a unique certificate). @n
 276          *
 277          * This is defined in ASN.1 as demonstrated in the following code:
 278          *
 279          *      @code
 280          *      serialNumber             CertificateSerialNumber.
 281          *
 282          *      CertificateSerialNumber  ::=  INTEGER
 283          *  @endcode
 284          *
 285          * Since the serial number can be greater than the system's maximum value for @c int, the output parameter type is @c ByteBuffer, instead of @c int.
 286          *
 287          * @since               2.0
 288          *
 289          * @return              The serial number of the certificate
 290          * @exception   E_SUCCESS                       The method is successful.
 291          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 292          * @exception   E_SYSTEM                        A system error has occurred. @n
 293          *                                  The method has failed to get the certificate serial number information.
 294          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 295          */
 296         virtual Tizen::Base::String GetSerialNumber(void) const = 0;
 297
 298         /**
 299          * Checks whether the certificate is currently valid. @n
 300          * It is valid if the current date and time are within the validity period given in the certificate. @n
 301          * The validity period consists of two date and time values: the initial date and time, and the final date and time until the validity of the certificate. @n
 302          *
 303          * This is defined in ASN.1 as demonstrated in the following code:
 304          *
 305          * @code
 306          * validity             Validity
 307          *
 308          *      Validity ::= SEQUENCE {
 309          *              notBefore      CertificateValidityDate,
 310          *              notAfter       CertificateValidityDate }
 311          *
 312          *      CertificateValidityDate ::= CHOICE {
 313          *              utcTime        UTCTime,
 314          *              generalTime    GeneralizedTime }
 315          *  @endcode
 316          *
 317          * @since                       2.0
 318          *
 319          * @return              The validity period of the certificate
 320          * @exception   E_SUCCESS                       The method is successful.
 321          * @exception   E_SYSTEM                        A system error has occurred. @n
 322          *                                                                      The certificate link list operation has failed.
 323          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 324          */
 325         virtual ValidityPeriod CheckValidityPeriod(void) = 0;
 326
 327
 328         /**
 329          * Gets the notBefore value of Tizen::Base::String type from the validity period of the certificate. @n
 330          *      This value represents the date and time before which the certificate is not valid.
 331          *
 332          * @since               2.0
 333          *
 334          * @return              A string representing the date and time value before which the certificate is not valid
 335          * @exception   E_SUCCESS                       The method is successful.
 336          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 337          * @exception   E_SYSTEM                        A system error has occurred. @n
 338          *                                                                      The method has failed to get the certificate validity information.
 339          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 340          * @see                 Tizen::Security::Cert::X509Certificate::CheckValidityPeriod() for relevant ASN.1 definitions
 341          */
 342         virtual Tizen::Base::String GetNotBefore(void) const = 0;
 343
 344
 345         /**
 346          * Gets the notAfter value of Tizen::Base::String type from the validity period of the certificate. @n
 347          *      This value represents the date and time after which the certificate is not valid.
 348          *
 349          * @since               2.0
 350          *
 351          * @return              A string representing the date and time value after which the certificate is not valid
 352          * @exception   E_SUCCESS                       The method is successful.
 353          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 354          * @exception   E_SYSTEM                        A system error has occurred. @n
 355          *                                                                      The method has failed to get the certificate validity information.
 356          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 357          * @see                 Tizen::Security::Cert::X509Certificate::CheckValidityPeriod() for relevant ASN.1 definitions
 358          */
 359         virtual Tizen::Base::String GetNotAfter(void) const = 0;
 360
 361         /**
 362          * Gets the name of the issuer of the certificate.
 363          *
 364          * @since               2.0
 365          *
 366          * @return              The name of the issuer of the certificate
 367          * @exception   E_SUCCESS                       The method is successful.
 368          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 369          * @exception   E_SYSTEM                        A system error has occurred. @n
 370          *                                  The method has failed to get the certificate issuer information.
 371          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 372          */
 373         virtual Tizen::Base::String GetIssuer(void) const = 0;
 374
 375         /**
 376          * Gets the subject name of the certificate.
 377          *
 378          * @since               2.0
 379          *
 380          * @return              The subject name of the certificate
 381          * @exception   E_SUCCESS                       The method is successful.
 382          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 383          * @exception   E_SYSTEM                        A system error has occurred. @n
 384          *                                                                      The method has failed to get the certificate issuer information.
 385          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 386          */
 387         virtual Tizen::Base::String GetSubject(void) const = 0;
 388
 389         /**
 390          * Gets the signature of the certificate.
 391          *
 392          * @since               2.0
 393          *
 394          * @return              A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 395          *                              else @c null if an error occurs
 396          * @exception   E_SUCCESS                       The method is successful.
 397          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 398          * @exception   E_SYSTEM                        A system error has occurred. @n
 399          *                                                                      The certificate link list operation or
 400          *                                                                      the Tizen::Base::ByteBuffer operation has failed.
 401          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 402          */
 403         virtual Tizen::Base::ByteBuffer* GetSignatureN(void) const = 0;
 404
 405 protected:
 406         //
 407         // This method is for internal use only. Using this method can cause behavioral, security-related,
 408         // and consistency-related issues in the application.
 409         //
 410         // This method is reserved and may change its name at any time without prior notice.
 411         //
 412         // @since 2.0
 413         //
 414         virtual void ICertificate_Reserved1(void) {}
 415
 416         //
 417         // This method is for internal use only. Using this method can cause behavioral, security-related,
 418         // and consistency-related issues in the application.
 419         //
 420         // This method is reserved and may change its name at any time without prior notice.
 421         //
 422         // @since 2.0
 423         //
 424         virtual void ICertificate_Reserved2(void) {}
 425
 426         //
 427         // This method is for internal use only. Using this method can cause behavioral, security-related,
 428         // and consistency-related issues in the application.
 429         //
 430         // This method is reserved and may change its name at any time without prior notice.
 431         //
 432         // @since 2.0
 433         //
 434         virtual void ICertificate_Reserved3(void) {}
 435
 436 }; //ICertificate
 437
 438 } } } //Tizen::Security::Cert
 439
 440 #endif //_FSEC_CERT_ICERTIFICATE_H_