Secure your communication
=========================
include::revision.txt[]

WARNING: This chapter is only for reader that use the GNTP adapter. Even if UDP is 
link:http://growl.info/documentation/developer/protocol.php[binary format protocol], 
it shouldn't be considered as secure. 

GNTP is a MIME like format, contents are sent as readable plain text.
You should think to use either :

* a HTTPS secure channel
* encrypt your data on a basic HTTP channel

We will see now, how to encrypt your data and what formats are supported.

The authorization of messages is accomplished by passing key information that proves 
that the sending application knows a shared secret with the notification system, 
namely a password. Users that want to authorize applications must share with them 
a password that will be used for both authorization and encryption.

NOTE: By default, authorization is not required for requests orginating on the local machine.

[[HASHALGO]]
.The supported hashing algorithms
[grid="rows",format="csv",width="100%"]
[options="header",cols="5<s,10<"]
|===========================
Hash,   Features
MD5,    "128-bit, 16 byte, 32 character length when hex encoded"
SHA1,   "160-bit, 20 byte, 40 character length when hex encoded"
SHA256, "256-bit, 32 byte, 64 character length when hex encoded"
SHA512, "512-bit, 64 byte, 128 character length when hex encoded"
|===========================

[[CRYPTALGO,]]
.The supported encryption algorithms
[grid="rows",format="csv",width="100%"]
[options="header",cols="5<s,10<"]
|===========================
Hash, Features
NONE, "No encryption; messages are sent in plain text"
AES,  "key length: 24 bytes (192 bit), block size: 16 byte (128 bit), iv size: 16 byte (128 bit)"
DES,  "key length: 8 bytes (64 bit), block size: 8 byte (64 bit), iv size: 8 byte (64 bit)"
3DES, "key length: 24 bytes (192 bit), block size: 8 byte (64 bit), iv size: 8 byte (64 bit)"
|===========================

NOTE: All encryption algorithms should use a block mode of CBC (Cipher Block Chaining) and PKCS5 (PKCS7) padding.

IMPORTANT: It is important to keep in mind that some encryption algorithms 
require keys that are longer than can be generated by some hashing algorithms. 
As such, not all hash/encryption combinations are valid 
(ex: MD5 hash produces a 16 byte result, but AES encryption requires a 24-byte key).

.Hash and Encryption algorithms compatibilities
[grid="rows",format="csv",width="100%"]
[options="header",cols="5,10"]
|===========================
Encryption, Hash
AES,  "SHA256, SHA512"
DES,  "MD5, SHA1, SHA256, SHA512"
3DES, "SHA256, SHA512"
|===========================

To encrypt your data, its very easy. 
You have just to specify in *options* of xref:C1M1[Net_Growl::singleton] method :

* password hash algorithm, see xref:HASHALGO[the supported hashing algorithms].
* encryption algorithm, see xref:CRYPTALGO[the supported encryption algorithms].

.encrypted messages with AES/SHA256
==========================
[source,php]
----
<?php
require_once 'Net/Growl/Autoload.php';

$notifications = array(
    'GROWL_NOTIFY_PHPERROR'
);
$appName  = 'PHP App Example using GNTP/encrypt AES';
$password = 'mamasam';

$app = new Net_Growl_Application(
    $appName,
    $notifications, 
    $password
);
$options = array(
    'host'     => '127.0.0.1',
    'protocol' => 'tcp', 
    'port'     => Net_Growl::GNTP_PORT,
    'timeout'  => 10,
    'encryptionAlgorithm'   => 'AES',
    'passwordHashAlgorithm' => 'SHA256',
);

try {
    $growl = Net_Growl::singleton($app, null, null, $options);
    $growl->register();

    $title       = 'Welcome in PHP/GNTP world';
    $description = "New GNTP protocol support 3 encryption algorithms ! \n"
                 . "DES, 3DES, AES with 4 hash algorithm \n"
                 . "MD5, SHA1, SHA256, SHA512.";
    $options     = array(
        'sticky' => true,
    );
    $growl->notify($name, $title, $description, $options);

} catch (Net_Growl_Exception $e) {
    echo 'Growl exception: ' . $e->getMessage() . PHP_EOL;
}
?>
----
==========================
