inc/FSecCryptoKeaKeyExchange.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           FSecCryptoKeaKeyExchange.h
  20   *     @brief          This is the header file for the %KeaKeyExchange class.
  21  *
  22   *     This header file contains the declarations of the %KeaKeyExchange class.
  23  */
  24 #ifndef _FSEC_CRYPTO_KEA_KEY_EXCHANGE_H_
  25 #define _FSEC_CRYPTO_KEA_KEY_EXCHANGE_H_
  26
  27 #include <FSecCryptoIKeyExchange.h>
  28
  29
  30 namespace Tizen { namespace Security { namespace Crypto
  31 {
  32
  33 /**
  34  *      @class          KeaKeyExchange
  35  *      @brief          This class provides methods for performing the key exchange mechanism using Key Exchange Algorithm (KEA).
  36  *
  37   *     @since       2.0
  38  *
  39  *      The %KeaKeyExchange class provides a KEA key exchange between two communicating users. @n
  40  *
  41   *     For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/security/key_exchange_algorithm.htm">Key exchanging</a>.
  42  *
  43   *     @see    IKeyExchange
  44   *     @see    KeyPairGenerator
  45  *
  46   *     The following example demonstrates how to use the %KeaKeyExchange class.
  47   *     @code
  48  *
  49  *      void KeaGenerateSecretExample(void)
  50  *      {
  51  *
  52  *              result r = E_SUCCESS;
  53  *              KeyPair *pKeyPairAlice1 = null;
  54  *              IPrivateKey *pPriKeyAlice1 = null;
  55  *              IPrivateKey *pPriKeyAlice2 = null;
  56  *              KeyPair *pKeyPairAlice2 = null;
  57  *              IPublicKey *pPubKeyAlice1 = null;
  58  *              IPublicKey *pPubKeyAlice2 = null;
  59  *
  60  *              KeyPair *pKeyPairBob1 = null;
  61  *              IPrivateKey *pPriKeyBob1 = null;
  62  *              IPrivateKey *pPriKeyBob2 = null;
  63  *              KeyPair *pKeyPairBob2 = null;
  64  *              IPublicKey *pPubKeyBob1 = null;
  65  *              IPublicKey *pPubKeyBob2 = null;
  66  *
  67  *
  68  *              KeyPairGenerator *pKeyPairGen = null;
  69  *              IKeyParameters *pKeyParams = null;
  70  *
  71  *              int size = 1024;
  72  *              KeaKeyExchange *pKeaKeyExchangeAlice = null;
  73  *              KeaKeyExchange *pKeaKeyExchangeBob = null;
  74  *              ByteBuffer *pBuffer = null;
  75  *              ByteBuffer *pBuffer1 = null;
  76  *
  77  *
  78  *              // Generates the key.
  79  *              pKeyPairGen = new KeyPairGenerator();
  80  *              if (pKeyPairGen == null)
  81  *              {
  82  *                      goto CATCH;
  83  *              }
  84  *
  85  *
  86  *              r = pKeyPairGen->Construct(size, L"KEA");
  87  *              if (IsFailed(r))
  88  *              {
  89  *                      goto CATCH;
  90  *              }
  91  *
  92  *
  93  *              pKeyParams = pKeyPairGen->GenerateKeyParametersN();
  94  *              if (pKeyParams == null)
  95  *              {
  96  *                      goto CATCH;
  97  *              }
  98  *
  99  *
 100  *              pKeyPairAlice1 = pKeyPairGen->GenerateKeyPairN(pKeyParams);
 101  *              if (pKeyPairAlice1 == null)
 102  *              {
 103  *                      goto CATCH;
 104  *              }
 105  *
 106  *              pKeyPairAlice2 = pKeyPairGen->GenerateKeyPairN(pKeyParams);
 107  *              if (pKeyPairAlice2 == null)
 108  *              {
 109  *                      goto CATCH;
 110  *              }
 111  *
 112  *              pPriKeyAlice1 = pKeyPairAlice1->GetPrivateKey();
 113  *              if (pPriKeyAlice1 == null)
 114  *              {
 115  *                      goto CATCH;
 116  *              }
 117  *
 118  *              pPubKeyAlice1 = pKeyPairAlice1->GetPublicKey();
 119  *              if (pPubKeyAlice1 == null)
 120  *              {
 121  *                      goto CATCH;
 122  *              }
 123  *
 124  *              pPriKeyAlice2 = pKeyPairAlice2->GetPrivateKey();
 125  *              if (pPriKeyAlice2 == null)
 126  *              {
 127  *                      goto CATCH;
 128  *              }
 129  *
 130  *              pPubKeyAlice2 = pKeyPairAlice2->GetPublicKey();
 131  *              if (pPubKeyAlice2 == null)
 132  *              {
 133  *                      goto CATCH;
 134  *              }
 135  *
 136  *              pKeyPairBob1 = pKeyPairGen->GenerateKeyPairN(pKeyParams);
 137  *              if (pKeyPairBob1 == null)
 138  *              {
 139  *                      goto CATCH;
 140  *              }
 141  *
 142  *              pKeyPairBob2 = pKeyPairGen->GenerateKeyPairN(pKeyParams);
 143  *              if (pKeyPairBob2 == null)
 144  *              {
 145  *                      goto CATCH;
 146  *              }
 147  *
 148  *              pPriKeyBob1 = pKeyPairBob1->GetPrivateKey();
 149  *              if (pPriKeyBob1 == null)
 150  *              {
 151  *                      goto CATCH;
 152  *              }
 153  *
 154  *              pPubKeyBob1 = pKeyPairBob1->GetPublicKey();
 155  *              if (pPubKeyBob1 == null)
 156  *              {
 157  *                      goto CATCH;
 158  *              }
 159  *
 160  *              pPriKeyBob2 = pKeyPairBob2->GetPrivateKey();
 161  *              if (pPriKeyBob2 == null)
 162  *              {
 163  *                      goto CATCH;
 164  *              }
 165  *
 166  *              pPubKeyBob2 = pKeyPairBob2->GetPublicKey();
 167  *              if (pPubKeyBob2 == null)
 168  *              {
 169  *                      goto CATCH;
 170  *              }
 171  *
 172  *
 173  *              pKeaKeyExchangeAlice = new KeaKeyExchange();
 174  *              if (pKeaKeyExchangeAlice == null)
 175  *              {
 176  *                      goto CATCH;
 177  *              }
 178  *
 179  *              pKeaKeyExchangeBob = new KeaKeyExchange();
 180  *              if (pKeaKeyExchangeBob == null)
 181  *              {
 182  *                      goto CATCH;
 183  *              }
 184  *
 185  *              r = pKeaKeyExchangeAlice->Construct(*pKeyParams);
 186  *              if (IsFailed(r))
 187  *              {
 188  *                      goto CATCH;
 189  *              }
 190  *
 191  *              r = pKeaKeyExchangeAlice->DoPhase(*pPriKeyAlice1, *pPubKeyBob1);
 192  *              if (IsFailed(r))
 193  *              {
 194  *                      goto CATCH;
 195  *              }
 196  *
 197  *              r = pKeaKeyExchangeBob->Construct(*pKeyParams);
 198  *              if (IsFailed(r))
 199  *              {
 200  *                      goto CATCH;
 201  *              }
 202  *
 203  *              r = pKeaKeyExchangeBob->DoPhase(*pPriKeyBob1, *pPubKeyAlice1);
 204  *              if (IsFailed(r))
 205  *              {
 206  *                      goto CATCH;
 207  *              }
 208  *
 209  *              pBuffer =  pKeaKeyExchangeAlice->GenerateSecretN(*pPriKeyAlice2, *pPubKeyBob2);
 210  *              if (pBuffer == null)
 211  *              {
 212  *                      goto CATCH;
 213  *              }
 214  *
 215  *              pBuffer1 = pKeaKeyExchangeBob->GenerateSecretN(*pPriKeyBob2, *pPubKeyAlice2);
 216  *              if (pBuffer1 == null)
 217  *              {
 218  *                      goto CATCH;
 219  *              }
 220  *
 221  *              if (*pBuffer == *pBuffer1)
 222  *              {
 223  *                      AppLog("Secret is Generated Successfully");
 224  *              }
 225  *              else
 226  *              {
 227  *                      goto CATCH;
 228  *              }
 229  *
 230  *      CATCH:
 231  *
 232  *              delete pKeyPairGen;
 233  *              delete pKeyPairAlice1;
 234  *              delete pKeyPairAlice2;
 235  *              delete pKeyPairBob1;
 236  *              delete pKeyPairBob2;
 237  *              delete pBuffer;
 238  *              delete pBuffer1;
 239  *              delete pKeaKeyExchangeAlice;
 240  *              delete pKeaKeyExchangeBob;
 241  *              delete pKeyParams;
 242  *      }
 243  *      @endcode
 244  *
 245  */
 246
 247 class _OSP_EXPORT_ KeaKeyExchange
 248         : public virtual IKeyExchange
 249         , public Tizen::Base::Object
 250 {
 251
 252 public:
 253         /**
 254          *      The object is not fully constructed after this constructor is called. For full construction, @n
 255          *      the Construct() method must be called right after calling this constructor.
 256          *
 257          *      @since          2.0
 258          */
 259         KeaKeyExchange(void);
 260
 261         /**
 262          *      This destructor overrides Tizen::Base::Object::~Object().
 263          *
 264          *      @since          2.0
 265          */
 266         virtual ~KeaKeyExchange(void);
 267
 268         /**
 269          *      Computes the shared secret in a phase-wise manner. @n
 270          *      The %DoPhase() method requires the first party's private key(s) and the second party's public key(s)
 271          *      to generate the shared secret.
 272          *      This method is used in algorithms such as the KEA algorithm and also for a multi-party key exchange.
 273          *
 274          *      @since          2.0
 275          *
 276          *      @return         An error code
 277          *      @param[in]      privateKey                              The private key component of the first party to instantiate
 278          *      @param[in]      publicKey                               The public key component of the second party to instantiate
 279          *      @exception      E_SUCCESS                               The method is successful.
 280          *      @exception      E_INVALID_ARG                   A specified input parameter is invalid.
 281          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 282          *
 283          */
 284         virtual result DoPhase(Tizen::Security::IPrivateKey& privateKey, Tizen::Security::IPublicKey& publicKey);
 285
 286         /**
 287          *      Initializes this instance of %IKeyExchange with the specified key parameters.
 288          *
 289          *      @since          2.0
 290          *
 291          *      @return         An error code
 292          *      @param[in]      keyParameters                   The domain parameters of the key exchange algorithm @n
 293          *                                                                              This parameter needs to be instantiated.
 294          *      @exception      E_SUCCESS                               The method is successful.
 295          *      @exception      E_INVALID_ARG                   The specified input parameter is invalid.
 296          *      @exception      E_OUT_OF_MEMORY The memory is insufficient.
 297          */
 298         virtual result Construct(const Tizen::Security::IKeyParameters& keyParameters);
 299
 300         /**
 301          *      Generates the final shared secret among two parties.
 302          *
 303          *      @since          2.0
 304          *
 305          *      @return         A pointer to the Tizen::Base::ByteBuffer class that contains the generated secret key, @n
 306          *                              else @c null if the method fails to generate the secret key
 307          *      @param[in]      privateKey                              The private key component of the first party to instantiate
 308          *      @param[in]      publicKey                               The public key component of the second party to instantiate
 309          *      @exception      E_SUCCESS                               The method is successful.
 310          *      @exception      E_INVALID_ARG                   A specified input parameter is invalid.
 311          *      @exception      E_OUT_OF_MEMORY                 The memory is insufficient.
 312          *      @exception      E_SYSTEM                                A system error has occurred. @n
 313          *                                                                              The method has failed to operate with the openssl library, or
 314          *                                                                              the Tizen::Base::ByteBuffer operation has failed.
 315          *      @remarks        The specific error code can be accessed using the GetLastResult() method.
 316          */
 317         virtual Tizen::Base::ByteBuffer* GenerateSecretN(Tizen::Security::IPrivateKey& privateKey, Tizen::Security::IPublicKey& publicKey);
 318
 319 private:
 320
 321         //
 322         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 323         //
 324         // @since 2.0
 325         //
 326         KeaKeyExchange(const KeaKeyExchange& rhs);
 327
 328         //
 329         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 330         //
 331         // @since 2.0
 332         //
 333         KeaKeyExchange& operator =(const KeaKeyExchange& rhs);
 334
 335 private:
 336         Tizen::Base::ByteBuffer* __pParamsP;
 337         Tizen::Base::ByteBuffer* __pParamsG;
 338
 339         Tizen::Base::ByteBuffer* __pPrivateComponent;
 340         Tizen::Base::ByteBuffer* __pPublicComponent;
 341
 342         class _KeaKeyExchangeImpl* __pKeaKeyExchangeImpl;
 343         friend class _KeaKeyExchangeImpl;
 344
 345 }; //KeaKeyExchange
 346
 347 } } } //Tizen::Security::Crypto
 348
 349 #endif //_FSEC_CRYPTO_KEA_KEY_EXCHANGE_H_