inc/FSecPkcsPkcs05PbKdf2Parameters.h

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