inc/FSecCertICertificatePath.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                FSecCertICertificatePath.h
  19  * @brief               This is the header file for the %ICertificatePath interface.
  20  *
  21  * This header file contains the declarations of the %ICertificatePath interface.
  22  */
  23 #ifndef _FSEC_CERT_ICERTIFICATE_PATH_H_
  24 #define _FSEC_CERT_ICERTIFICATE_PATH_H_
  25
  26 #include <FBaseString.h>
  27 #include <FSecCertICertificate.h>
  28 #include <FSecCertTypes.h>
  29
  30 namespace Tizen { namespace Security { namespace Cert
  31 {
  32
  33 class ICertificatePathValidationResult;
  34 /**
  35  *  @interface  ICertificatePath
  36  *  @brief              This interface provides methods for validating the certificate path and get information about it.
  37  *
  38  *  @since                      2.0
  39  *
  40  * The %ICertificatePath interface provides methods for validating the certificate path and get information about it. @n
  41  *
  42  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/security/certificate_namespace.htm">Certificates</a>. @n
  43  *
  44  *  The following example demonstrates how to use the %ICertificatePath interface.
  45  *
  46  *  @code
  47  *
  48  *  void
  49  *  MyCertificatePath::Sample(void)
  50  *  {
  51  *              X509Certificate *pCertificate1  = null;
  52  *              X509Certificate *pCertificate2  = null;
  53  *
  54  *              ICertificate    *pTrustCa = null;
  55  *              ByteBuffer              input1, input2;
  56  *              int             depth = 0;
  57  *              ValidationResult valResult;
  58  *              result                  r = E_FAILURE;
  59  *
  60  *              ICertificatePath        *pCertPath      = null;
  61  *
  62  *              String fileName1(Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/UTsSecurity/Security/Domain3Certs/TestCert1-1.der");
  63  *              String fileName2(Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/UTsSecurity/Security/Domain3Certs/TestCert1-2.der");
  64  *              File                    file1, file2;
  65  *              FileAttributes  attribute1, attribute2;
  66  *
  67  *              r = file1.Construct(fileName1, L"r");
  68  *              if (IsFailed(r))
  69  *              {
  70  *                      goto CATCH;
  71  *              }
  72  *
  73  *              r = file1.GetAttributes(fileName1, attribute1);
  74  *              if (IsFailed(r))
  75  *              {
  76  *                      goto CATCH;
  77  *              }
  78  *
  79  *              r = input1.Construct((int)attribute1.GetFileSize());
  80  *              if (IsFailed(r))
  81  *              {
  82  *                      goto CATCH;
  83  *              }
  84  *
  85  *              r = file1.Read(input1);
  86  *              if (IsFailed(r))
  87  *              {
  88  *                      goto CATCH;
  89  *              }
  90  *
  91  *              input1.Flip();
  92  *
  93  *              r = file2.Construct(fileName2, L"r");
  94  *              if (IsFailed(r))
  95  *              {
  96  *                      goto CATCH;
  97  *              }
  98  *
  99  *              r = file2.GetAttributes(fileName2, attribute2);
 100  *              if (IsFailed(r))
 101  *              {
 102  *                      goto CATCH;
 103  *              }
 104  *
 105  *              r = input2.Construct((int)attribute2.GetFileSize());
 106  *              if (IsFailed(r))
 107  *              {
 108  *                      goto CATCH;
 109  *              }
 110  *
 111  *              r = file2.Read(input2);
 112  *              if (IsFailed(r))
 113  *              {
 114  *                      goto CATCH;
 115  *              }
 116  *
 117  *              input2.Flip();
 118  *
 119  *              // Certificate1
 120  *              pCertificate1 = new X509Certificate;
 121  *              pCertificate1->Construct(input1);
 122  *
 123  *              // Certificate2
 124  *              pCertificate2 = new X509Certificate;
 125  *              pCertificate2->Construct(input2);
 126  *
 127  *              // Certificate Path
 128  *              pCertPath        = new X509CertificatePath();
 129  *              if (pCertPath == null)
 130  *              {
 131  *                      goto CATCH;
 132  *              }
 133  *
 134  *              r = pCertPath->AddCertificate(*pCertificate1);
 135  *              if (IsFailed(r))
 136  *              {
 137  *                      goto CATCH;
 138  *              }
 139  *
 140  *              r = pCertPath->AddCertificate(*pCertificate2);
 141  *              if (IsFailed(r))
 142  *              {
 143  *                      goto CATCH;
 144  *              }
 145  *
 146  *
 147  *              // Certificate Path Validation Result
 148  *              valResult = pCertPath->Validate();
 149  *              if (valResult != VALIDATION_SUCCESS)
 150  *              {
 151  *                      goto CATCH;
 152  *              }
 153  *
 154  *              depth = pCertPath->GetLength();
 155  *              if (depth == 0)
 156  *              {
 157  *                      goto CATCH;
 158  *              }
 159  *
 160  *              for (int i = 0; i < depth; i++)
 161  *              {
 162  *                      ICertificate *pOutCert = pCertPath->GetCertificateN(i);
 163  *
 164  *                      if (pOutCert)
 165  *                      {
 166  *                              String subjectName;
 167  *                              subjectName = pOutCert->GetSubject();
 168  *                      }
 169  *
 170  *                      delete pOutCert;
 171  *              }
 172  *
 173  *              pTrustCa = pCertPath->GetTrustAnchorN();
 174  *              if (pTrustCa)
 175  *              {
 176  *                      String subjectName;
 177  *                      subjectName = pTrustCa->GetSubject();
 178  *              }
 179  *
 180  *              delete pTrustCa;
 181  *
 182  *              r = E_SUCCESS;
 183  *
 184  *      CATCH:
 185  *              delete pCertificate1;
 186  *              delete pCertificate2;
 187  *              delete pCertPath;
 188  *      }
 189  *
 190  *  @endcode
 191  *
 192  */
 193
 194 class _OSP_EXPORT_ ICertificatePath
 195 {
 196
 197 public:
 198         /**
 199          *      This is the destructor for this class.
 200          *
 201          *      @since          2.0
 202          */
 203         virtual ~ICertificatePath(void) {}
 204
 205         /**
 206          *  Gets the format of the certificate path.
 207          *
 208          *      @since          2.0
 209          *
 210          *      @return         The format of the certificate
 211          */
 212         virtual Tizen::Base::String GetFormat(void) const = 0;
 213
 214         /**
 215          *  Adds the specified certificate to the certificate chain.
 216          *  The order of certificates should be as follows: @n
 217          *  1. User certificate.
 218          *  2. Intermediate certificate.
 219          *  3. Root CA certificate.
 220          *
 221          *      @since          2.0
 222          *
 223          *      @return         An error code
 224          *      @param[in]      certificate                     A reference to the certificate to add
 225          *      @exception      E_SUCCESS                       The method is successful.
 226          *      @exception      E_INVALID_ARG           The specified @c certificate or the certificate data is invalid.
 227          *      @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 228          *      @exception      E_SYSTEM                        Either of the following conditions has occurred:
 229          *                                                                      - A system error has occurred.
 230          *                                                                      - The certificate link list operation has failed.
 231          */
 232         virtual result AddCertificate(const Tizen::Security::Cert::ICertificate& certificate) = 0;
 233
 234         /**
 235          *  Validates the specified certificate path.
 236          *
 237          *      @since          2.0
 238          *
 239          *      @return         The result of the certificate path validation
 240          *      @exception      E_SUCCESS                               The method is successful.
 241          *      @exception      E_SYSTEM                                Either of the following conditions has occurred:
 242          *                                                                              - A system error has occurred.
 243          *                                                                              - The certificate link list operation has failed.
 244          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 245          */
 246         virtual Tizen::Security::Cert::ValidationResult Validate(void) = 0;
 247
 248         /**
 249          *  Validates the specified certificate path.
 250          *
 251          *      @since          2.0
 252          *
 253          *      @return         The result of the certificate path validation
 254          *      @param[in]      trustAnchor                     The trusted Certificate Authority (CA)
 255          *      @exception      E_SUCCESS                       The method is successful.
 256          *      @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 257          *      @exception      E_INVALID_ARG           The specified input parameter is invalid.
 258          *      @exception      E_SYSTEM                        Either of the following conditions has occurred:
 259          *                                                                      - A system error has occurred.
 260          *                                                                      - The certificate link list operation has failed.
 261          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 262          */
 263         virtual Tizen::Security::Cert::ValidationResult Validate(const Tizen::Security::Cert::ICertificate& trustAnchor) = 0;
 264
 265         /**
 266          *      Gets the trust anchor for the certificate path.
 267          *
 268          *      @since          2.0
 269          *
 270          *      @return         The root certificate, @n
 271          *                              else @c null if an error occurs
 272          *      @exception      E_SUCCESS                       The method is successful.
 273          *      @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 274          *      @exception      E_OBJ_NOT_FOUND         The certificate is not found.
 275          *      @exception      E_SYSTEM                        A system error has occurred. @n
 276          *                                                                      Either of the following conditions has occurred:
 277          *                                                                      - The certificate link list operation.
 278          *                                                                      - The Tizen::Base::ByteBuffer operation has failed.
 279          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 280          */
 281         virtual Tizen::Security::Cert::ICertificate* GetTrustAnchorN(void) const = 0;
 282
 283         /**
 284          *  Gets the length of the certificate path.
 285          *
 286          *      @since          2.0
 287          *
 288          *      @return         The length of the certificate path, @n
 289          *                              else @c -1 if an error occurs
 290          *      @exception      E_SUCCESS                       The method is successful.
 291          *      @exception      E_SYSTEM                        Either of the following conditions has occurred:
 292          *                                                                      - A system error has occurred.
 293          *                                                                      - The certificate list is empty.
 294          */
 295         virtual int GetLength(void) const = 0;
 296
 297         /**
 298          *      Gets the list of certificates in this certificate path.
 299          *
 300          *      @since          2.0
 301          *
 302          *      @return         A pointer to the ICertificate interface, @n
 303          *                              else @c null if an error occurs
 304          *      @param[in]      nth                                     The nth certificate in the certificate path (starts from @c 0)
 305          *      @exception      E_SUCCESS                       The method is successful.
 306          *      @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 307          *      @exception      E_INVALID_ARG           The value of the specified @c nth is out of the valid range. @n
 308          *                                                                      It must be less than the value retrieved by the GetLength() method.
 309          *      @exception      E_OBJ_NOT_FOUND         The certificate is not found.
 310          *      @exception      E_SYSTEM                        Either of the following conditions has occurred:
 311          *                                                                      - A system error has occurred.
 312          *                                                                      - The certificate list is empty.
 313          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 314          */
 315         virtual Tizen::Security::Cert::ICertificate* GetCertificateN(int nth) const = 0;
 316
 317 protected:
 318         //
 319         // This method is for internal use only. Using this method can cause behavioral, security-related,
 320         // and consistency-related issues in the application.
 321         //
 322         // This method is reserved and may change its name at any time without prior notice.
 323         //
 324         // @since 2.0
 325         //
 326         virtual void ICertificatePath_Reserved1(void) {}
 327
 328         //
 329         // This method is for internal use only. Using this method can cause behavioral, security-related,
 330         // and consistency-related issues in the application.
 331         //
 332         // This method is reserved and may change its name at any time without prior notice.
 333         //
 334         // @since 2.0
 335         //
 336         virtual void ICertificatePath_Reserved2(void) {}
 337
 338         //
 339         // This method is for internal use only. Using this method can cause behavioral, security-related,
 340         // and consistency-related issues in the application.
 341         //
 342         // This method is reserved and may change its name at any time without prior notice.
 343         //
 344         // @since 2.0
 345         //
 346         virtual void ICertificatePath_Reserved3(void) {}
 347
 348 }; //ICertificatePath
 349
 350 } } } //Tizen::Security::Cert
 351
 352 #endif //_FSEC_CERT_ICERTIFICATE_PATH_H_