Skip to content

Commit 5d80d0f

Browse files
author
Derek Jones
committed
Update Encrypt lib docs
1 parent d386f25 commit 5d80d0f

File tree

1 file changed

+105
-71
lines changed

1 file changed

+105
-71
lines changed

‎user_guide_src/source/libraries/encryption.rst

Lines changed: 105 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,17 @@ reasonable degree of security for encrypted sessions or other such
1010
"light" purposes. If Mcrypt is available, you'll be provided with a high
1111
degree of security appropriate for storage.
1212

13+
.. contents::
14+
:local:
15+
16+
.. raw:: html
17+
18+
<div class="custom-index container"></div>
19+
20+
****************************
21+
Using the Encryption Library
22+
****************************
23+
1324
Setting your Key
1425
================
1526

@@ -61,104 +72,127 @@ initialized in your controller using the **$this->load->library** function::
6172

6273
$this->load->library('encrypt');
6374

64-
Once loaded, the Encrypt library object will be available using:
65-
$this->encrypt
75+
Once loaded, the Encrypt library object will be available using
76+
``$this->encrypt``
77+
78+
***************
79+
Class Reference
80+
***************
81+
82+
.. class:: CI_Encrypt
83+
84+
.. method:: encode($string, $key = '')
85+
86+
:param string $string: contents to be encrypted
87+
:param string $key: encryption key
88+
:returns: string
89+
90+
Performs the data encryption and returns it as a string. Example::
91+
92+
$msg = 'My secret message';
93+
94+
$encrypted_string = $this->encrypt->encode($msg);
95+
96+
You can optionally pass your encryption key via the second parameter if
97+
you don't want to use the one in your config file::
98+
99+
$msg = 'My secret message';
100+
$key = 'super-secret-key';
101+
102+
$encrypted_string = $this->encrypt->encode($msg, $key);
103+
66104

67-
$this->encrypt->encode()
68-
========================
105+
.. method:: decode($string, $key = '')
69106

70-
Performs the data encryption and returns it as a string. Example::
107+
:param string $string: contents to be decrypted
108+
:param string $key: encryption key
109+
:returns: string
71110

72-
$msg = 'My secret message';
111+
Decrypts an encoded string. Example::
73112

74-
$encrypted_string = $this->encrypt->encode($msg);
75-
113+
$encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84';
76114

77-
You can optionally pass your encryption key via the second parameter if
78-
you don't want to use the one in your config file::
115+
$plaintext_string = $this->encrypt->decode($encrypted_string);
79116

80-
$msg = 'My secret message';
81-
$key = 'super-secret-key';
117+
You can optionally pass your encryption key via the second parameter if
118+
you don't want to use the one in your config file::
82119

83-
$encrypted_string = $this->encrypt->encode($msg, $key);
120+
$msg = 'My secret message';
121+
$key = 'super-secret-key';
84122

85-
$this->encrypt->decode()
86-
========================
123+
$encrypted_string = $this->encrypt->decode($msg, $key);
87124

88-
Decrypts an encoded string. Example::
89125

90-
$encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84';
126+
.. method:: set_cipher($cipher)
91127

92-
$plaintext_string = $this->encrypt->decode($encrypted_string);
128+
:param int $cipher: valid PHP Mcrypt cypher constant
129+
:returns: CI_Encrypt object for method chaining
93130

94-
You can optionally pass your encryption key via the second parameter if
95-
you don't want to use the one in your config file::
131+
Permits you to set an Mcrypt cipher. By default it uses
132+
**MCRYPT_RIJNDAEL_256**. Example::
96133

97-
$msg = 'My secret message';
98-
$key = 'super-secret-key';
134+
$this->encrypt->set_cipher(MCRYPT_BLOWFISH);
99135

100-
$encrypted_string = $this->encrypt->decode($msg, $key);
136+
Please visit php.net for a list of `available
137+
ciphers <http://php.net/mcrypt>`_.
101138

102-
$this->encrypt->set_cipher();
103-
==============================
139+
If you'd like to manually test whether your server supports Mcrypt you
140+
can use::
104141

105-
Permits you to set an Mcrypt cipher. By default it uses
106-
**MCRYPT_RIJNDAEL_256**. Example::
142+
echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup';
107143

108-
$this->encrypt->set_cipher(MCRYPT_BLOWFISH);
109144

110-
Please visit php.net for a list of `available
111-
ciphers <http://php.net/mcrypt>`_.
145+
.. method:: set_mode($mode)
112146

113-
If you'd like to manually test whether your server supports Mcrypt you
114-
can use::
147+
:param int $mode: valid PHP Mcrypt mode constant
148+
:returns: CI_Encrypt object for method chaining
115149

116-
echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup';
150+
Permits you to set an Mcrypt mode. By default it uses **MCRYPT_MODE_CBC**.
151+
Example::
117152

118-
$this->encrypt->set_mode();
119-
============================
153+
$this->encrypt->set_mode(MCRYPT_MODE_CFB);
120154

121-
Permits you to set an Mcrypt mode. By default it uses **MCRYPT_MODE_CBC**.
122-
Example::
155+
Please visit php.net for a list of `available
156+
modes <http://php.net/mcrypt>`_.
123157

124-
$this->encrypt->set_mode(MCRYPT_MODE_CFB);
125158

126-
Please visit php.net for a list of `available
127-
modes <http://php.net/mcrypt>`_.
159+
.. method:: encode_from_legacy($string[, $legacy_mode = MCRYPT_MODE_ECB[, $key = '']])
128160

129-
$this->encrypt->encode_from_legacy($orig_data, $legacy_mode = MCRYPT_MODE_ECB, $key = '');
130-
==========================================================================================
161+
:param string $string: contents to be encrypted
162+
:param int $legacy_mode: valid PHP Mcrypt cypher constant
163+
:param string $key: encryption key
164+
:returns: string
131165

132-
Enables you to re-encode data that was originally encrypted with
133-
CodeIgniter 1.x to be compatible with the Encryption library in
134-
CodeIgniter 2.x. It is only necessary to use this method if you have
135-
encrypted data stored permanently such as in a file or database and are
136-
on a server that supports Mcrypt. "Light" use encryption such as
137-
encrypted session data or transitory encrypted flashdata require no
138-
intervention on your part. However, existing encrypted Sessions will be
139-
destroyed since data encrypted prior to 2.x will not be decoded.
166+
Enables you to re-encode data that was originally encrypted with
167+
CodeIgniter 1.x to be compatible with the Encryption library in
168+
CodeIgniter 2.x. It is only necessary to use this method if you have
169+
encrypted data stored permanently such as in a file or database and are
170+
on a server that supports Mcrypt. "Light" use encryption such as
171+
encrypted session data or transitory encrypted flashdata require no
172+
intervention on your part. However, existing encrypted Sessions will be
173+
destroyed since data encrypted prior to 2.x will not be decoded.
140174

141-
.. important::
142-
**Why only a method to re-encode the data instead of maintaining legacy
143-
methods for both encoding and decoding?** The algorithms in the
144-
Encryption library have improved in CodeIgniter 2.x both for performance
145-
and security, and we do not wish to encourage continued use of the older
146-
methods. You can of course extend the Encryption library if you wish and
147-
replace the new methods with the old and retain seamless compatibility
148-
with CodeIgniter 1.x encrypted data, but this a decision that a
149-
developer should make cautiously and deliberately, if at all.
175+
.. important::
176+
**Why only a method to re-encode the data instead of maintaining legacy
177+
methods for both encoding and decoding?** The algorithms in the
178+
Encryption library have improved in CodeIgniter 2.x both for performance
179+
and security, and we do not wish to encourage continued use of the older
180+
methods. You can of course extend the Encryption library if you wish and
181+
replace the new methods with the old and retain seamless compatibility
182+
with CodeIgniter 1.x encrypted data, but this a decision that a
183+
developer should make cautiously and deliberately, if at all.
150184

151-
::
185+
::
152186

153-
$new_data = $this->encrypt->encode_from_legacy($old_encrypted_string);
187+
$new_data = $this->encrypt->encode_from_legacy($old_encrypted_string);
154188

155-
====================== =============== =======================================================================
156-
Parameter Default Description
157-
====================== =============== =======================================================================
158-
**$orig_data** n/a The original encrypted data from CodeIgniter 1.x's Encryption library
159-
**$legacy_mode** MCRYPT_MODE_ECB The Mcrypt mode that was used to generate the original encrypted data.
160-
CodeIgniter 1.x's default was MCRYPT_MODE_ECB, and it will assume that
161-
to be the case unless overridden by this parameter.
162-
**$key** n/a The encryption key. This it typically specified in your config file as
163-
outlined above.
164-
====================== =============== =======================================================================
189+
====================== =============== =======================================================================
190+
Parameter Default Description
191+
====================== =============== =======================================================================
192+
**$orig_data** n/a The original encrypted data from CodeIgniter 1.x's Encryption library
193+
**$legacy_mode** MCRYPT_MODE_ECB The Mcrypt mode that was used to generate the original encrypted data.
194+
CodeIgniter 1.x's default was MCRYPT_MODE_ECB, and it will assume that
195+
to be the case unless overridden by this parameter.
196+
**$key** n/a The encryption key. This it typically specified in your config file as
197+
outlined above.
198+
====================== =============== =======================================================================

0 commit comments

Comments
 (0)