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 security 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 certificate */
  44         TRUSTED_THIRD_PARTY_DOMAIN,     /**< The trusted third party domain certificate*/
  45         USER_CERT,                      /**< The user certificate */
  46         UNKNOWN_TYPE = 10,              /**< The unknown type certificate*/
  47 }; //CertificateType
  48
  49 /**
  50  * @enum ValidityPeriod
  51  *
  52  * Defines the certificate validity period.
  53  *
  54  * @since               2.0
  55  */
  56 enum ValidityPeriod
  57 {
  58         VALIDITY_PERIOD_VALID,          /**< The certificate is valid */
  59         VALIDITY_PERIOD_EXPIRED,        /**< The certificate has expired */
  60         VALIDITY_PERIOD_NOT_YET_VALID,  /**< The certificate period 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
  70  * certificates, such as X.509 and PGP, share general functionalities, namely encoding and verifying, and information like
  71  * 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 certificate format
 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 certificate type
 198          * @exception   E_SUCCESS               The method is successful.
 199          * @exception   E_SYSTEM                Either of the following conditions has occurred:
 200          *                                                              - A system error has occurred.
 201          *                                                              - The certificate link list operation has failed.
 202          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 203          */
 204         virtual CertificateType GetType(void) const = 0;
 205
 206         /**
 207          * Gets the encoded form of the certificate. @n
 208          * 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.
 209          *
 210          * @since               2.0
 211          *
 212          * @return              A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 213          *                              else @c null if an error occurs
 214          * @exception   E_SUCCESS                       The method is successful.
 215          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 216          * @exception   E_SYSTEM                        Either of the following conditions has occurred:
 217          *                                                                      - A system error has occurred.
 218          *                                                                      - The certificate link list operation has failed.
 219          *                                                                      - The Tizen::Base::ByteBuffer operation has failed.
 220          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 221          */
 222         virtual Tizen::Base::ByteBuffer* GetEncodedDataN(void) const = 0;
 223
 224         /**
 225          * Gets the fingerprint of the certificate. @n
 226          * It is the hash value of the encoding of the certificate.
 227          *
 228          * @since               2.0
 229          *
 230          * @return              A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 231          *                              else @c null if an error occurs
 232          * @exception   E_SUCCESS                       The method is successful.
 233          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 234          * @exception   E_SYSTEM                        Either of the following conditions has occurred:
 235          *                                                                      - A system error has occurred.
 236          *                                                                      - The certificate parsing operation has failed.
 237          *                                                                      - The Tizen::Base::ByteBuffer operation has failed.
 238          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 239          */
 240         virtual Tizen::Base::ByteBuffer* GetFingerprintN(void) const = 0;
 241
 242         /**
 243          *  Verifies whether the certificate is signed using the private key corresponding to the specified public key.
 244          *
 245          *      @since          2.0
 246          *
 247          *      @return         @c true if the certificate is signed using the private key corresponding to the specified public key, @n
 248          *                              else @c false
 249          *      @param[in]      publicKey                       A reference to IPublicKey
 250          *      @exception      E_SUCCESS                       The method is successful.
 251          *      @exception      E_INVALID_ARG           The specified @c publicKey is invalid or empty.
 252          *      @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 253          *      @exception      E_SYSTEM                        Either of the following conditions has occurred:
 254          *                                                                      - A system error has occurred.
 255          *                                                                      - The certificate parsing operation has failed.
 256          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 257          */
 258         virtual bool Verify(const Tizen::Security::IPublicKey& publicKey) = 0;
 259
 260         /**
 261          * Gets the public key of this certificate.
 262          *
 263          * @since               2.0
 264          *
 265          * @return              A pointer to the IPublicKey interface, @n
 266          *                              else @c null if an error occurs
 267          * @exception   E_SUCCESS                       The method is successful.
 268          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 269          * @exception   E_KEY_NOT_FOUND         The key is not found.
 270          * @exception   E_SYSTEM                        Either of the following conditions has occurred:
 271          *                                                      - A system error has occurred.
 272          *                                                      - The Tizen::Base::ByteBuffer operation has failed.
 273          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 274          */
 275         virtual Tizen::Security::IPublicKey* GetPublicKeyN(void) const = 0;
 276
 277         /**
 278          * Gets the serial number of the certificate. @n
 279          * The serial number is a unique integer assigned by the Certification Authority (CA) to each certificate (that is, the issuer name and serial number
 280          * must identify a unique certificate). @n
 281          *
 282          * This is defined in ASN.1 as demonstrated in the following code:
 283          *
 284          *      @code
 285          *      serialNumber             CertificateSerialNumber.
 286          *
 287          *      CertificateSerialNumber  ::=  INTEGER
 288          *  @endcode
 289          *
 290          * Since the serial number can be greater than the system's maximum defined value for @c int, the output parameter type
 291          * is @c ByteBuffer, instead of @c int.
 292          *
 293          * @since               2.0
 294          *
 295          * @return              The serial number of the certificate
 296          * @exception   E_SUCCESS                       The method is successful.
 297          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 298          * @exception   E_SYSTEM                        Either of the following conditions has occurred:
 299          *                                                      - A system error has occurred.
 300          *                                                      - The method has failed to get the certificate serial number information.
 301          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 302          */
 303         virtual Tizen::Base::String GetSerialNumber(void) const = 0;
 304
 305         /**
 306          * Checks whether the certificate is currently valid. @n
 307          * It is valid if the current date and time are within the validity period of the certificate. The validity period consists
 308          * of two date and time values: the initial date and time, and the final date and time for the validity of the certificate. @n
 309          *
 310          * This is defined in ASN.1 as demonstrated in the following code:
 311          *
 312          * @code
 313          * validity             Validity
 314          *
 315          *      Validity ::= SEQUENCE {
 316          *              notBefore      CertificateValidityDate,
 317          *              notAfter       CertificateValidityDate }
 318          *
 319          *      CertificateValidityDate ::= CHOICE {
 320          *              utcTime        UTCTime,
 321          *              generalTime    GeneralizedTime }
 322          *  @endcode
 323          *
 324          * @since               2.0
 325          *
 326          * @return              The validity period of the certificate
 327          * @exception   E_SUCCESS                       The method is successful.
 328          * @exception   E_SYSTEM                        Either of the following conditions has occurred:
 329          *                                                                      - A system error has occurred.
 330          *                                                                      - The certificate link list operation has failed.
 331          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 332          */
 333         virtual ValidityPeriod CheckValidityPeriod(void) = 0;
 334
 335
 336         /**
 337          * Gets the notBefore value of Tizen::Base::String type from the validity period of the certificate. @n
 338          * This value represents the date and time before which the certificate is not valid.
 339          *
 340          * @since               2.0
 341          *
 342          * @return              A string representing the date and time value before which the certificate is not valid
 343          * @exception   E_SUCCESS                       The method is successful.
 344          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 345          * @exception   E_SYSTEM                        Either of the following conditions has occurred:
 346          *                                                                      - A system error has occurred.
 347          *                                                                      - The method has failed to get the certificate validity information.
 348          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 349          * @see                 Tizen::Security::Cert::X509Certificate::CheckValidityPeriod() for relevant ASN.1 definitions
 350          */
 351         virtual Tizen::Base::String GetNotBefore(void) const = 0;
 352
 353
 354         /**
 355          * Gets the notAfter value of Tizen::Base::String type from the validity period of the certificate. @n
 356          * This value represents the date and time after which the certificate is not valid.
 357          *
 358          * @since               2.0
 359          *
 360          * @return              A string representing the date and time value after which the certificate is not valid
 361          * @exception   E_SUCCESS                       The method is successful.
 362          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 363          * @exception   E_SYSTEM                        Either of the following conditions has occurred:
 364          *                                                                      - A system error has occurred.
 365          *                                                                      - The method has failed to get the certificate validity information.
 366          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 367          * @see                 Tizen::Security::Cert::X509Certificate::CheckValidityPeriod() for relevant ASN.1 definitions
 368          */
 369         virtual Tizen::Base::String GetNotAfter(void) const = 0;
 370
 371         /**
 372          * Gets the name of the issuer of the certificate.
 373          *
 374          * @since               2.0
 375          *
 376          * @return              The name of the issuer of the certificate
 377          * @exception   E_SUCCESS                       The method is successful.
 378          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 379          * @exception   E_SYSTEM                        Either of the following conditions has occurred:
 380          *                                                                      - A system error has occurred.
 381          *                                                                      - The method has failed to get the certificate issuer information.
 382          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 383          */
 384         virtual Tizen::Base::String GetIssuer(void) const = 0;
 385
 386         /**
 387          * Gets the subject name of the certificate.
 388          *
 389          * @since               2.0
 390          *
 391          * @return              The subject name of the certificate
 392          * @exception   E_SUCCESS                       The method is successful.
 393          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 394          * @exception   E_SYSTEM                        Either of the following conditions has occurred:
 395          *                                                                      - A system error has occurred.
 396          *                                                                      - The method has failed to get the certificate issuer information.
 397          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 398          */
 399         virtual Tizen::Base::String GetSubject(void) const = 0;
 400
 401         /**
 402          * Gets the signature of the certificate.
 403          *
 404          * @since               2.0
 405          *
 406          * @return              A pointer to the Tizen::Base::ByteBuffer class that contains the output, @n
 407          *                              else @c null if an error occurs
 408          * @exception   E_SUCCESS                       The method is successful.
 409          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 410          * @exception   E_SYSTEM                        Either of the following conditions has occurred:
 411          *                                                                      - A system error has occurred.
 412          *                                                                      - The certificate link list operation has failed.
 413          *                                                                      - The Tizen::Base::ByteBuffer operation has failed.
 414          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 415          */
 416         virtual Tizen::Base::ByteBuffer* GetSignatureN(void) const = 0;
 417
 418 protected:
 419         //
 420         // This method is for internal use only. Using this method can cause behavioral, security-related,
 421         // and consistency-related issues in the application.
 422         //
 423         // This method is reserved and may change its name at any time without prior notice.
 424         //
 425         // @since 2.0
 426         //
 427         virtual void ICertificate_Reserved1(void) {}
 428
 429         //
 430         // This method is for internal use only. Using this method can cause behavioral, security-related,
 431         // and consistency-related issues in the application.
 432         //
 433         // This method is reserved and may change its name at any time without prior notice.
 434         //
 435         // @since 2.0
 436         //
 437         virtual void ICertificate_Reserved2(void) {}
 438
 439         //
 440         // This method is for internal use only. Using this method can cause behavioral, security-related,
 441         // and consistency-related issues in the application.
 442         //
 443         // This method is reserved and may change its name at any time without prior notice.
 444         //
 445         // @since 2.0
 446         //
 447         virtual void ICertificate_Reserved3(void) {}
 448
 449 }; //ICertificate
 450
 451 } } } //Tizen::Security::Cert
 452
 453 #endif //_FSEC_CERT_ICERTIFICATE_H_