Email Permission Keys in five easy steps

1
Email Permission Keysin five easy steps

• Adrian McElligottadrianepk_at_geobytes.com

2
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

•  

3
Email Permission KeysSystem 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

4
Overview

• The requirements of a GKC client are to provide
  the following facilities and functions
• Authentication - uses a token delivered via
  email. 
• Initialization - retrieving client preferences
  from the GKC.
• Intercept all out going email and insert a
  permission key in to all instances of the
  protected user's email address.
• Monitor the Spam folder, and recover any messages
  that contain a valid key.
• 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.
5
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.
localpart_at_domain.tld 
6
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.

7
Outbound Message Key Insertion Function

• For 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.

8
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.

9
Authentication
Description Called 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

• What to use it for
• New Account Instance Authentication 
• Account Instance Re-authentication
• To acknowledge the receipt of GKC Tokens

Note Please see "New User Instance Account
Initialization" for a description of the
authentication process.
10
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 
• a probe message to test for the existence of plus
  addressing support within the protected user's
  email system, and
• a message containing the GKC authentication token.

Continued
11
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
  (gkc_at_keycustodian.com) 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
• calls Authenticate() for each recovered GKC
  token - this time including the GKC's token in
  the request.
• permanently records the first 10 digits of
  the GKC's token for inclusion in all further
  calls to the GKC.

Continued
12
New User Account Initialization con't.
Notes

• 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.

13
The Key Custodian APIReference
14
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.
localpart_at_domain.tld 
15
GetKey()
Description Called by the filter for each
outgoing message to obtain a key

• Parameters
• Email
• The protected user's email address
• Recipients
• Coma delimited list of the recipient email
  addresses.
• Filter Statistics (optional)
• MsgsReceived
• MsgsRecovered
• TotalSpam
•  
•  

• GKC Token
• Format
• Either xml or json
• Returns
• A keyed instance of the protected user's email
  address in either xml or json
• Example 
•  "key"
•       "addrspec" "joHN.SmiTH12345_at_eXamPLE.Com",
        "email" "\"John Smith 12345\"
  "   
  ,"success"true 

16
IsValidKey()
Description Called by the filter for each "spam"
message that contains a key

• Parameters
• Email
• The protected user's email address
• Key
• A key encoded email address retrieved from any
  part of the message
• Senders (optional)
• Coma delimited list of Email address of the
  message's senders.
• GKC Token
• Format
• Either xml or json

• Returns
• Key properties in either xml or json
•  
• Example 
•  "key"
•       "isvalidkey" "true",      "issuedto"
  "\"Joe\" ",      "issueddate""20080
  827232220",      "expires""20080903232220",    
    "issuedby""SMTP Outgoing Insertion"   
  ,"success"true 

17
InvalidateKey()
Description Called by the filter when the user
clicks "Is Spam" on a message that contains a key.

• Parameters
• Email
• The protected user's email address
• Key
• A key encoded email address retrieved from any
  part of the message
• Originator
• Email address of the message's sender.
• GKC Token
• Format
• Either xml or json
•  

• Returns
• Key's post invalidation properties in either xml
  or json
•  
• Example 
•  "key"
•       "isvalidkey" "false",      "issuedto"
  "\"Joe\" ",      "issueddate""2008-
  10-30 161122",      "expires""2999-12-31
  235959",      "issuedby""SMTP Outgoing
  Insertion"    ,"success"true 

18
Authenticate()
Description Called by the filter to authenticate
access to the protected user's GKC account. 

• Parameters
• Email Address
• The protected user's email address
• Client Token
• 10 digit alpha-numeric 
• GKC Token
• 10 digit alpha-numeric
• Provider ID
• 32 digit alpha-numeric
• Format
• Either xml or json

• 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. 

19
GetUserPreferences()
Description Called by the filter at the start of
each session.

• Parameters
• Email Address
• The protected user's email address
• GKC Token
• Format
• Either xml or json
• Returns
• Account status and user preferances (xml or json)

• Example 
•  "user"
•       "isauthenticated" "true",
•       "email""joE123_at_eXamplE.Com",
•       "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 

20
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 email
• Obtained by extracting from the subject field of
  the confirmation email
• 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.
21
GetMailToKey()
Description - Called by the web browers to
dynamically insert keyed email addresses in to
web pages.

• Parameters
• UserGUID
• 128 bit GUID String

• Returns
• Encoded mailto tag including key encoded email
  address
•  
• Example 
• 109097105108116
• 111106111104110
• 046115109105116
• 104049050051052
• 053064101120097
• 109112108101046
• 099111109