Sunset Rainbow and the Susnet Rainbow logo are registered trademarks of Sunset Rainbow, LLC.
© July 2009 r10/09. All Rights Reserved.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page i
Contents
Contacts
Introduction
SQL Command
Sqlencoder Class - PHP 5
Core API - PHP 4 and PHP 5
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page ii
Contents
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page iii
Contents
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 1
Contacts
Contacts
* Web & Email
Web
When you purchase the product you received a 'proof of purchase' code. This
can be used to access the 'my account' pages on our website.
Do not share your proof of purchase code or product key(s) with anyone you don't trust
with access to your data.
We suggest you create a user account with Sunset Rainbow to better protect your
product key.
Documentaion is maintained on our website.
sunsetrainbow.com
Email
If you find any omissions or errors in this document, please send email
detailing the error or omission to:
info@sunsetrainbow.com
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 2
Introduction
Introduction
* Overview
Sunset Rainbow's SQL Encoder protects your data before it reaches the database (DB). SQL Encoder uses a combination of high grade encryption and obfuscation. You can encode table names, field names, and data fields. Thieves will be unable to find your protected data in DB backup files, network traffic, server logs, etc.
SQL Encoder supports MySQL but comes with an API that will work with a wide variety of other databases.
The Encoder uses multiple encryption and obfuscation keys. It is capable of encoding these kinds of data:
* Database names
* Table names
* Field names
* Non-numeric fields (binary or text)
* Numeric fields (including decimal point numbers).
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 3
Introduction
* Warnings & Important Notices
Product Keys
Do not share your product key with anyone. Doing so will compromise security.
We suggest you create a user account with Sunset Rainbow to better protect your
product key.
Data Recovery
See the Migration & Disaster Recovery section near the end of this manual
before using SQL Encoder to create data you care about.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 4
Introduction
* License
Trial version license - refer to the page you downloaded the product from.
Regual version - refer to the page you downloaded the product from.
If ionCube loader is not installed and you have followed the setup instructions included with
your copy of the software, please refer to
ioncube.com.
ionCube is a registered trademark of ionCube Ltd (ioncube.com)
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 5
Introduction
* PHP Examples
// PHP 5 EXAMPLE ----------------------------------------------------------
require_once('sunsetrlib/sqlencoder/sqlencoder5.php');
/* Example of using the class object */
$sobj = new sqlencoder();
$data = $sobj->encode('Some secret information');
echo 'Decoded info is: '.$sobj->decode($data);
/* Connecting to the database here... */
/* Example of Creating a table with encoded name and encoded field names */
$sql='CREATE TABLE `SRKEY(testsql)` (
`SRKEY(fielda)` INT UNSIGNED NOT NULL , `SRKEY(fieldb)` VARCHAR( 30 ) NOT NULL ,
PRIMARY KEY ( `SRKEY(fielda)` ) ) ENGINE = MYISAM ';
$result = $sobj->sql_query($sql);
/* Using sql query statement to encrypt/decrypt with SQL Encoder
Be sure to read security note regarding sr_addslashes !
*/
$sql='INSERT INTO SRKEY(testsql) (SRKEY(fieldb)) VALUES ('SRENCODE(abcd)')';
$result = $sobj->sql_query($sql);
/* Retrieve from DB - decoding is automatic */
$sql='SELECT * from SRKEY(testsql)';
if (($result = $sobj->sql_query($sql)))
if (($row = $sobj->sql_fetch_array($result, MYSQL_ASSOC)))
{
$plain_data=$row['fieldb']; // plain_data is now 'abcd'
}
/* Example of using SQL Encoder API directly to do all the work */
$sql='SELECT * from '.$sobj->fieldname_decode('testsql');
if (($result = mysql_query($sql)))
if (($row = mysql_fetch_array($result, MYSQL_ASSOC)))
{
$plain_data = $sobj->decode($row[$sobj->fieldname('fieldb')])
}
// -------------------------------------------------------------------------
// PHP 4 EXAMPLE ----------------------------------------------------------
require_once('sunsetrlib/sqlencoder/sqlencoder.php');
$sql='INSERT INTO SRKEY(testsql) (SRKEY(fieldb)) VALUES ('SRENCODE(abcd)')';
$result = sr_sql_query($sql);
/* Retrieve from DB - decoding is automatic */
$sql='SELECT * from SRKEY(testsql)';
if (($result = sr_sql_query($sql)))
if (($row = sr_sql_fetch_array($result, MYSQL_ASSOC)))
{
$plain_data=$row['fieldb']; // plain_data is now 'abcd'
}
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 6
Introduction
* Data Type Requirements
Database Name, Table Names, Field Names
No special requirements.
Non-Numeric Fields
| Encoding Mode | Storage Bytes Required |
| SR_SE_COMPRESS | Typically 20% to 50% of the input. Binary output. |
| SR_SE_BASE64 | Base64 encoding: 1.4 times the input size. Non binary output. |
| SR_SE_BOTH |
Applies SR_SE_BASE64 to output of SR_SE_COMPRESS
|
| SR_SE_RAW | input size + 100 to 150 bytes
Binary output unless base64 was used.
|
| SR_SE_AUTO | Any combination of the other modes |
Numbers
| Data Type | Minimum Encoded Values | Maximum Encoded Value |
| TINYINT | Unusable | Unusable |
| SMALLINT | Unusable | Unusable |
| MEDIUMINT | -988000 | 988000 |
| INT | -2147483648 | 2147483647 |
| BIGINT |
Larger numbers than for INT may be possible but it depends on your
system. Test to be sure.
|
DECIMAL FLOAT and similar |
Values are not rounded by SQL Encoder.
Do not use more than six decimal places in the unencoded data.
You may need up to 10 decimal places to store the encoded value for large numbers.
|
Password Range Reduction
The optional password reduces the unencoded number range by the size of the password.
For decimals: The portion of a number before and after a decimal point are each reduced.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 7
SQL Command
SQL Command
3. Interceptor
The sr_parse() function provides commands you can
place in SQL statements. This section provides informaton on those commands.
You may access these commands via the
sr_sql_query().
3.1 Command
3.1.1 Parser: sr_parse
sr_parse -- Reveal the interpretation SQL Encoder Commands embedded in a SQL query.
Description
string sr_parse (string query)
This command returns the result of interpretation with result strings substitutded for encoded/decoded data.
Nested SQL Encoder commands are not supported so the result of 'SRKEY(SRKEY(x))' will not be what you expect.
Parameters
query: string to be parsed.
Return Values
Result of parsing with these strings replacing SQL Encoder Commands with command results.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 8
SQL Command
3.2 Encoding
3.2.1 Encrypt Data: SRENCODE
SRENCODE -- Encrypt data.
Description
mixed SRENCODE( mixed data )
This command returns the data in an encrypted form. It calls
sr_encode() with mode set to SR_SE_AUTO. Note:
base64 encoding is always applied to data you encode with the SQL COMMAND version of this function. Use
sr_encode() for more control over encoding methods.
Parameters
data: the data to encrypt.
Return Values
Encrypted data.
Notes
Everything within parenthesis is encoded. Thus to encode the string Z123, you write 'SRENCODE(Z123)'. To encode the string 'dentist' you write: 'SRENCODE(dentist)'.
Do not use this function for table names or field names. Use
SRKEY().
sr_fieldname() or
sr_tablename() functions instead.
See also:
SRDECODE(),
sr_decode().
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 9
SQL Command
3.2.2 Encrypt Data: SRENCODEN
SRENCODEN -- Encode a number
Parameters
n: number to encode.
password: optional password number.
Return Values
Encoded represenation of number.
Notes
Everything within parenthesis is encoded.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 10
SQL Command
3.2.3 Encrypt Data: SRENCODENKEY
SRENCODENKEY -- Encode a number
Parameters
n: number to encode.
password: password to add further obfuscation with.
Return Values
Encoded represenation of number.
Notes
Everything within parenthesis is encoded.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 11
SQL Command
3.2.4 Encrypt Data: SRKEY
SRKEY -- Encrypt data
Parameters
string: the data to encode.
Return Values
Encoded string.
Notes
Everything within parenthesis is encoded. Thus to encode the number 123, you write SRKEY(123). To encode the string 'dentist' you write: 'SRKEY(dentist)'.
Do not use this function for field data. Use
sr_encode() instead.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 12
SQL Command
3.1 Decoding
3.3.1 Decrypt data: SRDECODE
SRDECODE -- Decrypt data
Description
mixed SRDECODE( mixed )
Decrypts a string that was encrypted with
sr_encode().
This function calls
sr_decode() on string and returns the decrypted data.
Parameters
string: the data to decode.
Return Values
Plain original data.
Notes
Everything within parenthesis is decoded.
See also:
SRENCODE() and
sr_encode().
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 13
SQL Command
3.3.2 Decrypt Data: SRDECODEN
SRDECODEN -- Decode a number
Description
number SRDECODEN( number n [, int password])
This function calls
sr_decode_number() on number.
Parameters
n: number to decode.
password: Password used to encode the number.
Return Values
Decodes the original number.
Notes
Everything within parenthesis is decoded.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 14
SQL Command
3.3.3 Decrypt data: SRUNKEY
SRUNKEY -- Recover string that was encoded with SRKEY
Description
string SRUNKEY( string )
This function calls
sr_decode() on string.
Only works across multiple script executions if
you have previously ran sr_name_update().
Parameters
string: the encoded value to decode.
Return Values
Plain original data.
Notes
Everything within parenthesis is decoded.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 15
Sqlencoder Class - PHP 5
Sqlencoder Class - PHP 5
4. Object
4.1 Information
Only available in the PHP 5 version
sqlencoder -- Class Object
Description
mixed sqlencoder(int default_encoding_mode=SR_SE_AUTO) ()
All API functions can be accessed either as functions or as class methods
via the sqlencoder class.
To use class methods: remove the 'sr_' portion of the name from
the API functions.
For example 'sr_decode' is an API function.
'decode' is the sqlencoder class method.
Example usage:
/* CLASS OBJECT USAGE */
require_once('sunsetrlib/sqlencoder/sqlencoder5.php');
$sobj = new sqlencoder();
$data = $sobj->encode('Some secret information');
echo 'Decoded info is: '.$sobj->decode($data);
----------- different script ----
/* NON-CLASS USAGE */
require_once('sunsetrlib/sqlencoder/sqlencoder.php');
$data = sr_encode('Some secret information');
echo 'Decoded info is: '.sr_decode($data);
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 16
Core API - PHP 4 and PHP 5
Core API - PHP 4 and PHP 5
5. Function
5.1 Information
5.1.1 General Information: sr_info
sr_info -- Get Summary Information about an encoded field.
Description
array sr_info (mixed &$data)
This function returns an array containing properties describing data.
Parameters
Data: Encoded.
Return Values
| Array Property | Meaning |
| key | Set to true if this is a name. |
| encrypted | Set to true if encryption was used. |
| compressed | Set to true if data was compressed. |
| base64 | Set to true if base 64 encoding was used. |
| recovery | Set to true if in recovery mode. see sr_load_hardware_keys() |
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 17
Core API - PHP 4 and PHP 5
5.1.2 Detect Error: sr_data_errors
sr_data_errors -- Detect Error Status
Description
mixed sr_data_errors ()
Reports and clears
the error fstatus.
Decryption functions will set an error flag if the data being decoded did not past integrity checks.
Encrypt functions will set an error flag if an error occured during
the encoding process.
Return Values
| Value | Meaning |
| -1 | Function not available. |
| 0 | No error. |
| Non-zero | Error(s) occured. |
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 18
Core API - PHP 4 and PHP 5
5.1.3 Detect Error: sr_data_valid
sr_data_valid -- Detect Encryption status
Description
int sr_data_valid(mixed &$data) ()
Tell whether data is corrupt or has been modified.
Parameters
Data: Encoded.
Return Values
| Value | Meaning |
| -1 | No information available |
| 0 | Data is corrupt or modified. |
| 1 | Data is valid. |
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 19
Core API - PHP 4 and PHP 5
5.1.4 Test SQL Encoder Command Parser: sr_parse_test
sr_parse_test -- Tests the interpretation SQL Encoder Commands embedded in a SQL query.
Description
string sr_parse_test (string query)
This command returns the result of interpretation with test strings substitutded for encoded/decoded data.
Nested SQL Encoder commands are not supported so the result of 'SRKEY(SRKEY(x))' will not be what you expect.
Parameters
query: string to be parsed.
Return Values
Result of parsing with these strings replacing SQL Encoder Commands where appropriate:
SRKEY and SRUNKEY: #ENCODED_NAME#,#DECODED_NAME#
SRENCODE and SRDECODE: #ENCODED_VAL#,#DECODED_VAL#
SRENCODEN and SRDECODENKEY: #ENCODED_NUM#
SRDECODEN: #DECODED_NUM#
Notes
This function is
for test purposes only. You cannot use it to encode or decode data.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 20
Core API - PHP 4 and PHP 5
5.2 Encoding
5.2.1 Encrypt Data: sr_encode
sr_encode -- Encrypt data
Description
mixed sr_encode ( mixed &$data [, int $mode=SR_SE_AUTO])
This function returns the data in encrypted form.
Parameters
| Mode | Meaning |
| SR_SE_AUTO | Automatically determine the best mode. |
| SR_SE_COMPRESS | Compress. |
| SR_SE_BASE64 | Store as binary safe base 64 output. |
| SR_SE_BOTH | SR_SE_COMPRESS + SR_SE_BASE64 |
| SR_SE_RAW | Binary |
Return Values
Encrypted data.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 21
Core API - PHP 4 and PHP 5
5.2.2 Encrypt Data: sr_encode_number
sr_encode_number -- Encrypt data
Description
number sr_encode_number ( number $data [, int password] )
This function returns data in encrypted form.
Parameters
Data: data to be encoded.
Password: A positive whole number used to further encrypt data.
Return Values
Returns a number.
Notes
The maximum value depends on the system. To be safe, assume that you are
under the 32 bit system limitation: -2147483648 to 2147483647. If using a password, the range may be reduced (the larger the password the smaller the useable range)
Do not use more than six decimal places in the unencoded data.
You may need up to 10 decimal places to store the encoded value for large numbers.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 22
Core API - PHP 4 and PHP 5
5.2.3 Onfuscate Data: sr_encode_number_key
sr_encode_number_key -- Convert to an encoded number
Description
number sr_encode_number_key ( number data [, int password] )
This function returns a unique value that represents the original data. There is a 1:1 mapping between values passed
to the function and the values returned. This makes it useful in situations where you wish to reference a foreign key.
Parameters
Data: data to be encoded.
Password: A positive number used to further encrypt data.
Return Values
Encrypted data.
Notes
WARNING: you should not encode numbers with this function and then
write them to the same row in the database where the plain version of the number is present
or you will be revealing to an attacker information on how to decode numbers encoded with this
function.
The maximum value depends on the system. To be safe, assume that you are
under the 32 bit system limitation: -2147483648 to 2147483647. If using a password, the range may be reduced (the larger the password the smaller the useable range)
Do not use more than six decimal places in the unencoded data.
You may need up to 10 decimal places to store the encoded value for large numbers.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 23
Core API - PHP 4 and PHP 5
5.2.4 Encrypt Data: sr_encode_q
sr_encode -- Encrypt data
Description
mixed sr_encode_q ( mixed $data )
This function returns the data in encrypted form. It calls
sr_encode() with mode set to SR_SE_AUTO.
Parameters
Data: data to be encoded.
Return Values
Encrypted data.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 24
Core API - PHP 4 and PHP 5
5.2.5 Field Name: sr_fieldname
sr_fieldname -- Convert to a short encoded value
Description
mixed sr_fieldname (mixed $string)
This function returns an encoded representing the string.
Parameters
String should be a word like 'dentist' or 'full_name'
Return Values
The encoded version of the string
Notes
You can also use the function
sr_fieldname_q. It returns the encoded result
encapsulated with quote marks (').
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 25
Core API - PHP 4 and PHP 5
5.2.6 Table Name: sr_tablename
sr_tablename -- Convert to short encoded value
Description
mixed sr_tablename (mixed $string)
This is an alias of
sr_fieldname().
Parameters
String should be a word like 'reports' or 'mytable'
Return Values
The encoded the string
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 26
Core API - PHP 4 and PHP 5
5.3 Decoding
5.3.1 Decrypt Data: sr_decode
sr_decode -- Convert encoded data to original data.
Description
mixed sr_decode (mixed &$data_in)
This function returns the original unecoded version of data.
Return Values
The original plain data.
Notes
Table names and field names can only be decoded if you have used the
sr_name_update() function during the lifetime of the current recovery file.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 27
Core API - PHP 4 and PHP 5
5.3.2 Decrypt Data: sr_decode_number
sr_decode_number -- Convert encoded data to original data
Description
number sr_decode_number (number $data_in [, int $password])
This function returns the original unecoded version of data.
Return Values
The original plain data.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 28
Core API - PHP 4 and PHP 5
5.3.3 Reveal secret field name: sr_fieldname_decode
sr_fieldname_decode
Description
mixed sr_fieldname_decode (string $str)
This function returns the originally encoded string.
Only works across multiple script executions if
you have previously ran sr_name_update().
Parameters
Str: the string.
Return Values
Returns decoded data.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 29
Core API - PHP 4 and PHP 5
5.3.4 Reveal secret table name: sr_tablename_decode
sr_tablename_decode
Description
mixed sr_tablename_decode (string $str)
This function returns the original string.
Only works across multiple script executions if
you have previously ran sr_name_update().
Parameters
Str: the string.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 30
Core API - PHP 4 and PHP 5
5.4 MySQL Wrappers
5.4.1 Fetch Array: sr_sql_fetch_array
sr_sql_fetch_array
Description
array sr_sql_fetch_array ( resource $result [, int $result_type= MYSQL_BOTH ] )
This function calls mysql_fetch_array() and returns decoded fields as needed.
Note that numeric field types are not decoded by this function.
Parameters
result: The resource that is being evaluated. It comes from a call to mysql_query().
result_type: The type of array that is to be fetched.
Return Values
Returns an array of strings that corresponds to the fetched row, or FALSE if there are no more rows. The type of returned array depends on how result_type is defined.
See PHP documentation for further information about mysql_fetch_array();
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 31
Core API - PHP 4 and PHP 5
5.4.2 Fetch Assoc: sr_sql_fetch_assoc
sr_sql_fetch_assoc
Description
mixed sr_fetch_assoc (resource $result)
Calls mysql_fetch_assoc() and decodes any information present in the result.
Note that numeric field types are not decoded by this function.
Parameters
result: The resource that is being evaluated. It comes from a call to mysql_query().
Return Values
Returns an associative array of strings that corresponds to the fetched row, or FALSE if there are no more rows.
See PHP documentation for further information about mysql_fetch_assoc();
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 32
Core API - PHP 4 and PHP 5
5.4.3 Query: sr_sql_query
sr_sql_query
Description
resource sr_sql_query ( string $query [, resource $link_identifier ] )
Uses sr_parse() to interpret any SQL Encoder commands present in the query and then passes the result as a new query to
mysql_query() which sends the query to the currently active database associated with link_identifier.
Nested SQL Encoder commands are not supported so the result of 'SRKEY(SRKEY(x))' will not be what you expect.
WARNING: It is highly recommended that you use sr_addslashes() on any user supplied input, prior to
passing that input to this function.
Parameters
The result resource that is being evaluated. This result comes from a call to mysql_query().
Return Values
Same as mysql_query().
For queries returning a result set, mysql_query() returns a resource on success, or FALSE on error.
For other type of SQL statements it returns TRUE on success or FALSE on error.
Will return FALSE if the user does not have permission to access the table(s) referenced by the query.
See PHP documentation for further information about mysql_query();
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 33
Core API - PHP 4 and PHP 5
5.4.4 Unbuffered Query: sr_sql_unbuffered_query
sr_sql_unbuffered_query
Description
resource mysql_unbuffered_query ( string $query [, resource $link_identifier ] )
Interprets any SQL Encoder commands present in query and then passes the result to
mysql_unbuffered_query() which sends a SQL query query to MySQL, without fetching and buffering the result rows automatically.
WARNING: It is highly recommended that you use sr_addslashes() on any user supplied input, prior to
passing that input to this function.
Parameters
The result resource that is being evaluated. This result comes from a call to mysql_query().
Return Values
Returns an associative array of strings that corresponds to the fetched row, or FALSE if there are no more rows.
See PHP documentation for further information about mysql_unbuffered_query();
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 34
Core API - PHP 4 and PHP 5
5.5 File Operations
5.5.1 Exit Recovery Mode: sr_close_hardware_keys
sr_close_hardware_keys -- Exit Recovery Mode.
Description
mixed sr_close_hardware_keys ()
Exits the current Recovery Mode.
Return Values
| Value | Meaning |
| true | Exited Recovery Mode |
| false | Was not in Recovery Mode. Nothing done. |
Notes
Normally you do not have to call this function but it is useful if you wish to switch from recovery mode to normal mode in
the same process. This function is effectively called whenever your process starts and ends.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 35
Core API - PHP 4 and PHP 5
5.5.2 Access a recovery file: sr_load_hardware_keys
sr_load_hardware_keys -- Load a recovery file.
Description
mixed sr_load_hardware_keys (string filename, string password, string product_key)
This function reads the recovery file and causes the secret keys within it to be used by the system.
Parameters
filename: name of the file to load. It must end in '.srd'.
password: a secret string of 8 characters or more.
product_key: the product key issued to you with for your license of the software that created the recovery file.
Never store passwords or product keys in your software or on your site for maximum security.
Return Values
| Value | Meaning |
| -3 | File name must end in '.srd'. |
| -2 | File has bad format. |
| -1 | Already in recovery mode. |
| 0 | Success. |
| 1 | Could not access file or bad password. |
| 9 | Trial Edition |
Notes
Normally you do not have to call this function but it is useful for data recovery.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 36
Core API - PHP 4 and PHP 5
5.5.3 Add to name map: sr_flush_map
sr_flush_map -- add name(s) to the name map if needed.
Description
mixed sr_flush_map ()
This function writes name data to the name map only if needed. If you are calling SQL Encoder as a
class, this function is automatically called when the process ends normally or when you destroy the class object.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 37
Core API - PHP 4 and PHP 5
5.5.4 Add to name map: sr_name_update
sr_name_update -- add name(s) to the name table.
Description
mixed sr_name_update (string $query)
This function interprets name related SQL Encoder instructions found in the query and adds
new names found to the name table in the recovery file if needed.
Parameters
query: Key related SQL Encoder commands. Function expects the first word of the query to be
one of : ALTER, CREATE or RENAME.
Return Values
On success, the message returned is 'Keys updated: ', followed by the interpreted query.
Otherwise an error message.
Script will
die with an error message if the first word in query is not one of:
ALTER, CREATE or RENAME.
Notes
Use of this function is purely optional. Using this function when you do ALTER , CREATE or RENAME operations on encoded table names and field
names will allow you to store the information about the plain text names in the recovery file which
means that the recovery file alone contains all of the information you need to reconstruct an encoded
database. Otherwise the original plain text names would only be stored in your program software.
Use of this function also enables the decoding of string values with:
sr_fieldname_decode and
sr_tablename_decode.
Names are also added to the map when you explicitly call
sr_encode_fieldname or
sr_encode_tablename
It is not possible to remove names from the name map.
For information about recovering/moving databases see
sr_load_hardware_keys().
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 38
Core API - PHP 4 and PHP 5
5.5.5 Create a recovery file: sr_save_hardware_keys
sr_save_hardware_keys -- Create or update recovery file
Description
mixed sr_save_hardware_keys (string filename, string password)
This function writes to the existing recovery file or creates a new one.
Parameters
filename: the name to use for the file. It must end in '.srd'
password: a secret string of 8 characters or more.
Return Values
| Value | Meaning |
| -3 | File name must end in '.srd'. |
| -2 | Password must be 8 or more characters long. |
| -1 | Already in recovery mode. |
| 0 | Success. |
| 1 | Could not open file. |
| 2 | Corrupt file. |
| 3 | Updated IonCube Loader is required. |
| 5 | Write error. |
| 9 | Not authorized or Trial Edition |
Notes
This function should be called at least once during the lifetime of your database,
otherwise you will be unable to recover your data from a different system or
installation.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 39
Core API - PHP 4 and PHP 5
5.6 Data
5.6.1 File Description
SQL Encoder expects a subdirectory called 'data'.
The data directory may contain encrypted files:
* map.srm: contains information about names created
with sr_name_update().
* Files ending in '.srd', contain encryption keys needed to decrypt your data. These files can only be
read or written to via the functions:
sr_load_hardware_keys() and
sr_save_hardware_keys().
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 40
Core API - PHP 4 and PHP 5
5.6.2 Migration & Disaster Recovery
SQL Encoder is designed so that the data you encode with it cannot be read if the software has been moved, modified or re-installed.
This means that even if someone has an exact copy of your version of SQL Encoder,
and your license file they would still not be able to access your data.
But you may run into a situation where you need to access your data from a different
location and the Data Recovery Process allows this.
IMPORTANT
You must create a recovery file before you need to move data.
You will
not be able to recover your encrypted data if
you don't create a recovery file
before
moving, or deleting your SQL Encoder software.
Creating a Recovery File
Use the
sr_save_hardware_keys() function to create a recovery file.
The file will contain all of the information SQL Encoder needs to unlock your data from a different copy of SQL Encoder.
The password must match the password used to create the recovery file.
The product key must match the key associated with
the license.txt file you purchased.
SQL Encoder goes into Recovery Mode when a file is loaded.
Secure Your Keys
For maximum security you should
never store your recovery password(s) or product key on the same
server where SQL Encoder runs.
Loading a Recovery File
Use the
sr_load_hardware_keys() function to
access a recovery file. You need the password used
by the creator of the recovery file plus the product key
for the copy of SQL Encoder that was used to create the
recovery file.
Recovery Mode
In Recovery Mode, SQL Encoder uses two groups of encryption keys: the old group for decoding data and the current group
for encoding data. This means that you can read your old data in
while writing out data using the new keys.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 41
Core API - PHP 4 and PHP 5
5.7 Miscellaneous
5.7.1 Make user supplied input safe: sr_addslashes
sr_addslashes -- Safe user supplied input.
Description
string sr_addslashes (string input)
This function escapes SQL Encoder Commands and other special characters present in input so that a user cannot inject SQL Encoder commands.
Parameters
input: user supplied text.
Return Values
A string with special things escaped per PHP's addslashes documentation.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 42
Core API - PHP 4 and PHP 5
5.7.2 Unescape string: sr_stripslashes
sr_stripslashes -- Removes escapes added by
sr_stripslashes()
Description
string sr_stripslashes (string input)
This function unescapes SQL Encoder Commands and other special characters present in input.
Return Values
The original string previously passed to
sr_addslashes().
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 43
Core API - PHP 4 and PHP 5
5.7.3 Version Information: sr_version
sr_version -- Report product information.
Description
sr_version ()
This function echoes output containing information about the licensed product.
You can get extended information by calling via the web: add '?version=' to the web address of your
copy of SQL Encoder.
Example
SQL Encoder 1.3 Basic
(C)2009 by Sunset Rainbow, LLC. All Rights Reserved.
July 2009 r10/09 - Sunset Rainbow's SQL Encoder Guide - Page 44
Web GUI
Web GUI
* Server & SQL Encoder Viewer
Overview
The Web GUI is a Firefox add-on
that works with the GUI Edition of SQL Encoder server.
You can use it with web based database applications like phpMyAdmin.
Note: Encrypted data on a web page must be within table tags for
the Web GUI to recognize it.
Adding a Domain
From within Firefox:
Open the sidebar with Tools > SQL Encoder Viewer. Click on 'Settings'.
Set Domain Name to the domain name you have a license for.
Set Product Key to the product key associated with your license.
Clicking on the SQL Encoder icon will translate the current web pages.
The setting will only be saved if you Translate or Parse something with it.
Translate a Web Page
Click on the SQL Encoder Viewer icon or the 'Translate' button in the sidebar while viewing a web page.
Non numeric items that were encoded are decoded. To decode numbers see Parse Section.
Parse Statements
With the SQL Encoder Viewer Sidebar open: Type or paste command statements into the SQL box.
Click 'Parse' to send the statements to the SQL Encoder server named in 'Settings'.
Parsed statements reveal to you what SQL you should send to your Database SQL Server.
They can also be used to decode numbers.
If you are authorized to access the server the response will appear in the box below the
'Parse' button. Normally the statement is sent to the eqivalent of sr_parse() but if
the keywords 'ALTER', 'CREATE' or 'ALIAS' appear anywhere in your statement
and any SRKEY() names need updating the
statement will be sent to sr_name_update() so to get the decoded
contents of statements with new names you may have to click parse twice.
Working with Multiple Domains & Deleting Domains
When you add a new domain the secure settings for
previously added domains are retained.
Delete or edit multiple domains by going to
to Options > Security
> Saved Password.
Note: when you use 'Settings' to set a password to blank the password will
not be changed.
To delete a password you must use the options menu or disable the password
via SQL Encoder Viewer settings by changing it to '1'.
Deny GUI Service
Copy the
.htaccess file in the data directory to the sqlencoder directory.
This disables all web access to SQL Encoder.
Note: Requires your web server to support .htaccess