1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
################
Encryption Class
################
The Encryption Class provides two-way data encryption. It uses a scheme
that either compiles the message using a randomly hashed bitwise XOR
encoding scheme, or is encrypted using the Mcrypt library. If Mcrypt is
not available on your server the encoded message will still provide a
reasonable degree of security for encrypted sessions or other such
"light" purposes. If Mcrypt is available, you'll be provided with a high
degree of security appropriate for storage.
.. contents::
:local:
.. raw:: html
<div class="custom-index container"></div>
****************************
Using the Encryption Library
****************************
Setting your Key
================
A *key* is a piece of information that controls the cryptographic
process and permits an encrypted string to be decoded. In fact, the key
you chose will provide the **only** means to decode data that was
encrypted with that key, so not only must you choose the key carefully,
you must never change it if you intend use it for persistent data.
It goes without saying that you should guard your key carefully. Should
someone gain access to your key, the data will be easily decoded. If
your server is not totally under your control it's impossible to ensure
key security so you may want to think carefully before using it for
anything that requires high security, like storing credit card numbers.
To take maximum advantage of the encryption algorithm, your key should
be 32 characters in length (256 bits). The key should be as random a
string as you can concoct, with numbers and uppercase and lowercase
letters. Your key should **not** be a simple text string. In order to be
cryptographically secure it needs to be as random as possible.
Your key can be either stored in your **application/config/config.php**, or
you can design your own storage mechanism and pass the key dynamically
when encoding/decoding.
To save your key to your **application/config/config.php**, open the file
and set::
$config['encryption_key'] = "YOUR KEY";
Message Length
==============
It's important for you to know that the encoded messages the encryption
function generates will be approximately 2.6 times longer than the
original message. For example, if you encrypt the string "my super
secret data", which is 21 characters in length, you'll end up with an
encoded string that is roughly 55 characters (we say "roughly" because
the encoded string length increments in 64 bit clusters, so it's not
exactly linear). Keep this information in mind when selecting your data
storage mechanism. Cookies, for example, can only hold 4K of
information.
Initializing the Class
======================
Like most other classes in CodeIgniter, the Encryption class is
initialized in your controller using the **$this->load->library** function::
$this->load->library('encrypt');
Once loaded, the Encrypt library object will be available using
``$this->encrypt``
***************
Class Reference
***************
.. class:: CI_Encrypt
.. method:: encode($string[, $key = ''])
:param string $string: Data to encrypt
:param string $key: Encryption key
:returns: Encrypted string
:rtype: string
Performs the data encryption and returns it as a string. Example::
$msg = 'My secret message';
$encrypted_string = $this->encrypt->encode($msg);
You can optionally pass your encryption key via the second parameter if
you don't want to use the one in your config file::
$msg = 'My secret message';
$key = 'super-secret-key';
$encrypted_string = $this->encrypt->encode($msg, $key);
.. method:: decode($string[, $key = ''])
:param string $string: String to decrypt
:param string $key: Encryption key
:returns: Plain-text string
:rtype: string
Decrypts an encoded string. Example::
$encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84';
$plaintext_string = $this->encrypt->decode($encrypted_string);
You can optionally pass your encryption key via the second parameter if
you don't want to use the one in your config file::
$msg = 'My secret message';
$key = 'super-secret-key';
$encrypted_string = $this->encrypt->decode($msg, $key);
.. method:: set_cipher($cipher)
:param int $cipher: Valid PHP MCrypt cypher constant
:returns: CI_Encrypt instance (method chaining)
:rtype: CI_Encrypt
Permits you to set an Mcrypt cipher. By default it uses
``MCRYPT_RIJNDAEL_256``. Example::
$this->encrypt->set_cipher(MCRYPT_BLOWFISH);
Please visit php.net for a list of `available ciphers <http://php.net/mcrypt>`_.
If you'd like to manually test whether your server supports MCrypt you
can use::
echo extension_loaded('mcrypt') ? 'Yup' : 'Nope';
.. method:: set_mode($mode)
:param int $mode: Valid PHP MCrypt mode constant
:returns: CI_Encrypt instance (method chaining)
:rtype: CI_Encrypt
Permits you to set an Mcrypt mode. By default it uses **MCRYPT_MODE_CBC**.
Example::
$this->encrypt->set_mode(MCRYPT_MODE_CFB);
Please visit php.net for a list of `available modes <http://php.net/mcrypt>`_.
.. method:: encode_from_legacy($string[, $legacy_mode = MCRYPT_MODE_ECB[, $key = '']])
:param string $string: String to encrypt
:param int $legacy_mode: Valid PHP MCrypt cipher constant
:param string $key: Encryption key
:returns: Newly encrypted string
:rtype: string
Enables you to re-encode data that was originally encrypted with
CodeIgniter 1.x to be compatible with the Encryption library in
CodeIgniter 2.x. It is only necessary to use this method if you have
encrypted data stored permanently such as in a file or database and are
on a server that supports Mcrypt. "Light" use encryption such as
encrypted session data or transitory encrypted flashdata require no
intervention on your part. However, existing encrypted Sessions will be
destroyed since data encrypted prior to 2.x will not be decoded.
.. important::
**Why only a method to re-encode the data instead of maintaining legacy
methods for both encoding and decoding?** The algorithms in the
Encryption library have improved in CodeIgniter 2.x both for performance
and security, and we do not wish to encourage continued use of the older
methods. You can of course extend the Encryption library if you wish and
replace the new methods with the old and retain seamless compatibility
with CodeIgniter 1.x encrypted data, but this a decision that a
developer should make cautiously and deliberately, if at all.
::
$new_data = $this->encrypt->encode_from_legacy($old_encrypted_string);
====================== =============== =======================================================================
Parameter Default Description
====================== =============== =======================================================================
**$orig_data** n/a The original encrypted data from CodeIgniter 1.x's Encryption library
**$legacy_mode** MCRYPT_MODE_ECB The Mcrypt mode that was used to generate the original encrypted data.
CodeIgniter 1.x's default was MCRYPT_MODE_ECB, and it will assume that
to be the case unless overridden by this parameter.
**$key** n/a The encryption key. This it typically specified in your config file as
outlined above.
====================== =============== =======================================================================
|
