1## KDF
2
3The `KDF` abstract class represent base class for all Key Derivation Functions.
4It is a parent of [`PBKDF2`](pbkdf2.md).
5
6### Instance Methods
7
8#### `KDF::__construct($length, $salt = NUL)`
9
10_**Description**_: Creates a new `KDF` class.
11
12The `KDF` class is an abstract class which means that it can't be instantiated.
13This constructor defines just logic for its subclasses. It sets a supplied
14length and salt if supplied. It can throw `KDFException` if the salt size
15or length is over the max limits.
16
17##### *Parameters*
18
19*length* : `int` - the key length
20*salt* : `string` - the salt
21
22##### *Return value*
23
24`KDF`: New instances of the `KDF` subclass.
25
26##### *Throws*
27
28It can throw `KDFException` with code
29
30- `KDFException::KEY_LENGTH_LOW` - the supplied key length is too low
31- `KDFException::KEY_LENGTH_HIGH` - the supplied key length is too high
32- `KDFException::SALT_LENGTH_HIGH` - if the data length exceeds
33C INT_MAX
34
35#### `KDF::derive($password)`
36
37_**Description**_: An abstract method to derive the key from the password.
38
39The `derive` abstract method has to be used in all subclasses to derive
40the key from the supplied password. If the derivation fails, it must
41throw `KDFException`.
42
43##### *Parameters*
44
45*password* : `string` - the password
46
47##### *Return value*
48
49`string`: Derived key.
50
51##### *Throws*
52
53The implementing method can throw `KDFException` with code
54
55- `KDFException::DERIVATION_FAILED` - the derivation failed
56- `KDFException::PASSWORD_LENGTH_INVALID` - if the password length
57exceeds C INT_MAX
58
59#### `KDF::getLength()`
60
61_**Description**_: Returns a length of the derived key.
62
63This method returns a lenght of the key that will be or was derived
64by the `KDF::derive`.
65
66##### *Parameters*
67
68This method has no parameters.
69
70##### *Throws*
71
72This method does not throw any exception.
73
74##### *Return value*
75
76`int`: The lenght of the derived key.
77
78#### `KDF::getSalt()`
79
80_**Description**_: Returns salt for the key derivation.
81
82This method returns salt string that will be used when deriving a key
83using `KDF::derive`.
84
85##### *Parameters*
86
87This method has no parameters.
88
89##### *Throws*
90
91This method does not throw any exception.
92
93##### *Return value*
94
95`string`: The salt.
96
97#### `KDF::setLength($length)`
98
99_**Description**_: Sets a length for the derived key.
100
101This method sets a length that will be the string length of the derived key.
102
103##### *Parameters*
104
105*length* : `int` - key length
106
107##### *Throws*
108
109It can throw `KDFException` with code
110
111- `KDFException::KEY_LENGTH_LOW` - if key length is less than 0
112- `KDFException::KEY_LENGTH_HIGH` - if key length is more than C INT_MAX
113value
114
115##### *Return value*
116
117`bool`: true if the key length was set succesfully
118
119#### `KDF::setSalt($salt)`
120
121_**Description**_: Sets salt for the key derivation.
122
123This method sets salt that will be used when deriving key using `KDF::derive`.
124
125##### *Parameters*
126
127*salt* : `string` - salt for the key derivation
128
129##### *Throws*
130
131It can throw `KDFException` with code
132
133- `KDFException::SALT_LENGTH_HIGH` - if the salt length is more than C INT_MAX
134
135##### *Return value*
136
137`bool`: true if the salt was set succesfully
138