Permission Keys in five easy steps Adrian McElligott

Resources The Key Custodian API Reference Permission Keys Paper Permission Keys FAQ Sample Outlook plug in source code Sample SMTP MTA source code

Permission Keys System Components Client Side Outbound Message Key Insertion Function Spam Folder Monitoring Module Server Side Key Issuing Facility –AJAX Web Service –UI for manual issuing –Key Custodian API GetKey IsValidKey InvalidateKey Access authentication Key Generation Key Storage & Retrieval Reporting

Overview The requirements of a GKC client are to provide the following facilities and functions: 1.Authentication - uses a token delivered via . 2.Initialization - retrieving client preferences from the GKC. 3.Intercept all out going and insert a permission key in to all instances of the protected user's address. 4.Monitor the Spam folder, and recover any messages that contain a valid key. 5.Invalidate Compromised Keys Note: All communications must be secure (HTTPS / SSL). Implement the Key Custodian APIs should be in compliance with the Licensing Requirements as specified in the attached document.

The Key Custodian APIs Filters call Authenticate(...) GetKey(...) IsValidKey(...) InvalidateKey(...) GetUserPreferences(...) Anonymous Browsers call GetMailToKey(...) Note: Unless specified otherwise, the term " address" refers to an address as defined by "RFC Address Specification" and should preferably be provided as it would typically appear in the message headers and therefore include the dispaly name, if available. In accordance with RFC 2822, to avoid confusion the term "addr- spec address" is used to refer to the bare SMTP form of the address. ie.

Spam Folder Monitoring Function For each message that is placed in to the Spam folder: Check that the message has not been previously processed. Retrieve the Originator's Address. Retrieve any keyed instances of the protected user's address, and check the validity of the key via the GKC IsValidKey() API. (continued): If the Key is valid, then move the message to the inbox – bump a counter. Optionally, record that the message has been processes, and that it has been recovered. If operating in free mode, then alert the user via a message box or dialog.

Outbound Message Key Insertion Function For each outgoing message: Obtain the Recipient's Address Obtain a 'Permission Key' from the global key custodian, via the GetKey API. Insert the envelop key into the message envelop by replacing instances of the protected users address with the provided "envelop " keyed version. For each outgoing message (continued): Insert the headers key into the message headers by replacing instances of the protected users address with the provided "headers" keyed version. If opperating in free mode, then insert GKC promotional footer.

On Compromised Key Function For each message that is placed in to the Spam folder that has been previously recovered, or where the user has specifically indicated that the key should be invalidated: Retrieve the Originator's Address. Retrieve any keyed instances of the protected user's address, and call the GKC InvalidateKey() API for each.

Authentication What to use it for: New Account Instance Authentication Account Instance Re- authentication To acknowledge the receipt of GKC Tokens Description Called to initiate the dispatching of, and to acknowledge the receipt of GKC Tokens. When to use it: Upon new installation / activation of Permission Key facility In the event that the current GKC token is rejected by the GKC Upon the receipt of a GKC token during the filter authentication process Note: Please see "New User Instance Account Initialization" for a description of the authentication process.

New User Instance Account Initialization Process is always initiated by the filter. The filter calls Authenticate() passing in a filter generated random 10 digit alpha-numeric "filter token", which the filter stores for further reference. The GKC sends two messages to the protected user's address: 1.a probe message to test for the existence of plus addressing support within the protected user's system, and 2.a message containing the GKC authentication token. Continued…

New User Account Initialization con't. The filter monitors incoming messages for two responses from the GKC. Responses are identified by the originators address and authenticated by the presence of the original "filter token" in the subject of the message. The structure of the subject field is: "... Token is: : " The filter recovers the GKC's token from the subject field of each GKC message, and 1.calls Authenticate() for each recovered GKC token - this time including the GKC's token in the request. 2.permanently records the first 10 digits of the GKC's token for inclusion in all further calls to the GKC. Continued…

New User Account Initialization con't. The first 10 digits of the GKC's token will be the same for each response message. The Eleventh digit of the GKC's token is used to identify tagged addressing probes. GKC messages may be optionally deleted by the filter. All messages from the GKC contain both the original "filter token" and a GKC token. Filters only need to monitor for and respond to GKC messages during the account authentication process. Notes

The Key Custodian API Reference

The Key Custodian APIs Filters call Authenticate(...) GetKey(...) IsValidKey(...) InvalidateKey(...) GetUserPreferences(...) Anonymous Browsers call GetMailToKey(...) Note: Unless specified otherwise, the term " address" refers to an address as defined by "RFC Address Specification" and should preferably be provided as it would typically appear in the message headers and therefore include the display name, if available. In accordance with RFC 2822, to avoid confusion the term "addr- spec address" is used to refer to the bare SMTP form of the address. ie.

GetKey() Parameters o The protected user's address Recipients o Coma delimited list of the recipient addresses. Filter Statistics (optional) o MsgsReceived o MsgsRecovered o TotalSpam GKC Token Format o Either xml or json Returns A keyed instance of the protected user's address in either xml or json Example: { "key": { "addrspec": " ": "\"John Smith 12345\" " },"success":true} Description Called by the filter for each outgoing message to obtain a key

IsValidKey() Parameters o The protected user's address Key o A key encoded address retrieved from any part of the message Senders (optional) o Coma delimited list of address of the message's senders. GKC Token Format o Either xml or json Returns Key properties in either xml or json Example: { "key": { "isvalidkey": "true", "issuedto": "\"Joe\" ", "issueddate":" ", "expires":" ", "issuedby":"SMTP Outgoing Insertion" },"success":true} Description Called by the filter for each "spam" message that contains a key

InvalidateKey() Parameters o The protected user's address Key o A key encoded address retrieved from any part of the message Originator o address of the message's sender. GKC Token Format o Either xml or json Description Called by the filter when the user clicks "Is Spam" on a message that contains a key. Returns Key's post invalidation properties in either xml or json Example: { "key": { "isvalidkey": "false", "issuedto": "\"Joe\" ", "issueddate":" :11:22", "expires":" :59:59", "issuedby":"SMTP Outgoing Insertion" },"success":true}

Authenticate() Parameters Address o The protected user's address Client Token o 10 digit alpha-numeric GKC Token o 10 digit alpha-numeric Provider ID o 32 digit alpha-numeric Format o Either xml or json Description Called by the filter to authenticate access to the protected user's GKC account. Returns True or False in either xml or json format {"success": true} First called by the filter to initiate the filter authentication process. Then called to confirm the receipt of each GKC token.

GetUserPreferences() Parameters Address o The protected user's address GKC Token Format o Either xml or json Returns Account status and user preferances (xml or json) Description: Called by the filter at the start of each session. Example: { "user": { "isauthenticated": "true", "subexpires":" ", "uniquekeysissued": "123", "recovered": "12", "received": "12345", "spam": "12345", "established":" ", "lastaccessed":" ", "lastaccessedip":" ", "provider":"Example, inc.", "messagefooter":"Replies to this..." },"success":true}

The GKC Authentication Token Description The GKC Authentication Token is A alpha-numeric ASCII string of a maximum of 11 characters in length Requested via the authenticate API Delivered to the filter via Obtained by extracting from the subject field of the confirmation The structure of the subject field is: "... Token is: : " Note: Once acquired via the authenticate API, then every call from the filter to the GKC must include the GKC Authentication Token.

GetMailToKey() Parameters UserGUID o 128 bit GUID String Description - Called by the web browers to dynamically insert keyed addresses in to web pages. Returns Encoded mailto: tag including key encoded address Example: mailt o:john .smit h+1234 5@exa mple. com