Freelancer Union Forum

Power to the End User - Customizable Access API Keys (http://www.eveonline.com/devblog.asp?a=blog&bid=848)
29 January 2011, 7:07 pm

TL;DR: We are completely overhauling the API authentication system, and the API keys, according to most popular wishes from the community, the application developers and the CSM. We are also changing the nomenclature a bit so the term API Key isn‘t as interchangable between different concepts.

The what.

The EVE API (referred to as API henceforth) is a service we provide to developers outside of CCP so they can provide third party applications aimed at making your EVE experience that more enjoyable. Examples of applications you might recognize, that make use of the API, are: EVEMon, EVE Fitting Tool (EFT) and the EVEBoard. All of these applications rely, to a different extent, on your characters in-game data. As knowledge is power it is imperative that the API is as secure as possible while still being usable.

As it stands the API has two access levels: the limited access API key and the full access API key (referred to as access keys henceforth). These two access keys are currently created and deleted on user demand through the API Key management (http://www.eveonline.com/api/). These access keys consist of a User ID and an API Key for authentication. Access control is only affected by the type of access key generated, that is limited or full. Once the access keys have been created the User ID and API Key pair that belongs to them is put into the third party application settings so it can authenticate against the API and fetch the data it needs.

The full access key gives anyone who has your User ID and API Key pair access to all data we expose through the API, and the limited one gives access to a set of predefined information. This was all fine and dandy as a preliminary inception of the service but as it has grown in both functionality and usage this access restriction schema has become somewhat disadvantageous due to its lack of flexibility.

A lot of this blog is dedicated to technical talk as this mostly affects the application developers. End-users will have to relearn the process of creating and managing access keys, which is also covered in this blog. Important factors are bulletpointed below but a lot of this dev blog will be aimed at the developers. If you are not one of them feel free to skim read this and roll your eyes occasionally.

The why.

Almost every pilot and corporation in New Eden has given their full or limited access key to someone as it has become the de facto standard of both corporations and alliances to verify potential recruits. Both of these access keys often give access to more information than the receiver strictly requires. Directors of corporations must give out their personal character access key in order for alliances to look into their corporations. Access keys handed over to a second party can be traded to the holders liking and will never expire unless the keys' owner generates a new one. All of those points, along with both user and developer requests, have put us on the path of redesigning the access control layer of the API service.

The how.

Here is the design we are working with, in bullet points:

• The User ID will be removed from the authentication process.            
  • It is less than ideal to require people to pass along meaningful information to other parties along with their key for authentication.
• Replacing the User ID with a keyID as a unique key identifier.            
  • Thus your account is no longer constrained to a pair of API keys (User ID and one full access plus one limited access key) nor is any information about it exposed in the key itself.        
• The API Key will be removed from the authentication process and a verification code introduced to replace it. This verification code will, by default, look much like the old API Key but will also accept user input for convenience.            
  • This will clear up the current nomenclature. As you can see above in this blog the duality of the term "API Key" is somewhat problematic to explanations.            
    • Access Keys are now API Keys or just keys for short.
    • The Keys authentication part consists of:            
      • KeyID            
        • As mentioned this is a unique identifier for your key.
      • Verification Code            
        • This is your security measure. People can possibly guess your keyID  but that does not allow them to guess your secret verification code to authenticate.
  • This can also simplify management for the end user who might like to share the samekey verification code between the different API keys of his different accounts.
  • CCP strongly recommends that you do not use the same verification code as your EVE account password and that you do not share the verification codes you use for your privately used keys.            
    • There is however nothing stopping you from doing these things other than security awareness.
  • Example API Key (Current schema):            
    • userID = 19
      
      apiKey = c5SS0sxYzfbdEVOEu7xxY8w9Nv00TTPO0012B6915IszWFb6GTn4jDs9pwgrCTQYp
  • Example API Key (New schema), any one of:            
    • keyID = 157
      
      verificationCode = c5SS0sxYzfbdEVOEu7xxY8w9NvTT0PO0012B6915IszWFb6GTn4jDs9pwgrCTQYp
      
      or
      
      keyID = 157
      
      verificationCode = m4nIh473Th353L0n9S7rin9s
      
      or
      
      keyID = 157
      
      verificationCode = corpCheckKeyExpireIn1Hour
• We will deprecate the LIMITED/FULL access schema (see above) and give you theoptionto customize what API requests your keys will grant access to.            
  • There is no reason for users to always give out access to their EVE Mail because the corporation they are applying to wants to see their asset list so they can proof their ownership of T2 BPOs.
• Finally this new service will be HTTPS only.        

Thus your API call authentication will no longer be based on your User ID and a API Key for verification. Instead you will authenticate with a keyID and its paired verification code as shown in the example key above.

Further security additions!

Seeing as we're doing this massive overhaul of the authentication layer we decided to take the security measures of keys to the next level.

• An expiry date will be added to all API keys.            
  • So if someone gets his hands on your API key without you knowing it will at least expire at some point removing his access to your data.            
    • Note that there is an activity log on each key that you can query if you suspect your key is compromised.
  • Maximum lifetime of a year.
  • Minimum lifetime of an hour.
• Separating corporation and character keys.            
  • Currently a corporate director has to give away his private asset list because an alliance wants to validate the corporation as the holders of T2 BPOs.
• Allowing character specific keys rather than always account wide.            
  • In many cases API key holders do not want to expose their entire account.
  • In the corporation example above the Director is not only exposing his main characters asset list with the corporation key but also the asset list of all his alts.
  • This setting will only be viewable through the API key management, not by everyone holding the key. So the holder of a character specific key will not be able to see what other characters belong to the account if the keys owner sets it to a single character.
• Increasing the number of API keys per account to accommodate for the new access customization which replaces the FULL / LIMITED access.            
  • This should make it easier for API holders to have their private keys private and still have the ability to create keys to share to others if the need arises.

How to customize the access of keys:

The EVE API consists of three categories:

• Character bound API
• Corporate bound API
• Keyless API (will not be affected as no authentication is required for it)

As I mentioned the key bound categories will be split up between keys with the introduction of the corporation API key. But this is not enough granularity! For example, the character bound API contains 25 separate calls. But requiring non-super users to pick from 25 calls in order to make an active key is going to be too confusing for many. So instead we're grouping the calls together according to functionality.

The actual grouping of calls is still up for discussion and the final version will be announced in a much later blog (which will contain things such as the key generation layout and the final plan for migration) but it will look something like this:

• Group: Character sheet            
  • /char/CharacterSheet.xml.aspx
  • /char/Standings.xml.aspx
• Group: Wallet            
  • /char/WalletTransactions.xml.aspx
  • /char/WalletTransactions.csv.aspx
  • /char/WalletJournal.xml.aspx
  • /char/WalletJournal.csv.aspx
  • /char/AccountBalance.xml.aspx
• Group: Science and Industry            
  • /char/Research.xml.aspx
  • /char/IndustryJobs.xml.aspx
• Etc...

These groups will not have any overlapping access as the current design stands, although the data provided will be overlapping in many cases, such as the character sheet and account balance. Even though this will undergo further revision I'd like to encourage all discussions based on how this access grouping should be done and even whether or not it should be more granular.

 

How will this affect the API key generation and the end-user?

Greatly!

The new API keys will be managed through EVE Gate. There you will be able to add, edit and remove keys through a user friendly interface. As the interface has not been created at the time of writing I have no screenshots for you. There will be a management interface for all API keys where you can see your currently active keys, edit or delete them as well as creating new ones.

The process of creating a new API key will go something like this (like I mentioned earlier there is no current design for the layout):

• Log into EVE Gate on a character on the account you want to link the key to (or the character in question for a single character only API) or, in the case of corporate keys, a character with the director role.
• Go to the API Key Management
• Select "Create New API Key"
• Give your key a name so you can easily differentiate between the purpose of keys in the management interface through a descriptive name.
• Select a lifespan (see Further Security Additions above) for your new key, the default will be six months.
• Select the type of key you are generating            
  • Corporation Key (Requires Director role)
  • Account wide key
  • Character bound key
• Assign call groups to your key.
• Auto-generate, or assign, a verification code to go with the keyID.

The edit functionality will then allow you to change all of the above with the exception of the keyID itself. You can always delete keys and recreate them for a new keyID if you believe it is somehow compromised. In order to reduce the risk of compromised keys we would advise you to always generate new keys, with an auto-generated verification code as well as a short lifespan, to hand out to second parties.

So... how is this happening?

This is a massive change that will not be rushed out. It will also affect application developers who need to redesign parts of their applications to fit with the new access schema. When it is ready, and we are happy with the internal testing, we will push it out to the public test API that connects to SISI.

Once the new API has been deployed out to Tranquility we intend to keep both versions of the API running for some time. This will allow developers leeway to introduce new versions of their applications and users to generate their new API keys. We do not intend to move the current API keys over to the new system as that would defeat the purpose of this security overhaul. The new custom access level API will be hosted on the EVE Gate along with its API key management.

Once development gets into full swing and we've got more details to give to you we will publish another blog. In the meantime you have the opportunity to give us feedback and ideas to improve this design proposition.

What about all the other features the API is missing?

We are fully aware or both missing pages and other additional functionality that ranks highly on the community wish-list for the EVE API. However we are focusing on the security layer before we add any further complications. We really want feedback on this proposition to make it as compatible with the community wishes as possible and thus I would like to request that we keep the comments section restricted to the subject matter of the Dev Blog rather than risking good feedback getting lost.

So how about it? Got something that might make the API even more awesome?

Fly safe pod-pilots,

CCP Prism X

EVE Software Database Developer and Acting API Dude

 

 

 

Source: eveonline.com | devBlog (http://www.eveonline.com/)