modules/aes/API.txt

$Id: $

Here's a brief and simple run-through of the functions which might be interesting from a developers point of view. Most (see exceptions below) of the functions are implementation independant, so behaviour should be consistent regardless of which implementation (mcrypt or phpseclib) is used.

Implementation independence exceptions:

1. aes_make_iv is mute when using phpseclib since that implementation handle its own IV internally.

2. The $custom_cipher and $custom_iv arguments to aes_encrypt and aes_decrypt are ignored when using phpseclib, since that implementation doesn't support changing these values. Passing these arguments as anything else than null will generate warnings in the watchdog when using phpseclib.

---------------------------------------------------------------------------------
Function:
string|false aes_encrypt($string, $base64encode = true, $custom_key = null, $custom_cipher = null, $custom_iv = null, $custom_implementation = null)

Description:
Encrypts a string.

Arguments:
string $string The string to encrypt.
(optional) bool $base64encode Whether to return the string base64 encoded (recommended for database insertion).
(optional) string $custom_key Use this as the key rather than the stored one for this operation.
(optional) string $custom_cipher Use this cipher rather than the default one. (only with Mcrypt - ignored with phpseclib)
(optional) string $custom_iv Use this initialization vector instead of the default one.
(optional) string $custom_implementation Can be "phpseclib" or "mcrypt". Warning: Does not check if the requested implementation actually exists.

Returns:
The encrypted string on success, false on error.

---------------------------------------------------------------------------------
Function:
string|false aes_decrypt($string, $base64encoded = true, $custom_key = null, $custom_cipher = null, $custom_iv = null, $custom_implementation = null)

Description:
Decrypts a string of encrypted data.

Arguments:
string $string The string to decrypt.
(optional) bool $base64encode Whether this encrypted string is base64 encoded or not.
(optional) string $custom_key Use this as the key rather than the stored one for this operation.
(optional) string $custom_cipher Use this cipher rather than the default one. (only with Mcrypt - ignored with phpseclib)
(optional) string $custom_iv Use this initialization vector instead of the default one.
(optional) string $custom_implementation Can be "phpseclib" or "mcrypt". Warning: Does not check if the requested implementation actually exists.

Returns:
The decrypted string on success, false on error.

---------------------------------------------------------------------------------
Function:
bool aes_password_exists($uid)

Description:
Checks if a users password exists.

Arguments:
int $uid The user ID.

Returns:
True or false.

---------------------------------------------------------------------------------
Function:
string|false aes_get_password($uid, $decrypt = false)

Description:
Gets a users password, in plain text, or in it's encrypted form.

Arguments:
int $uid The user ID.
(optional) bool $decrypt Whether to decrypt the password before returning it, or not. Defaults to false.

Returns:
The password on success, false on failure.

---------------------------------------------------------------------------------
Function:
string aes_get_key()

Description:
Gets the current key used for the encryption system. If there's currently no key defined, this function will generate one, store it, and return it.

Arguments:
none

Returns:
The key.

---------------------------------------------------------------------------------
Function:
bool aes_store_key($key)

Description:
Stores the key given by writing it to the storage method currently used (database or file).

Arguments:
string $key The key.

Returns:
True on success, false on failure.

---------------------------------------------------------------------------------
Function:
void aes_delete_key($storage_method)

Description:
Deletes the encryption system key.

Arguments:
string $storage_method The storage method used to store the key. "Database" or "File".

Returns:
nothing

---------------------------------------------------------------------------------
Function:
string aes_make_key()

Description:
Generates a new key.

Arguments:
none

Returns:
The newly generated key.

---------------------------------------------------------------------------------
Function:
void aes_make_iv($ignore_implementation = false)

Description:
Generates a new initialization vector and stores it (overwrites old IV!). NOTE: Only use this with the Mcrypt implementation, phpseclib has its own IV management.

Arguments:
(optional) bool $ignore_implementation Forces aes_make_iv to create and store a new IV even if the phpseclib implementation is used.

Returns:
nothing
1	$Id: $
2
3	Here's a brief and simple run-through of the functions which might be interesting from a developers point of view. Most (see exceptions below) of the functions are implementation independant, so behaviour should be consistent regardless of which implementation (mcrypt or phpseclib) is used.
4
5	Implementation independence exceptions:
6
7	1. aes_make_iv is mute when using phpseclib since that implementation handle its own IV internally.
8
9	2. The $custom_cipher and $custom_iv arguments to aes_encrypt and aes_decrypt are ignored when using phpseclib, since that implementation doesn't support changing these values. Passing these arguments as anything else than null will generate warnings in the watchdog when using phpseclib.
10
11	---------------------------------------------------------------------------------
12	Function:
13	string\|false aes_encrypt($string, $base64encode = true, $custom_key = null, $custom_cipher = null, $custom_iv = null, $custom_implementation = null)
14
15	Description:
16	Encrypts a string.
17
18	Arguments:
19	string $string The string to encrypt.
20	(optional) bool $base64encode Whether to return the string base64 encoded (recommended for database insertion).
21	(optional) string $custom_key Use this as the key rather than the stored one for this operation.
22	(optional) string $custom_cipher Use this cipher rather than the default one. (only with Mcrypt - ignored with phpseclib)
23	(optional) string $custom_iv Use this initialization vector instead of the default one.
24	(optional) string $custom_implementation Can be "phpseclib" or "mcrypt". Warning: Does not check if the requested implementation actually exists.
25
26	Returns:
27	The encrypted string on success, false on error.
28
29	---------------------------------------------------------------------------------
30	Function:
31	string\|false aes_decrypt($string, $base64encoded = true, $custom_key = null, $custom_cipher = null, $custom_iv = null, $custom_implementation = null)
32
33	Description:
34	Decrypts a string of encrypted data.
35
36	Arguments:
37	string $string The string to decrypt.
38	(optional) bool $base64encode Whether this encrypted string is base64 encoded or not.
39	(optional) string $custom_key Use this as the key rather than the stored one for this operation.
40	(optional) string $custom_cipher Use this cipher rather than the default one. (only with Mcrypt - ignored with phpseclib)
41	(optional) string $custom_iv Use this initialization vector instead of the default one.
42	(optional) string $custom_implementation Can be "phpseclib" or "mcrypt". Warning: Does not check if the requested implementation actually exists.
43
44	Returns:
45	The decrypted string on success, false on error.
46
47	---------------------------------------------------------------------------------
48	Function:
49	bool aes_password_exists($uid)
50
51	Description:
52	Checks if a users password exists.
53
54	Arguments:
55	int $uid The user ID.
56
57	Returns:
58	True or false.
59
60	---------------------------------------------------------------------------------
61	Function:
62	string\|false aes_get_password($uid, $decrypt = false)
63
64	Description:
65	Gets a users password, in plain text, or in it's encrypted form.
66
67	Arguments:
68	int $uid The user ID.
69	(optional) bool $decrypt Whether to decrypt the password before returning it, or not. Defaults to false.
70
71	Returns:
72	The password on success, false on failure.
73
74	---------------------------------------------------------------------------------
75	Function:
76	string aes_get_key()
77
78	Description:
79	Gets the current key used for the encryption system. If there's currently no key defined, this function will generate one, store it, and return it.
80
81	Arguments:
82	none
83
84	Returns:
85	The key.
86
87	---------------------------------------------------------------------------------
88	Function:
89	bool aes_store_key($key)
90
91	Description:
92	Stores the key given by writing it to the storage method currently used (database or file).
93
94	Arguments:
95	string $key The key.
96
97	Returns:
98	True on success, false on failure.
99
100	---------------------------------------------------------------------------------
101	Function:
102	void aes_delete_key($storage_method)
103
104	Description:
105	Deletes the encryption system key.
106
107	Arguments:
108	string $storage_method The storage method used to store the key. "Database" or "File".
109
110	Returns:
111	nothing
112
113	---------------------------------------------------------------------------------
114	Function:
115	string aes_make_key()
116
117	Description:
118	Generates a new key.
119
120	Arguments:
121	none
122
123	Returns:
124	The newly generated key.
125
126	---------------------------------------------------------------------------------
127	Function:
128	void aes_make_iv($ignore_implementation = false)
129
130	Description:
131	Generates a new initialization vector and stores it (overwrites old IV!). NOTE: Only use this with the Mcrypt implementation, phpseclib has its own IV management.
132
133	Arguments:
134	(optional) bool $ignore_implementation Forces aes_make_iv to create and store a new IV even if the phpseclib implementation is used.
135
136	Returns:
137	nothing