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 validates the certificate path and gets more information about it.
  37  *
  38  *  @since                      2.0
  39  *
  40  * The %ICertificatePath interface validates the certificate path and gets more 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 a 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 a certificate
 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                        A system error has occurred. @n
 229          *                                                                      The certificate link list operation has failed.
 230          */
 231         virtual result AddCertificate(const Tizen::Security::Cert::ICertificate& certificate) = 0;
 232
 233         /**
 234          *  Validates the specified certificate path.
 235          *
 236          *      @since                  2.0
 237          *
 238          *      @return                 The result of the certificate path validation
 239          *      @exception      E_SUCCESS                               The method is successful.
 240          *      @exception      E_SYSTEM                                A system error has occurred. @n
 241          *                                                                              The certificate link list operation has failed.
 242          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 243          */
 244         virtual Tizen::Security::Cert::ValidationResult Validate(void) = 0;
 245
 246         /**
 247          *  Validates the specified certificate path.
 248          *
 249          *      @since          2.0
 250          *
 251          *      @return         The result of the certificate path validation
 252          *      @param[in]      trustAnchor                     The most trusted Certificate Authority (CA)
 253          *      @exception      E_SUCCESS                       The method is successful.
 254          *      @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 255          *      @exception      E_INVALID_ARG           The specified input parameter is invalid.
 256          *      @exception      E_SYSTEM                        A system error has occurred. @n
 257          *                                                                      The certificate link list operation has failed.
 258          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 259          */
 260         virtual Tizen::Security::Cert::ValidationResult Validate(const Tizen::Security::Cert::ICertificate& trustAnchor) = 0;
 261
 262         /**
 263          *      Gets the trust anchor for the certificate path.
 264          *
 265          *      @since                  2.0
 266          *
 267          *      @return         The root certificate, @n
 268          *                              else @c null if an error occurs
 269          *      @exception      E_SUCCESS                       The method is successful.
 270          *      @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 271          *      @exception      E_OBJ_NOT_FOUND         The certificate is not found.
 272          *      @exception      E_SYSTEM                        A system error has occurred. @n
 273          *                                                                      The certificate link list operation or
 274          *                                                                      the Tizen::Base::ByteBuffer operation has failed.
 275          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 276          */
 277         virtual Tizen::Security::Cert::ICertificate* GetTrustAnchorN(void) const = 0;
 278
 279         /**
 280          *  Gets the length of the certificate path.
 281          *
 282          *      @since          2.0
 283          *
 284          *      @return         The length of the certificate path, @n
 285          *                              else @c -1 if an error occurs
 286          *      @exception      E_SUCCESS                       The method is successful.
 287          *      @exception      E_SYSTEM                        A system error has occurred. @n
 288          *                                                                      The certificate list is empty.
 289          */
 290         virtual int GetLength(void) const = 0;
 291
 292         /**
 293          *      Gets the list of certificates in this certificate path.
 294          *
 295          *      @since                  2.0
 296          *
 297          *      @return         A pointer to the ICertificate interface, @n
 298          *                              else @c null if an error occurs
 299          *      @param[in]      nth                                     The nth certificate in the certificate path (starts from @c 0)
 300          *      @exception      E_SUCCESS                       The method is successful.
 301          *      @exception      E_OUT_OF_MEMORY         The memory is insufficient.
 302          *      @exception      E_INVALID_ARG           The value of the specified @c nth is out of the valid range. @n
 303          *                                                                      It must be less than the value retrieved by the GetLength() method.
 304          *      @exception      E_OBJ_NOT_FOUND         The certificate is not found.
 305          *      @exception      E_SYSTEM                        A system error has occurred. @n
 306          *                                                                      The certificate list is empty.
 307          * @remarks        The specific error code can be accessed using the GetLastResult() method.
 308          */
 309         virtual Tizen::Security::Cert::ICertificate* GetCertificateN(int nth) const = 0;
 310
 311 protected:
 312         //
 313         // This method is for internal use only. Using this method can cause behavioral, security-related,
 314         // and consistency-related issues in the application.
 315         //
 316         // This method is reserved and may change its name at any time without prior notice.
 317         //
 318         // @since 2.0
 319         //
 320         virtual void ICertificatePath_Reserved1(void) {}
 321
 322         //
 323         // This method is for internal use only. Using this method can cause behavioral, security-related,
 324         // and consistency-related issues in the application.
 325         //
 326         // This method is reserved and may change its name at any time without prior notice.
 327         //
 328         // @since 2.0
 329         //
 330         virtual void ICertificatePath_Reserved2(void) {}
 331
 332         //
 333         // This method is for internal use only. Using this method can cause behavioral, security-related,
 334         // and consistency-related issues in the application.
 335         //
 336         // This method is reserved and may change its name at any time without prior notice.
 337         //
 338         // @since 2.0
 339         //
 340         virtual void ICertificatePath_Reserved3(void) {}
 341
 342 }; //ICertificatePath
 343
 344 } } } //Tizen::Security::Cert
 345
 346 #endif //_FSEC_CERT_ICERTIFICATE_PATH_H_