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