PIP-0027: updated with community suggestions and further R&D

PIP/PIP-0027.md

@@ -35,14 +35,13 @@ An Extended PASA is defined by the below EBNF grammar:
     ExtendedAddress    = ( PublicPayload | ReceiverEncPayload | SenderEncPayload | PasswordEncPayload ), [ ":", PayloadChecksum ] ;
     PublicPayload      = "[", Payload, "]" ;
     ReceiverEncPayload = "(", Payload, ")" ;
-    SenderEncPayload   = "{", Payload, "}" ;
-    PasswordEncPayload = "<", Payload, ":", Password, ">" ;
-    Payload            = [ Pascal64String | HexString | Base58String ] ;      (* allows empty payload *)
+    SenderEncPayload   = "<", Payload, ">" ;
+    PasswordEncPayload = "{", Payload, ":", Password, "}" ;
+    Payload            = [ """, SafeAnsiString, """ | HexString | Base58String ] ;      (* allows empty payload *)
     PayloadChecksum    = HexDigit, HexDigit, HexDigit, HexDigit
-    Password           = HexString                                             (* force passwords to be specified in hex *)
-    Pascal64String     = Pascal64StartChar, { Pascal64Char } ;
-    Pascal64StartChar  ??= TODO
-    Pascal64Char       ??= TODO
+    Password           = SafeAnsiString
+    SafeAnsiString     = Pascal64StartChar, { Pascal64Char } ;
+    SafeAnsiChar       = (" " | "!" | EscapeChar """ | "#" | "$" | "%" | "&" | "'" | "(" | ")" | "*" | "+" | "," | "-" | "." | "/" | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | ":" | ";" | "<" | "=" | ">" | "?" | "@" | "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" | "[" | EscapeChar "\" | "]" | "^" | "_" | "`" | "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "{" | "|" | EscapeChar "}" | "~") ;
     HexString          = "0", "x", HexByte { HexByte } ;
     HexByte            = HexDigit, HexDigit
     HexDigit           = ( Digit | "a" | "b" | "c" | "d" | "e" | "f" ) ;       (* no uppercase hex allowed *)
@@ -52,7 +51,7 @@ An Extended PASA is defined by the below EBNF grammar:
     Base58LowerChar    = ( "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z" ) ; (* missing l *)
     Digit              = ( "0" | NaturalDigit ) ;
     NaturalDigit       = ( "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ) ;
-
+    EscapeChar         = "\"
 
 | Rule               | Explanation                                                                                                   |
 | -----------------: | :------------------------------------------------------------------------------------------------------------ |
@@ -61,65 +60,79 @@ An Extended PASA is defined by the below EBNF grammar:
 | Checksum           | This is the standard layer-1 address checksum                                                                 |
 | ExtendedAddress    | The optional extra text that forms part of layer-2 address (payload specification)                            |
 | PublicPayload      | A payload which is not encrypted and publically visible                                                       |
-| ReceiverEncPayload | A payload which is ICIES encrypted using receivers public key (the PASA portion specifies receiver)           |
-| SenderEncPayload   | A payload which is ICIES encrypted using the senders public key (only sender can decrypt EPASA)               |
+| ReceiverEncPayload | A payload which is ECIES encrypted using receivers public key (the PASA portion specifies receiver)           |
+| SenderEncPayload   | A payload which is ECIES encrypted using the senders public key (only sender can decrypt EPASA)               |
 | PasswordEncPayload | A payload which is AES256 encrypted using the specified password                                              |
 | Payload            | The actual payload data, specified it an well-defined encoding                                                |
 | PayloadChecksum    | An UINT16 specified by two hexbytes (4 hexdigits) that denotes a checksum of payload, used to ensure payload consistency (prevents typo/copy-paste errors)  |
-| Password           | The password used in PasswordEndPayload. Must be specified as a hexadecimal string                            |
-| Pascal64String     | A Pascal64-encoded string. This encoding also used for specifying Account Names.                              |
+| Password           | The password used in PasswordEndPayload. Must be specified as a safe ANSI string (chars 32..126)              |
 | Base58String       | A Base58-encoded string. This is used for specifying public keys, and hashes of public keys                   |
 | HexString          | A hexadecimal-encoded string prefixed with a 0x. Every byte specified by two hexdigits, lower-case            |
 
-#### Payload Checksumming
+#### Validation Rules
+
+#### PASA Checksum
+
+TODO: add existing PASA checksum rule
+
+#### Payload Checksum
 
 In order to avoid data entry errors, the payload portion is **optionally** checksummed. The payload checksum is calculated as follows:
 
 ```
-    PayloadChecksum = ToHexString ( CastToUINT16( MurMur3( PayloadEncType ++ Payload ) MOD 65536 ) )
-
-    PayloadEncType  = "0" for PublicPayload
-                    = "1" for ReceiverEncPayload
-                    = "2" for SenderEncPayload
-                    = "3" for PasswordEncPayload
-       
+    PayloadChecksum = ToHexStringLE ( CastToUINT16( MurMur3( ToAsciiBytes ( PayloadEncType ++ Payload ) ) MOD 65536 ) )
+
+    where
+       PayloadEncType  = "0" for PublicPayload
+                       = "1" for ReceiverEncPayload
+                       = "2" for SenderEncPayload
+                       = "3" for PasswordEncPayload
+       ToAsciiBytes    = converts ASCII string argument into raw byte form, character by character (no endianness concerns here)                
+       MurMur3         = performs 32bit MurMur3 hash of the byte array argument                
+       CastToUINT16    = casts the integer argument into to a 16bit unsigned integer (should never overflow due to modulo 65536)
+       ToHexStringLE   = converts the 16bit unsigned integer argument into 4 hexadecimal characters in little-endian
 ```
 
-The MurMur3 used here is the 32bit version. The hash digest is **Payload** portion of the E-PASA in it's ASCII form, not it's binary form. The Checksum will always be 4 hexadecimal digits and numerically ranged to 0 - 65535.
+#### Payload Lengths
 
-## Examples
+The following validation rules must be applied to Payload lends
 
-### Example 1 
+- For public unecrypted ASCII payloads the string length must be less than or equal to 255 
+- For ECIES encrypted ASCII payloads the string length must be less than or equal to ???
+- For AES encrypted ASCII payloads the string length must be less than or equal to ???
+- For public unecrypted Hexadecimal or Base58 payloads the string length must be less than or equal to 510
+- For ECIES encrypted Hexadecimal or Base58 payloads the string length must be less than or equal to ???
+- For AES encrypted Hexadecimal or Base58 payloads the string length must be less than or equal to ???
 
-```
-123456-77[0x12ab3f]:10cb 
-```
-
-- Receiver address is '123456-77'
-- Payload is the hexadecimal string 0x12ab3f
-- Payload is public (not encrypted)
-- Payload checksum is 10cb
+## E-PASA Examples
 
-**Note**
- - To encrypt using senders key, address would be ```123456-77{0x12ab3f}:19de```.
- - To encrypt using recipients key, address would be ```123456-77(0x12ab3f):bf91```.
- - To encrypt using password "Alpha$", address would be ```123456-77<0x12ab3f:0x416c70686124>:dd32``` noting password converted into hex encoding.
+### With ASCII payloads 
 
- 
+| Rule                                      | Explanation                                                                                                     |
+| ----------------------------------------: | :-------------------------------------------------------------------------------------------------------------- |
+| 123456-77                                 | Backwards compatible to PASA 123456-77 This is a layer-2 address, fully backwards compatible as Layer-1 address |
+| 123456-77["Hello World!"]                 | Public ASCII payload "Hello World!", no checksum protection                                                     |
+| 123456-77["Hello World!"]:10cb            | Same but checksum protected                                                                                     |
+| 123456-77("Hello World!"):7ba2            | ECIES encrypted payload using **recipient's public key** and checksum protected                                 |
+| 123456-77<"Hello World!">:b51f            | ECIES encrypted payload using **senders public key** and checksum protected                                     |
+| 123456-77{"Hello World!":!43lp|-d|a%@#!}  | AES256 encrypted payload using password **!43lp|-d|a%@#!**                                                      |
+TODO: add escaped password examples
 
-### Example 2: 
+**NOTE**: Text payload and passwords are restricted to ANSI charset subset 32..126;
 
-```
-77-44["[email protected]"]:1234 
-```
+### With hexadecimal payloads 
 
-- Recipient address is '77-44'
-- Payload is the Pascal64 string "[email protected]"
-- Payload is not encrypted (public)
-- Payload checksum is "1234"
+| Rule                                      | Explanation                                                                                                     |
+| ----------------------------------------: | :-------------------------------------------------------------------------------------------------------------- |
+| 77-44                                     | Backwards compatible to PASA 123456-77 This is a layer-2 address, fully backwards compatible as Layer-1 address |
+| 77-44[0x416c70686124]                     | Public hexadecimal payload 0x123abc, no checksum protection                                                     |
+| 77-44[0x416c70686124]:10cb                | Same but checksum protected                                                                                     |
+| 77-44(0x416c70686124):7ba2                | ECIES encrypted payload using **recipient's public key** and checksum protected                                 |
+| 77-44<0x416c70686124>:b51f                | ECIES encrypted payload using Recipient key and  checksum protected                                             |
+| 123456-77{0x416c70686124:!43lp|-d|a%@#!}  | AES256 encrypted payload using password **!43lp|-d|a%@#!**                                                      |
+TODO: add escaped password examples
 
-**NOTE**
-- By using recipients key, ```77-44("[email protected]"):5bd8``` exchanges could use such addresses to accept users deposits easily, via a single address per user.
+TODO: add Base58 examples
 
 ## Rationale