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