Email Permission Keys in five easy steps Adrian McElligott [email protected].

Email Permission Keysin five easy steps

Adrian [email protected]

Resources

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

Email Permission KeysSystem Components

• Client Side• Outbound Message

Key Insertion Function

• Spam Folder Monitoring Module

• Server SideKey Issuing Facility

– AJAX Web Service – UI for manual issuing– Key Custodian API

• GetKey • IsValidKey • InvalidateKey

• Access authentication • Key Generation• Key Storage &

Retrieval • Reporting

OverviewThe requirements of a GKC client are to provide the

following facilities and functions:1. Authentication - uses a token delivered via

email. 2. Initialization - retrieving client preferences from

the GKC. 3. Intercept all out going email and insert a

permission key in to all instances of the protected user's email address.

4. Monitor the Spam folder, and recover any messages that contain a valid key.

5. Invalidate Compromised KeysNote: 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 "email address" refers to an email address as defined by "RFC 2822 3.4. 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. [email protected] 

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 Email Address.

• Retrieve any keyed instances of the protected user's email 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 FunctionFor each outgoing message:• Obtain the Recipient's

Email 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 email 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 email 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 Email Address.• Retrieve any keyed instances of the protected

user's email 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

DescriptionCalled to initiate the dispatching of, and to acknowledge the receipt of GKC Tokens.

When to use it:• Upon new installation /

activation of Email 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 email messages to the protected user's email address: 1.a probe message to test for the existence of plus

addressing support within the protected user's email 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 email address ([email protected]) 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:<filter token>:<gkc token>"

• The filter recovers the GKC's token from the subject field of each GKC message, and1.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 APIReference

The Key Custodian APIs

Filters call• Authenticate(...)• GetKey(...) • IsValidKey(...)• InvalidateKey(...)• GetUserPreferences(...)

Anonymous Browsers call • GetMailToKey(...)  

Note: Unless specified otherwise, the term "email address" refers to an email address as defined by "RFC 2822 3.4. 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. [email protected] 

GetKey()

Parameters• Email

o The protected user's email address

• Recipientso Coma delimited list of

the recipient email addresses.

• Filter Statistics (optional)o MsgsReceivedo MsgsRecoveredo TotalSpam

• GKC Token• Format

o Either xml or jsonReturnsA keyed instance of the protected user's email address in either xml or jsonExample:  { "key": {      "addrspec": "[email protected]",      "email": "\"John Smith 12345\" <[email protected]>"    },"success":true} 

DescriptionCalled by the filter for each outgoing message to obtain a key

IsValidKey()

Parameters• Email

o The protected user's email address

• Keyo A key encoded email

address retrieved from any part of the message

• Senders (optional)o Coma delimited list of

Email address of the message's senders.

• GKC Token• Format

o Either xml or json

ReturnsKey properties in either xml or json Example:  { "key": {      "isvalidkey": "true",      "issuedto": "\"Joe\" <[email protected]>",      "issueddate":"20080827232220",      "expires":"20080903232220",      "issuedby":"SMTP Outgoing Insertion"    },"success":true} 

DescriptionCalled by the filter for each "spam" message that contains a key

InvalidateKey()Parameters• Email

o The protected user's email address

• Keyo A key encoded email

address retrieved from any part of the message

• Originatoro Email address of the

message's sender. • GKC Token• Format

o Either xml or json

DescriptionCalled 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\" <[email protected]>",      "issueddate":"2008-10-30 16:11:22",      "expires":"2999-12-31 23:59:59",      "issuedby":"SMTP Outgoing Insertion"    },"success":true} 

Authenticate()

Parameters• Email Address

o The protected user's email address

• Client Tokeno 10 digit alpha-

numeric • GKC Token

o 10 digit alpha-numeric

• Provider IDo 32 digit alpha-

numeric• Format

o Either xml or json

DescriptionCalled by the filter to authenticate access to the protected user's GKC account. 

ReturnsTrue 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• Email Address

o The protected user's email address

• GKC Token• Format

o Either xml or json

ReturnsAccount status and user preferances (xml or json)

Description: Called by the filter at the start of each session.

Example: { "user": {      "isauthenticated": "true",      "email":"[email protected]",      "subexpires":"20090903232220",      "uniquekeysissued": "123",      "recovered": "12",      "received": "12345",      "spam": "12345",      "established":"20080827232220",      "lastaccessed":"20080827232220",      "lastaccessedip":"0.0.0.0",      "provider":"Example, inc.",      "messagefooter":"Replies to this..."    },"success":true} 

The GKC Authentication TokenDescriptionThe 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 email• Obtained by extracting from the subject field of

the confirmation email• The structure of the subject field is: 

   "... Token is:<filter token>:<gkc token>"

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 email addresses in to web pages.

ReturnsEncoded mailto: tag including key encoded email address Example:  &#109;&#097;&#105;&#108;&#116;&#111;:&#106;&#111;&#104;&#110;&#046;&#115;&#109;&#105;&#116;&#104;+&#049;&#050;&#051;&#052;&#053;&#064;&#101;&#120;&#097;&#109;&#112;&#108;&#101;&#046;&#099;&#111;&#109;