inc/FSecPkcsPkcs05PbKdf2Parameters.h

   1 //
   2 // Copyright (c) 2013 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                FSecPkcsPkcs05PbKdf2Parameters.h
  19  * @brief               This is the header file for the %Pkcs05PbKdf2Parameters class.
  20  *
  21  * This header file contains the declarations of the %Pkcs05PbKdf2Parameters class.
  22  */
  23
  24 #ifndef _FSEC_PKCS_PKCS_05_PBKDF2_PARAMETERS_H_
  25 #define _FSEC_PKCS_PKCS_05_PBKDF2_PARAMETERS_H_
  26
  27 #include <FBaseByteBuffer.h>
  28 #include <FSecPkcsIAlgorithmParameters.h>
  29 #include <FSecPkcsAlgorithmIdentifier.h>
  30 #include <FSecPkcsTypes.h>
  31
  32 namespace Tizen { namespace Security { namespace Pkcs
  33 {
  34
  35 /**
  36  * @class               Pkcs05PbKdf2Parameters
  37  * @brief               This class provides methods for the functionalities specified by the PKCS05 KDF2 scheme.
  38  *
  39  * @since               2.1
  40  *
  41  * The %Pkcs05PbKdf2Parameters class provides methods for the functionalities specified by the PKCS05 KDF2 scheme. PBKDF2 applies a pseudo
  42  * random function to derive keys. The length of the derived key is essentially unbounded. However, the maximum effective search
  43  * space for the derived key can be limited by the structure of the underlying pseudo random function.
  44  *
  45  * This is defined in ASN.1 as demonstrated in the following code:
  46  * @code
  47  *                              PBKDF2-params ::= SEQUENCE {
  48  *                              salt CHOICE {
  49  *                              specified OCTET STRING,
  50  *                              otherSource AlgorithmIdentifier {{PBKDF2-SaltSources}}
  51  *                              },
  52  *                              iterationCount INTEGER (1..MAX),
  53  *                              keyLength INTEGER (1..MAX) OPTIONAL,
  54  *                              prf AlgorithmIdentifier {{PBKDF2-PRFs}} DEFAULT
  55  *                              algid-hmacWithSHA1 }
  56  * @endcode
  57  *
  58  */
  59
  60 class _OSP_EXPORT_ Pkcs05PbKdf2Parameters
  61         : public virtual IAlgorithmParameters
  62         , public Tizen::Base::Object
  63 {
  64
  65 public:
  66         /**
  67          * The object is not fully constructed after this constructor is called. @n
  68          * For full construction, the Construct() method must be called right after calling this constructor.
  69          *
  70          * @since               2.1
  71          */
  72         Pkcs05PbKdf2Parameters(void);
  73
  74         /**
  75          * This destructor overrides Tizen::Base::Object::~Object().
  76          *
  77          * @since               2.1
  78          */
  79         virtual ~Pkcs05PbKdf2Parameters(void);
  80
  81         /**
  82          * Initializes this instance of %Pkcs05PbKdf2Parameters with the encoded Tizen::Base::ByteBuffer that contains Password
  83          * Based Key Derivation Function parameters structure(PBKDF2) in ASN.1 DER format.
  84          *
  85          * @since               2.1
  86          *
  87          * @return              An error code
  88          * @param[in]   encodedData                                     The DER encoded Tizen::Base::ByteBuffer of %Pkcs05PbKdf2Parameters
  89          * @exception   E_SUCCESS                                       The method is successful.
  90          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
  91          */
  92         result Construct(const Tizen::Base::ByteBuffer& encodedData);
  93
  94         /**
  95          * Initializes the %Pkcs05PbKdf2Parameters with the specified input parameters values.
  96          *
  97          * @since               2.1
  98          *
  99          * @return              An error code
 100          * @param[in]   saltBuffer                              An instance of Tizen::Base::ByteBuffer holding salt value
 101          * @param[in]   iterationCount                  The positive integer specifying iteration count for generation of password based key
 102          * @param[in]   derivedKeyLength                The positive integer specifying the length of the password based key
 103          * @exception   E_SUCCESS                               The method is successful.
 104          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 105          * @remarks             In this case, when pseudo random function algorithm is not passed, then default HMAC-SHA1 will be used.
 106          */
 107         result Construct(const Tizen::Base::ByteBuffer& saltBuffer, int iterationCount, int derivedKeyLength = 0);
 108
 109         /**
 110          * Initializes this %Pkcs05PbKdf2Parameters instance with the specified input parameters values.
 111          *
 112          * @since               2.1
 113          *
 114          * @return              An error code
 115          * @param[in]   saltBuffer                              An instance of Tizen::Base::ByteBuffer holding salt value
 116          * @param[in]   iterationCount                  The positive integer specifying iteration count for generation of password based key
 117          * @param[in]   prf                                             The AlgorithIdentifier instance holding the underlying pseudo random function to use
 118          *                                                                              to generate a password based key
 119          * @param[in]   derivedKeyLength                The positive integer specifying the length of the password based key
 120          * @exception   E_SUCCESS                               The method is successful.
 121          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 122          */
 123         result Construct(const Tizen::Base::ByteBuffer& saltBuffer, int iterationCount, const AlgorithmIdentifier& prf, int derivedKeyLength = 0);
 124
 125         /**
 126          * Gets the encoded form of the %Pkcs05PbKdf2Parameters instance. @n
 127          * It is assumed that each %Pkcs05PbKdf2Parameters will have only a single form of encoding, for example: ASN.1 DER.
 128          *
 129          * @since               2.1
 130          *
 131          * @return              A pointer to the Tizen::Base::ByteBuffer instance that contains the output, @n
 132          *                              else @c null if an error occurs
 133          * @exception   E_SUCCESS                                       The method is successful.
 134          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
 135          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 136          */
 137         Tizen::Base::ByteBuffer* GetEncodedDataN(void) const;
 138
 139         /**
 140          * Gets the salt byte buffer.
 141          *
 142          * @since               2.1
 143          *
 144          * @return              A reference to the Tizen::Base::ByteBuffer instance containing the specified salt value
 145          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 146          */
 147         const Tizen::Base::ByteBuffer& GetSaltValue(void) const;
 148
 149         /**
 150          * Gets the iteration count. @n
 151          * The purpose of this count is to increase the cost of producing keys from a password, thereby, also increasing the difficulty of attack.
 152          *
 153          * @since               2.1
 154          *
 155          * @return              An integer value containing the iteration count for PBKDF2
 156          *
 157          */
 158         int GetIterationCount(void) const;
 159
 160         /**
 161          * Gets the derived key length. @n
 162          * The %GetDerivedKeyLength() method returns the length of the derived key that is used to generate the password based key.
 163          *
 164          * @since               2.1
 165          *
 166          * @return              An integer value containing the length of the derived key
 167          *
 168          */
 169         int GetDerivedKeyLength(void) const;
 170
 171         /**
 172          * Gets a reference to AlgorithmIdentifier that identifies the underlying pseudo random function.
 173          *
 174          * @since               2.1
 175          *
 176          * @return              A reference to AlgorithmIdentifier containing the algorithm identifier of underlying pseudo random function
 177          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 178          */
 179         const AlgorithmIdentifier& GetPrf(void) const;
 180
 181         /**
 182          *
 183          * Gets a pointer to AlgorithmParameters that identifies the underlying parameters such as PbKdf2,PbEs2,PbMac1. @n
 184          * For this class, %AlgorithmParameters will be of PbKdf2 type.
 185          *
 186          * @since               2.1
 187          *
 188          * @return              A pointer to IAlgorithmParameters containing the algorithm identifier of underlying pseudo random function, @n
 189          *                              else @c null if an error occurs
 190          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 191          */
 192         virtual IAlgorithmParameters* CloneN(void) const;
 193
 194         /**
 195          * Gets the PkcsAlgorithmParameterType value.
 196          *
 197          * @since               2.1
 198          *
 199          * @return              The PkcsAlgorithmParameterType instance holding the enum value @c PKCS_ALGO_PARAM_TYPE_PKCS05_KDF02 for KDF2 Parameters
 200          */
 201         virtual PkcsAlgorithmParameterType GetType(void) const;
 202
 203         /**
 204          * Checks whether the specified instance of %Pkcs05PbKdf2Parameters equals the current instance.
 205          *
 206          * @since               2.1
 207          *
 208          * @return              @c true if the specified instance equals the current instance, @n
 209          *              else @c false
 210          * @param[in]   rhs                                             An instance of %Pkcs05PbKdf2Parameters
 211          * @exception   E_SUCCESS                               The method is successful.
 212          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 213          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 214          */
 215         virtual bool Equals(const Tizen::Base::Object& rhs) const;
 216
 217         /**
 218          * Gets the hash value of the current instance of %Pkcs05PbKdf2Parameters.
 219          *
 220          * @since               2.1
 221          *
 222          * @return              An integer value indicating the hash value of the current instance of %Pkcs05PbKdf2Parameters
 223          */
 224         virtual int GetHashCode(void) const;
 225
 226 private:
 227         // This copy constructor is intentionally declared as private to prohibit @n
 228         // copying of objects by users.
 229         //
 230         // @since               2.1
 231         Pkcs05PbKdf2Parameters(const Pkcs05PbKdf2Parameters& rhs);
 232
 233         // The implementation of this copy assignment operator is intentionally blank and @n
 234         // declared as private to prohibit copying of objects.Use CloneN() to get an exact copy of the instance. @n
 235         // Use Equals() to compare the contents of one instance with the other.
 236         //
 237         // @since               2.1
 238         Pkcs05PbKdf2Parameters& operator =(const Pkcs05PbKdf2Parameters& rhs);
 239
 240 private:
 241         class _Pkcs05PbKdf2ParametersImpl* __pPkcs05PbKdf2ParametersImpl;
 242         friend class _Pkcs05PbKdf2ParametersImpl;
 243 };  // Pkcs05PbKdf2Parameters
 244
 245 } } } // Tizen::Security::Pkcs
 246
 247 #endif //_FSEC_PKCS_PKCS_05_PBKDF2_PARAMETERS_H_