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