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