Mitro: Password Manager for Groups/Enterprise

Mitroisapasswordmanagerthatsupportsgroupsandenterprises.Itintegrateswithweb
browserstogenerateandsavepasswords,meaningthatusersonlyneedonestrongpassword
tosignintoanywebapplication.Italsosupportssharingpasswordswithotherindividualsor
groups,andsupportsorganizationsthatcanapplytheirownpolicies.

UseCases
Individual
TwoFactorAuthentication
Sharing
Organizations
Enterprisefeatureswemaywanttosupportinthefuture
CoreCryptographicDesign
Identities
Groups
ACLSignatures
AccessControlExample
Secrets
Secretstorageexample
DiscardedDesignAlternatives/Discussion
Implementation
Client/ServerCommunication
ClientStorage
Operations
SynchronizingGroupswithExternalDirectories
Customermanagedsynchronizationagent
Mitrohostedgroupsyncing,withadministratorapproval
Mitrohostedgroupsyncingwithautomaticchanges
TheUserVisibleModel
Questions

Use Cases
Thissectiondescribeshowpeoplewillusethetool,withoutdiscussinganyspecificinterfaceor
technicalrequirements.

Individual
Wantssomethingtogenerate/rememberpersonalpasswordsacrossallbrowsersanddevices.
E.g.bankaccountlogin,emaillogin,Twitteraccount.

Logsintoawebsitewithanexistingpassword:promptstosavepassword.
Createsanewaccountonasite:prompttogenerateauniquepassword.
Visitsasiteonwhichhe/shehasanaccount:promptstosignin/autofill.
Changesapasswordonasite:wesavethenewpassword.Wealsosaveallprevious
versions,soincasewe/theyscrewup,theusercanfindtheiroldpassword.
Canchoosetocopyorviewthepassword,althoughwediscourageitintheUI.Thisis
neededfornonweblogins.
Savessecurenotes(e.g.creditcardnumbers,databaseserverpasswords,root
certificates,etc.)
Accessestheirpasswordsonmultipledevices(webbrowsers,mobile,etc).
Optional:Iftheyforgettheirpassword,itshouldbepossibletoresetit.Suggestion
options:Escrowusinganofflinekeywithus(manualrecovery),downloadablerecovery
codefile,storeaGoogleDoc/Drive/Dropboxrecoveryfile(viatheJSAPIsoitisdoneon
theclientside).

Two Factor Authentication

Someuserswillwanttoenabletwofactorauthentication(2fa)forextrasecurity.

UserselectstheTwoFactorAuthPreferencesinthepopup,andatabopensuptothe
TwoFactorAuthenticationPreferencespage.
Thepageeither:
a.Saystheuserhasenabled2faandletstheuserdisableitorresetthebackupcodes.
b.Saystheuserhasntenabled2fa,explainswhatitisandletstheuserenableit.
Enable2fa:prompttoscantheQRcodeandinputtheverificationcodefromtheapp.If
thecodewascorrect:backupcodesareshown.Ifnot:prompttoinputcodeagain.
Loginonanewdevice:if2faisenabled,prompttoinputverificationorbackupcode
Changepassword:if2faisenabled,prompttoinputverificationorbackupcode

Sharing
Someaccountsneedtobeshared,forbothpersonalreasons(e.g.sharingabankaccountwith
aspouse)andforwork(e.g.sharedTwitteraccount,sharedcreditcard,hiringacontractor).

Userselectsanaccountorsecurenoteandchoosespeople/groupstoshareitwith.
Peopleareidentifiedbyemailaddress,sowecanincludepeoplewhodontalreadyhave
accounts.Thispasswordthenappearsinthesamewayasallotherpasswords.
Usersareeitherownersorusers.Ownerscancontrolwhohasaccessandeditthe
metadata.Regularuserscanonlyusethepassword.NOTE:Thisismorefor
convenience,notforsecurity:anyonewhohasaccesstothepasswordcancopyitand
changethepasswordontheservice.Thisisaconvenienceformostlytrustedteams.
Whenrevokingaccess,iftheuserbeingremovedhaseveraccessedthepassword,we
suggestchangingit(toguaranteethattheynolongerhaveaccess).
Userscancreategroupsofpeopleandpasswords.e.g.digitalagenciescancreatea
groupperclient,thenassignusersandpasswordstothatclientasappropriate.Groups
alsohaveaccesslevelsofownersandusers.

Organizations
Organizationswantadditionalcontrol:administratoraccesstoallpasswords,limitsonsharing
(e.g.forbidsharingexternally),policiesaboutauthentication(e.g.timeouts,2FA),resettinguser
passwords,etc.Theymayadditionallywishtosynchronizewithexistingdirectories(e.g.Google
Apps,ActiveDirectory,LDAP).Directoriesmayhaveahierarchyoforganizationalunitsin
additiontogroups.However,forusersitshouldworkthesame:theysavepasswordsinan
organization,andcanusethemasnormal.

Anorganizationsadministratorscanaccessandeditanythingthatbelongstoan
organization(accounts/securenotes,andgroups).Thiswaytheycanseewhatservices
theirorganizationisusing,canaccessaccountsifsomeoneleaves,andcanreset
passwords.
Anorganizationsmemberscancreatenewaccounts/securenotesandnewgroupsas
partoftheorganization.
Userscanuseboththeirpersonalpasswordsandorganizationspasswordsatthesame
time,fromthesamebrowser.
Whensavinganewpasswordtheclientaskswhatorganizationitshouldbelongto(e.g.
OrgA,OrgB,Personal),defaultingtowhateverwasselectedlast.
Userscansaveindividualaccounts/securenotesthatbelongtotheorganization.E.g.
theirownSalesforce,YouSendItorDNSaccounts.Theseareaccessibleonlytothem,
andtotheorganizationadministrators.
Sharinganaccount/securenotewithothermembersoftheorganizationworksasnormal
(aspermittedbytheACLsofeachsecret/group)
Whensharingapasswordwithsomeonewhoisnotamemberoftheorganization,the
companypolicyapplies.Bydefault,itwilldisplayawarning,butallowanyonetoinvite
newusers(similartoGoogleDocs).Otherpoliciesaredenyoraskadministrator.
Audit/accesslogs:Administratorscanseewhohasaccessedwhichpasswords,from
whichdevices.
Device/usagereports:Administratorscanseewhichdeviceshavebeenusedtoaccess
theservice.
Backupsandexporting:Fordisasterrecoveryandtoavoidlockin.

Enterprise features we may want to support in the future

Enforcerulesabouthowusersauthenticate.E.g.musttypeapasswordonceaday,use
twofactorauthentication,orotherpolicies.
Storeanorganizationspasswordsontheirownserver,whilestillusingpasswordson
thepublicserver(e.g.personal).
Restrictaccesstotheorganizationspasswordstospecificdevices.
Forceallpasswordstobelongtotheorganization(e.g.abank,onabankowned
machine).
Restrictuserssotheycantcreatetheirowngroups.
Allowuserstoseeallpasswordsintheorganization,andallowthemtorequestaccess.
Oneagencylikesthisfeatureoftheirexistingsystem,sinceitpermitsalevelof
selfserviceaccess,whileallowingmanagerstocontrolwhohasaccesstowhat.

Core Cryptographic Design

Mitroisdividedintotwoparts:thecoreserviceandtheuserinterface.Thecoreserviceis
securitycriticalandperformsallthecryptographicoperations.Itisintendedtobeassimpleas
possibletomakeiteasiertoverifythedesignandtheimplementation.Theuserinterfacemaps
useroperationstosimplercoreserviceoperations.Theuserinterfaceisalsoinevitablyinvolved
inmaintainingsecurity.However,ifthecoreserviceiscorrect,flawsintheuserinterfaceshould
onlyhavelimitedimpact.Functionalityinbothpartsisdividedbetweenclientsandtheserver.

MitroCoreiscomposedofaclient,typicallyrunningasawebbrowserextension,andthe
keyserver.Theserveristrustedaslittleaspossible,sinceitwillberunasathirdpartyservice
andcanbeeasilyattacked.Thecoreservicestoresthreetypesofdata:identities,groups,and
secrets.Identitiesarepublic/privatekeysthatrepresentusers.Groupsimplementaccess
controlliststolimitwhocansee,accessandeditsecrets.Secretsstoreusernames/passwords
orothersecretdata.

Identities
Tousetheservice,aclientmustcreateanidentity.Anidentityiscomposedofauniqueuserid
(usuallyanemailaddress),apublickey,anencryptedprivatekey,adisplayname,andadditional
directorydata.Theclientcodegeneratesthekeypair,andencryptstheprivatekeyusinga
strongpassphrase.Thesecurityofthesystemreliesonthefactthatonlythisauthorized
usercanaccessthedecryptedsecretkey.

Tocreateanidentity,theclientsubmitsarequesttoaserverwithaproofofidentity.Thisproofis
anassertionfromatrustedthirdpartythattheusersubmittingtherequestreallycontrolsthe
userid(e.g.aGoogleOAuthtoken,oratokenfromourownemailverificationservice).The
keyserververifiesthetoken,thensignstheidentityrecordwithitsownprivatekey.Thissignature
provestoclientsthatthekeyserververifiedtheidentity,andmeanssomeonewithaccesstothe
databasecannotinsertormodifyidentities.

Identitiesstore:
userid
name
publickey
encryptedprivatekey
additionaloptionaldirectorydata(e.g.profilepicture,website,contactdetails,...)
keyserversignatureon(userid,publickey)
twofactorauthenticationsecretandbackupcodes

Groups
Groupsapplyaccesscontrolpoliciestoasetofsecrets(seebelow).Groupscontainmembers
inanAccessControlList(ACL),eachofwhichinanidentityoranothergroups.Eachgroupalso
hasitsownpublic/privatekeypair.Theprivatekeyisindividuallyencryptedforeachgroup
member,soonlythatmembercandecryptit.EachACLentryissignedwiththegroupkey,so
thekeyserverandclientscanverifythatitwasaddedbyamemberofthegroup(otherwise,
someonemightaddthemselvestothegroup,andthenexttimethegroupkeywaschangedthey
wouldgetaccess).

Whenaddingasecrettoagroup,thesecretisencryptedwiththegrouppublickey,soonly
membersofthegroupcanaccessit.Whenremovingauser,thegroupkeyneedstoberotated,
toensurethatifanattackergetsaccesstotheencrypteddata,previousmemberscannot
accessit.Thesecretrecordissignedbyagroupmembersothatclientsandthekeyservercan
provethatavalidmemberofthegroupaddedit,andthatsomeoneisnotattemptingtoinjecta
recordforagroup.

Groupmembershavetwolevelsofaccess:ownerormember.Ownerscanediteverything
insideagroup:thegroupmetadata,add/removesecrets,andchangingthemembership.
Memberscanonlyreadthegroupmetadata,secretsandmembershiplist.Sincegroupscan
containothergroups,thisprovidesaflexiblegraphrelationshipthatcanrepresentboth
hierarchiesandcrossorganizationalgroupings.Weneverpermitcyclesinthegroupgraph,
whichisenforcedwhenaddinggroupsasowners/members.Eachgroupmustalsohaveat
leastoneowner.

Identitiescanseethepublicmetadataforallgroupsthattheybelongtoasanowner/member,as
wellasallthegroupsthatareincludedinthosegroupsasowners/members.

Groupdata:
groupuniqueid
name/label
publickey
groupkeysignature(name,publickey)
listofACLentries
listofcontainedsecrets,encryptedforthisgroup

ACLdata:
acluniqueid
groupid(pointertogroup,above)
level(memberorowner)
membergroupid(canbenull)
memberidentityid(canbenull)
encryptedgroupprivatekeyforthegroup/identity
groupkeysignature(parentgroupid,level,membergroupid,identityid)

Secretdata:
parentgroupid
secretuniqueid
secretversionid
clientvisibledata(encryptedwithgroupkey)
criticaldata(encryptedwithgroupkey)
groupkeysignature(parentgroupid,secretunitid)

ACL Signatures
SignaturesonACLsarerequiredtopreventanattackerwithwriteaccesstothedatabasefrom
injectingthemselvesintoagroup,asfollows:

1. Attackeraddstheiridentitytoalargegroup,whereitisunlikelytobenoticed.Atthispoint,
theycannotaccessanysecrets,becausetheydonothaveaccesstothegroupkey.
2. Anadministratorremovesanormaluserfromthegroup.Thiscausesthegroupkeytobe
rotated.Aspartofthisoperation,theygenerateanewgroupkey,andencryptitforallthe
members,includingAttacker.
3. Attackernowhasaccesstothesecretsinthegroup.

SigningeachACLentrywiththegroupkeyitselfsolvespartoftheproblem:nowinstep2,the
administratorwillseethatAttackersentrydoesnothaveavalidsignatureanddetectthe
problem.Evenbetter,Mitrocanperiodicallyscanthedatabaseforsuspiciousdata.However,it
doesnotprotectfromanattackerspoofingtheentiregroup:

1. Attackerreplacesthetargetgroupskeywithanewgeneratedkey.
2. AttackerupdatesallACLentriestobesignedwiththenewkey,andaddstheirownentry.
3. Attackerrewritesallsecretstogeneratedfakedatatheyhavecreated.
4. Auseroradministratorsavesanewpasswordtothegroup.Or,theyseethata
passwordnolongerworksandresetit/resaveit.
5. Theattackernowhasaccesstothatpassword.

Thisrequiresuserstonotnoticethatthesecretshavechangedorbeendeleted,whichisless
likelybutnotimpossible.TODO:Canweprotectagainstthisinanintelligentway?

Access Control Example
GroupEngineering:members:Id1owners:Id2,GroupCompany
GroupSales:members:Id3owners:Id4,GroupCompany
GroupCompany:members:Id5owners:Id6
GroupAllStaff:members:GroupEngineering,GroupSalesowners:GroupCompany

Figure1:Membershipgraph,arrowspointtoincludedgroups

Inthefigureabove,arrowspointfromagrouptoincludedgroups.Accesstosecretsflowsalong
theseedges,meaningthatsecretsinupstreamgroupscanbeaccessedbyidentitiesinthe
downstreamgroup(s).Intheexample,secretsinGroupEngineeringcanbeaccessedby
identities1,2,5and6.Theycanbeeditedbyidentities2(e.g.anengineeringmanager),5and6.
Thecompanygroupcanonlybeeditedbyidentity6(e.g.theCEO),althoughidentity5canedit
anythinginSalesandEngineering.

Company,EngineeringandSalesformastricthierarchywithCompanyatthetoplevel.AllStaff
isacrosshierarchygroup(e.g.globalengineeringstaff,containingengineersfromboth
CanadaandtheUnitedStates).SecretsinAllStaffarevisibletoeveryone,butcanonlybe
administeredbypeopleinthetoplevelCompanygroup.

Whenidentity1liststheirgroups,theyseeEngineeringandAllStaff(becausetheyare
members),andCompany(becauseitisincludedinEngineering).TheycannotseetheSales
group.Identity6canseeallthegroups,sincetheyareanownerofallofthem.

Secrets
Secretsstoreencrypteddata.Everysecretbelongstoatleastonegroupthatcontrolswhocan
accessit.Thesecrethasthreeparts:servervisible,clientvisible,andsecuritycritical.The
servervisiblepartisvisibletotheserver,foroperationalreasons.Theclientvisiblepartis
encrypted,butreturnedwiththelistsecretsoperation,andisdisplayedtotheuser.Hence,this
partshouldnotcontaincriticaldata.Thesecuritycriticalpartisonlyreturnedwhenthissecretis
accessedindividually.Theencryptionensuresthatonlymembersofthegroup(s)thissecret
belongscanaccesstoit.Secretsareversioned,sopreviousrevisionsofthedata(e.g.
username,password)arestillaccessible.Thisallowsuserstorecoverfromaccidentaledits.
Thesystemwillautomaticallydeleteoldrevisionsafter30days,anduserscanexplicitlyexpunge
previousrevisions.Thisallowsuserstopermanentlyremovedatathatwasaccidentallysaved.

Servervisiblerecord:
secretid
versionid
edittimestamp
url/hostname(soMitrocanimprovetheservicetoworkwiththesewebsites.TODO:
allowclientstooptoutandincludethisfieldintheclientvisiblesection?)

Secretdata(actuallystoredaspartofthegrouprecord):
name/label(clientvisible)
longdescription(clientvisibleoptional)
username(clientvisible)
password(critical)
secretdata(critical)

Secret storage example

Wewillwalkthroughanexampleofhowtheencryptionofgroups/identitieswork.Thesimplest
caseisasingleprivatepassword.Inthiscase,identityUcreatesanewGroupXtostorethe
ACLforthepassword.Theusergeneratesanewkeypairforthegroup,andencryptsitwiththeir
publickeysoonlyidentityUcandecryptit.Theycreatethefollowingrecord(s)forthegroupwith
itsACL:

Group:{
id:(serverassignedGroupXid),
public_key:(groupXspublickey),
acl:[{
member_identity:U@example.com,
access_level:OWNER,
encrypted_private_key:(groupXsprivatekey,encryptedforU),
}]
}

Theythenencryptthesecretwiththisgroupkey,creatingtheserecordsfortheSecretandits
groupownership:

Secret:{
id:(serverassignedsecretid),
metadata:servervisiblemetadata,
groups:[{
id:(serverassignedGroupXid),
client_visible_data:(clientvisibledataencryptedwithGroupXskey),
critical_data:(criticaldataencryptedwithGroupXskey)
}]
}

Now,ifidentityUwishestodecryptthissecret,theymustperformthefollowingoperations:

1. Findtheshortestaccesspathfromthesecrettotheiridentity(Secret>GroupX>
IdentityU).Thedataisdecryptedinthereverseorderofthispathasfollows.
2. DecrypttheGroupXkeywithIdentityUsprivatekey.
3. DecryptthesecretwiththeGroupXkey.

TogiveanadditionalidentityVaccesstothissecret,wecanaddthemtoGroupX.Todothis,
theclientmustreencryptthegroupprivatekeyforidentityV,creatingthisrecord:

Group:{
id:(serverassignedGroupXid),
public_key:(groupXspublickey),
acl:[{
member_identity:U@example.com,
access_level:OWNER,
encrypted_private_key:(groupXsprivatekey,encryptedforU),
},{
member_identity:V@example.com,
access_level:OWNER,
encrypted_private_key:(groupXsprivatekey,encryptedforV),
}]
}

ThisgivesidentityVaccesstoeverythinginGroupX(asinglesecret).

Discarded Design Alternatives/Discussion

Encryptsecretsdirectlyforusers(nogroupkeys):Thiscouldeliminatetheneedforgroups
andgroupkeys.Instead,secretswouldbeencryptedfortheflattenedgroupmembership.This
isperfectforprivatesecretsaccessibletooneuser,orforsecretssharedwithasmallgroup.
However,itdoesntscaleaswelltolargegroups.Consideringthenumberofoperationsrequired
(below),alloperationsexceptaccessingasecretandrevokingausersaccessarecheaperwith
groupkeys.Themoreexpensiveoperationsareonlyslightlymoreexpensive.

U=#usersinthegroupS=#secretsinthegroup

Nogroupkeys:
Accessasecret:decryptthesecretwiththeusersdecryptedkey(1)
Addsecrettogroup:encryptsecretonceperuseringroup(U)
Removesecretfromgroup:DeleteACLentriesforallusers(U)
Addusertogroup:reencryptallthegroupssecretsforthatuser(S)
Removeuserfromgroup:DeleteACLentries(S)

Groupkeys:
Accessasecret:decryptthegroupkeythenthesecret(1buttechnically2operations)
Addsecrettogroup:encryptsecretwithgroupkey(1)
Removesecretfromgroup:DeleteACLentry(1)
Addusertogroup:Encryptthegroupsprivatekeyforthatuser(1)
Removeuserfromgroup:DeleteACLentry,reencryptsecretswithnewgroupkey(1+S)

Flatgroups(nonesting):thiswouldsimplifyACLs.However,wewouldneedtorepresent
organizationsinsomeway,toensurethatadministratorshaveaccesstoorganizationalsecrets.
Thisisnowrepresentedasnestedgroups.Thisalsocantdirectlyrepresentmorecomplex
directorystructures,whichwemayneedinthefuture.

Symmetricgroupkeys:Groupencryptionkeysareasymmetric,allowingusersinthegroupto
signthingsandpermittingthekeyservertoverifythem.Italsocouldpermitpeoplewhoarenot
membersofthegrouptoaddsecretstothegroup(currentlynotsupported).Forexample,
considerauserintheMarketinggroup,whowantstoshareapasswordforananalyticsaccount
withtheEngineeringgroup,butwhodoesnotbelongtotheEngineeringgroup.

Usingsymmetrickeysforgroupswouldpermitmoreefficientencryption/decryption.Inparticular,
asymmetriccryptoonlybeuseddirectlyforshortdatainputs(<~200byteswithOAEP).For
longerinputs,itistypicallyusedtoencryptarandomsymmetrickey,thenthatkeyisusedto
encryptthedata.However,usersonlyrarelyaccesssecrets,sothisshouldntbeaproblem.

Nogroupaccesslevel(containmentonly):Insteadofassigninggroupsasmembersor
owners,wecouldjustsupportcontainment.(e.g.CompanycontainsEngineeringandSales).In
thisversion,adminsofthecontaininggroupareautomaticallyadminsforthecontainedgroup.
Thisseemsfineforusers,butdoesntworksowellforsecrets.Considertheexampleof
creatinganAllStaffgroupthathasgloballyaccessiblesecrets,butisadministeredbyafew
users.ThiscanalmostberepresentedbyhavingEngineering,Sales,andCompanyallcontain
AllStaff,butthenalltheadminsinEngineering,Sales,andCompanycaneditthesecrets.Fixing
thisrequiresaddingaccesslevels,whichgetsusbacktoourcurrentsystem.

Implementation
TheserveriswrittenasaJavaservlet(usingJetty),asthisiswidelyunderstoodtechnology,
makingiteasyforpeopletodeployitthemselves,orrunitonPaaSsystemslikeHerokuor
GoogleAppengine.TheclientiswritteninJavascript,asitmustrunonmultiplewebbrowsersas
anextension(andpossiblyaspartofaplainwebpage).Javascriptextensionsbackground
tasksruninacompletelyisolatedenvironmentfromwebpagesandfromotherextensions.

Forcryptography,weuseGooglesKeyczar.Thislibraryisdesignedtomakeithardtomake
mistakeswhenusinglowlevelcryptographicprimitives.Itisalsoreleasedundera
commercialfriendlylicence(Apache),andhasC++andPythonversions.Allsecretswillbe
encryptedusingKeyczarssessionencryption,whichgeneratesarandomsymmetrickey,
encryptsthedatawiththatkey,thenencryptsthesymmetrickeywiththeasymmetrickey.While
thisisinefficientforsmalldata~<200bytes(e.g.mostpasswords),itmeanswecansupport
largesecretsandonlyauditasinglecodepath.Mostcritically,wewillneedtowritean
implementationofthesubsetofKeyczarthatweuseforJavascript.Keyczarcurrentlyuses
4096bitRSAkeysinOAEPmodeforpublic/privatekeyencryption,4096bitRSAkeyfor
public/privatekeysigning(separatefromencryptionkeys),and128bitAESinCBCmodefor
symmetricencryption.Toencryptidentityprivatekeys,itgeneratesa128bitAESkeyfroma
passwordusingPBKDF2.(TODO:AlternativesareNaCl/libsodium,whichusesnonNIST
primitivesbydefault,orOpenPGPimplementedbyGPGandBouncyCastleisKeyczarthebest
choice?)

Client/Server Communication
Allclient/servercommunicationoccursoverHTTPS.Theclientalwaysverifiesthattheservers
SSLcertificateisaspecificone,configuredwhentheclientisbuilt.Werelyonautomatic
updatestochangethecertificatewhenitisabouttoexpire.AllmodificationrequestsareHTTP
POSTs,whilereadsareHTTPGETs.EachrequestandresponseisaJSONobjectwithstring
keys({k1:somevaluek2:othervalue}).Toproveidentity,theclientserializestherequestto
astring,andsignsit.Theactualrequestsenttotheserveris:

{identity:uniqueidentitystring,request:...serializedJSONdata...,signature:web
safebase64encodedsignature}

Theserververifiesthesignatureusingtheidentityspublickey.Ifitmatches,itthenprocesses
therequest.Ifnot,itreturnsanHTTP401Unauthorizederror.Thissimpleprotocolisvulnerable
toreplayattacks,butSSLprotectsagainstthat.(TODO:Istheresomesimpleexistingprotocol
weshouldbereusinghere?Shouldwejustdoourownencryptionandsigning?)

TheoneexceptionistheCreateIdentityrequest,whichisselfsigned(toprovethattheclient
actuallyhastheprivatekey),andtheGetPrivateKeyrequest,whichisnotsigned.

Client Storage
Clientscachetheiridentitieslocally.TheprivatekeyMUSTbestoredencrypted.Onfirstuse,it
asksforthepasswordtodecryptthekey.Itthencachesthedecryptedkeyinmemory
(accordingtopolicy:afteratimelimititdropsit).(TODO:whatcountermeasurescanwetaketo
makeitdifficulttoattackthiskey?E.g.swappability,protectionfromdebuggingtoolsorother
processes?)

Clientsdonotcacheencryptedsecretslocally,andzerodecrypteddatafrommemoryASAP
(notactuallypossibleinJS,butpossiblewithNaCLandmobileapps).Thismakesiteasierto
revokesharedsecrets,providesanadditionallevelofprotection(astolenlaptophaslimited
information),andalevelofauditability(theserverlogsaremoreaccurate).Ithasthedownside
thatwhentheserviceisunavailable,soarethesecrets.Clientscancachepublickeysfor
groupsandidentities.

Operations
CreateIdentity:Clientgeneratesanewidentity.Theserververifiesandstoresit.
Requiresanexternalproofofidentity.
EditIdentity:Editthemetadataonanidentity.
RotateIdentityPrivateKey:Theclientprovidesanewkey,and*all*theirACLsand
secretsreencryptedwiththiskey.Usefulifalaptopordeviceislost/stolen.For
organizations,thiscanbeperformedbyanadministrator.Forindividuals,onlyby
themselves.TODO:Forindividuals,doweneedprotectionagainstmaliciousresets?
DeleteIdentity:Removetheidentityandanygroupsitbelongsto.Removeallempty
groups.Removeallsecretsthatbecomeorphans,orreassignownershiptoan
organizationadministrator.
GetIdentity:Returnsthepublickeyandmetadatafortheidentity.
GetPrivateKey:Returnstheencryptedprivatekeyforanidentity.Requiresanexternal
proofofidentity.Usedtosynchronizenewdevices.

CreateGroup:Clientgeneratesanewgroupkey,encryptsitforthemselvesandfor
anyoneelseintheACL.Theserverstoresthegroup.
EditGroup:EditthemetadataandoptionallytheACLonthegroup.Whenrevoking
accesstoagrouporauser,thegroupkeyshouldberegenerated,sothisneedsto
includereencryptedversionsofsecretsthatarepartofthisgroup.Todeleteagroup:
removeallmembers.
GetGroupPrivateKey:Returnsthemetadataforagroup,thegroupsACL,andthe
entireACLpathfromtheidentitytothegroup,sotheycanactuallydecrypttheprivate
key.
ListGroups:Returnsthemetadataandpublickeyforallgroupsthisidentityhasaccess
to:theentireconnectedcomponentofthegroupACLgraph.

CreateSecret:Clientencryptsasecretforatleastonegroup.
EditSecret:Clientcreatesanewversionofasecretand/orchangestheACL.When
changingtheACL,itmustreencrypttheversionhistory.Todeleteasecret:removeit
fromallgroups.
GetSecret:Returnthecriticalpartofasecret,andtheACLpathtothesecret,ifthe
identityhasaccess.Thisreturnsallversionsofthesecret.
ListSecrets:Returnstheservervisibleandclientvisiblecomponentsofallsecretsthis
identityhasaccessto.ItalsoreturnsthepublicpartoftheACLpathtoeachsecret(not
theencryptedkeys!).

Synchronizing Groups with External Directories

TherearetwoexternaldirectoriesthatourearlyusersareinterestedinusingwithMitro:LDAP
(includingActiveDirectory)andGoogleApps.Userswanttousegroupsstoredintheexternal
directorytocontrolaccesstosecretswithMitro.

Addinguserstoagrouprequiresadministratorcredentialstobeabletogivethenewuser
access.Thismeanseithercustomersmustruntheagent,ormustatleastapprovethechanges
throughtheirownclienttoensurethatMitrodoesnothaveaccesstothedecrypteddata.
Removingusersiseasier,sincewecanremovetheACLentries(howeverwestillneedtorotate
thekeys).Atrickycaseiswhentheremoveduseristhesoleownerofsomepasswords.Inthe
proposedstructurefororganizations,administratorswillalwaysbeanimplicit,hiddenownerfor
allsecrets,sotheownershipcanbereassignedwithoutneedinganycryptographicoperations.
However,itmaystillbedesirabletohaveanexplicitreassignmentofthesesecrets.

Customer-managed synchronization agent

Inthismode,thecustomerrunsadaemon(providedbyus)thatpollstheexternaldirectoryand
mirrorsthegroupsinMitro.Thisdaemonhasaccesstoaroleaccountthatisanadministrator
forallthegroupsandsecretsinanorganization.Itneedsthislevelofaccesstobeabletogive
newusersaccesstosecrets.Thecustomermustrunthisagentandensureitissecure.

Mitro-hosted group syncing, with administrator approval

Inthismode,Mitropollstheexternaldirectory.Whenchangesaredetected,itrecordsthe
desiredchanges(adduser,removeuser,etc),thennotifiestheadministrator(s)ofthe
organizationviaemail.TheadministratorthenlogsintoMitroandisshownthechangesthat
needtobeapplied.Theyclickapprovechanges,andthentheirclientmakesthechanges,
usingtheiridentity.Inthismode,Mitrodoesnothaveaccesstoanysecrets.However,
administratorsmustexaminethegroupmembershipchangestoensurethatamalicious
attackerisnottryingtoaddanunauthorizedusertothegroups.

Mitro-hosted group syncing with automatic changes

Inthismode,Mitrorunsadaemonthatautomaticallyapplieschangestothegroups.This
daemonmusthaveaccesstothesecrets,andwillbesandboxedtothehighestextentpossible.
Wecanevenrequireanadministratortostartthisdaemon,afterwhichwedonothaveany
accesstoitexceptthroughtheAPI.Thismeansmanualactionwouldberequiredafterafailure,
butitprovidesadditionalprotectionagainstattackersgainingaccesstosecrets.

The User-Visible Model

Mitroexposesafriendliermodeltousers,builtontopofthecore.ThismodelissimilartoGitHub.
Theclientstillperformsthecorecryptographicoperations,butitcommunicateswithafrontend
serverthathelpsimplementthesehigherlevelprimitives.

Users/personalidentity:Userscreateapersonalidentitybyverifyingtheiremailaddress
(eitherviaGoogleOAuthoraclickingalinkinaconfirmationemail).Thisisintendedtobelongto
thepersoncreatingtheaccount,notanyorganizations.TODO:Allowmultipleemailaddresses,
andchangingtheprimaryemail.Allowausertohavemultipleidentities,sothatanorganization
canimposeitsownkeypoliciesonusers,whilepermittinguserstostilluseMitrofortheir
personalaccounts.

Privatepasswords:Whencreatingapersonalpassword,itisrepresentedbycreatinganew
hiddengroupwiththecreatorasanowner,thenstoringthepasswordinthatgroup.

Adhocsharing:Userscaneditaccesscontrollistsontheirpersonalsecrets.Wetranslatethis
intoeditingthehiddengroupcontainingthesecret.

Invitingnewusers:Ifauserinvitessomeonewhodoesnotyethaveanidentity,wecreatean
identityforthem,andmarkitasunclaimed.Thismeanswegenerateapublic/privatekey,and
storetheprivatekeyunencrypted.Theuserclaimstheidentity,byprovingthattheyhaveaccess
totheemailaddress.Atthispointwereleasetheprivatekeytothem.TODO:Currentlywe
sendtheuseranemailwithatemporarypassword,thenexpungethepasswordfromour
system.Thisisgoodinthatwedonthavethekeyforverylong,butbadbecauseiftheusercant
findthatmessagetheycantgettheiraccount.

Flatgroups:Individualscancreategroups,andassignpasswordstogroups.Wedonotallow
nesting,andonlyallowuserstobelongtogroups.Thisisbecauseregularmortalsdonot
understandnestedgroups.TODO:Isthistoolimitingfororganizations/enterprises?

Organizations:Organizationsapplyadministrativepolicytoasetofidentities,groups,and
secrets.Organizationsarerepresentedbyanewgroupownedbytheadministratorsofthe
organization.Thisgroupistaggedtoindicatethatitisanorganization(otherwiseitlooksthe
sameasanadhocgroupofusers).Allgroupsintheorganizationareownedbythis
administratorgroup,whichgivestheadministratorsaccesstoeverythingintheorganization.

Therearethreelevelsoforganizationmembership:

Organizationowners:Havefullread/writeadministrativeaccesstoallpasswords,
groups,andACLsintheorganization.However,theUIseparatesthepasswordsthey
havedirectaccessto(asregularusers),andtheonestheyonlyhaveaccesstoas
administrators.Theymustexplicitlygototheadmininterfacetosee/edittheothers.This
triggerssomemanualreauthentication(e.g.retypeyourpasswordor2factorauth).
(TODO:Shouldwegenerateseparateidentities,whichmeansadministrativeoperations
couldbeprotecteddifferentlye.g.requiringreauthorization?IftheyhaveseparateIDs,
administratorsprobablyshouldntbeabletocreatesecrets,butonlymanagethem)
Organizationmembers:Canviewtheirownpasswords,savenewindividualpasswords
intheorganization,andcaneditthegroupsaspermittedbytheirownershiplevel.
Organizationguests:Usersthatarenotpartoftheorganizationcanbeinvitedto
accessagrouporpasswordbyanexistingmember(ifpermittedbypolicy).Guestsare
notpermittedtostorenewsecretsintheorganization,butonlyaccesswhathasbeen
explicitlysharedwiththem.Thisallowslimitedsharingwithexternalpeople(e.g.
contractors).

Theprimaryuservisiblepartofanorganizationiswhensavingnewpasswords,theyhaveto
selectifitbelongstotheorganizationornot.Iftheuserhasnotconfiguredapersonalaccount,
everythingbelongstotheorganization.

Foreachmemberoftheorganization(includingadministrators),wecreateahiddengroupwith
thatmemberasanowner.Thisallowsmemberstostoreprivatepasswordsthatbelongtothe
organization,andsharethemwithothersinanadhocfashion(justliketheydonormallywiththe
servicefortheirprivatepasswords).

TwoFactorAuthenticationHowitworks
Theusergoesto/mitrocore/TwoFactorAuth/TwoFactorPreferencesbypressingalinkinthe
popuppage.Whentheuserdoesthat,atokensignedbytheuserandcontainingtheusers
emailaddressandanonceisalsosenttothe2fapreferencespage.Thepreferencespage
checksthetokenandsignaturecombination,andthenthepagedetermineswhether2fais
enabledordisabledbycheckingwhetheridentity.getTwoFactorSecret()isnull.Ifitisdisabled,
informationabout2faisdisplayed,andtheusercanpressanEnablebutton.Thisredirectto
mitrocore/TwoFactorAuth/NewUserandalsopassesinthetokenandsignature,bothofwhich
arethencheckedagain.Instructionsonhowtoenable2faaredisplayed,alongwithaQRcode
whichembedsboththeemailandarandomlygeneratedsecretinit,andaformtoinputthe
verificationcode.Afterenteringthecode,theuserisredirectedto
mitrocore/TwoFactorAuth/TempVerifyandpassesalongthetoken,signature,secret,and
verificationcode.Thecodeischecked,andifitiscorrect,thesecretisstoredinthedatabase
andbackupcodesareshown(theusermayonlyseethematthispointbecausetheyareone
wayhashed).Whenevertheusergoestothepreferencespageafterthat,itwilldisplaythat2fa
isenabled,thedateitwasenabled,howtodisableit,aswellashowtogeneratenewbackup
codes.
When2faisenabledandausersignsinfromanewdevice,GetMyPrivateKeywillthrougha
DoTwoFactorException.TherawMessageofthatexceptioncontainstheurltoopenanewtab
to.Thetabopenstomitrocore/TwoFactorAuthwithalogintokensignedbysigningKeyfrom
theservletTwoFactorAuth.Theuserinputsaverificationorbackupcode,andifitiscorrectisto
theloginpagewiththesametoken,exceptthetwoFactorAuthVerifiedpartofthetokenhasbeen
changedtotrue,fromfalse.Theloginpageparsesforatokenandtoken_signatureintheurl,and
ifitsthere(whichmeans2fawasjustcompleted),itchecksthesignatureandtoken.Ifthe
passwordinputtedthefirsttimetheloginscreenwasdisplayediscorrect,theuserisloggedin.
When2faisenabledandauserchangespasswords,theusermustfirstauthenticatewith2fa.It
workstheexactsamewayasforloggingin,exceptforthewaytheuserisredirected.Arequest
ismadetotheserver,askingwhether2faisenabled.Ifyes,aresponseissentbacktothe
extensioncontainingaurltoopenatabto(vsthrowinganexceptionandgettingtheurlfromthe
exceptionmessage).
Questions
Shouldwebuildthisontopofanexistingprotocol?E.g.isthisjustaprettyinterfaceto
PGP?X509?SSHkeys?
Doweidentifyusersbyemailaddress?Ifso,weneedtoverifytheemailaddressin
someway(e.g.GoogleAccount,sendingthemanemail).Whatiftheyhavemultiple
addresses?Whatiftheychangeit?
Forthepublicservice:Dopeopleowntheirownaccount(GitHub)andbelongto
(multiple?)organization(s)?Doorganizationsowntheiraccountsandtheclientcansign
intomultipleaccounts(Google)?
Iftherearemultipleservers,andtheclientissignedintomorethanone,howdowe
knowwhatuser@company.commeans?Whatifsomeonecreatesthataccountbothon
ourpublicserver,andonaprivateserver?
Howdoweauthenticateusers?Someenterprisesmaywantdifferentpolicies.
Howdowedealwithuniqueids(e.g.passwordids)?Shouldwebeworriedaboutleaking
datathatway?Ideally,idswouldbescopedperuser,butIdontseehowtomakethat
workwithsharing(easily).
Canweusetwofactorauthenticationinasmartway?
Howshouldweallowpeopletorecoverkeysincasetheyforgettheirpassword?How
shouldwepermitorganizations/enterprisestorecoverkeys?
Howshouldtheextensionverifythesitebeforeitfillstheformandclickssubmit?
Example:http://blog.chromium.org/2008/12/securityindepthpasswordmanager.html
Shouldwerequirerequeststobesignedwiththeprivatekey?Thisprovestheuserhas
accesstoit.Shouldwealsorequireanotherproofofidentity?E.g.wouldcouldrequire
BOTHaGoogleAccountloginandthekey?Doesthisimprovesecurity?