A quick deck on how Clef's security architecture works.

1. CLEF SECURITY ARCHITECTURE
GETCLEF.COM/SECURE

2. OVERVIEW
Logging in with Clef
1.
Unique id sent to browser and
displayed as wave
2.
Phone’s camera used to scan
wave and transfer id
3.
Private key on phone used to
generate signature with id and
timestamp- sent to Clef Server
4.
Signature verified and OAuth
Code sent to browser
5.
Redirect in browser sends
OAuth Code to Site Server
6.
OAuth Handshake between Clef
Server and Site Server
7.
User info sent to Site Server
8.
User is logged in to site

3. SETUP

4. Registration on the Phone
• User downloads app
• Email address confirmed, PIN set up
• 2048-bit RSA key pair generated on phone
• Public key sent to server and stored
• Private key encrypted on device
• for iOS—KeychainServices for hardware encryption
• for Android—PIN-based encryption (PKCS#5)

5. Registering a New Site
• Developer creates account at
developer.getclef.com
• Developer receives App ID and App Secret
• <script> tag with App ID embedded in login form
• Standard code to handle OAuth 2.0 Handshake

6. LOGGING IN

7. Generating the Clef Wave
• <script> creates “Log in with Clef” button
• On user click, loads iframe from Clef Server
• iframe requests unique id (Session Key)
• Session Key is stored as a signed cookie
• displayed as animated barcode, the Clef Wave

8. Scanning the Clef Wave
• User opens Clef App on their smartphone
• Enters PIN to unlock the app
• On-screen guide instructs user to sync Clef Wave
• Phone’s camera reads Session Key from Clef
Wave

9. Verifying the Signature
• Signature is generated with Session Key, user id,
and current timestamp
• Signature is sent to Clef Server over TLS/SSL
• Clef Server verifies signature using stored public
key
• Timestamp is checked for recency to prevent
replay attacks

10. OAuth 2.0 Handshake
!
• Clef server generates OAuth code and pushes to browser
using WebSockets
• Browser redirects to site’s specified redirect URL with
OAuth code to initiate OAuth 2.0 handshake
• Site Server sends OAuth code, App ID, App Secret to Clef
Server for verification
• Clef Server returns OAuth token
• Site Server exchanges OAuth token for user information

11. Finishing the Login
• Site receives user information from Clef Server,
including site-specific identifier (clef_id)
• Site looks up user in database with clef_id
• Site sets a cookie to manage user’s session
• User is redirected to logged-in page

12. LOGGING OUT

13. Single Sign Off
• Site specifies a logout webhook URL on
developer.getclef.com
• User taps “log out” on phone (or logout timer
expires), signed logout request sent to Clef Server
• Clef server notifies each site of the logout via their
webhook URL

14. Database Logout
• Site stores login timestamp as part of session
• When webhook is triggered, site stores time of
logout in database
• On page request, site compares both timestamps
to determine whether user has logged out

15. LOST DEVICE

16. Deactivating a Lost Device
• A phone can be reported lost or stolen on
getclef.com/lost
• Notifications are sent through available channels
alerting user of attempted deactivation
• 24 hour wait period before deactivation, can be
skipped by verifying through email
• Public key is wiped from Clef Server after wait
period or verification

17. After Deactivation
• Temporary passcode is granted after deactivation
• Passcode can be used to log in at getclef.com
• Because of single sign on, allows access to all
connected services

18. Reactivation
• User reconfirms email address and PIN
• RSA key pair is generated on new device
• New public key is associated with old account

19. REQUIREMENTS

20. Smartphone Requirements
• Android or iOS device with camera
• Android minimum SDK version: 2.3
• iOS minimum SDK version: 5.0
• Device must be networked

21. Verification Server
Requirements
• Able to run Python code, SQL database server
• Network-accessible from smartphones and
consoles

22. Console Requirements
• Visual display for Clef Wave
• Networked with access to Verification Server
• Ability to look up users and store timestamps (for
logout)

23. USING CLEF ON AN
INTRANET

24. Replacing OAuth 2.0
• If within a completely trusted environment, no
need to do any handshake
• Otherwise, can replace OAuth 2.0 with asymmetric
cryptography between Verification Server and
Consoles

25. Networking Devices
• Both phone and console must be able to
communicate with Verification Server
• No dependency on Internet

26. White-labeled App
• Clef functionality wrapped in client app
• Configured to work only within intranet
• BYOD compatible
• Available for iOS and Android devices

27. OTHER POSSIBLE FEATURES

28. Device Fingerprinting
• Prevents device spoofing
• Hardware IDs
• Geolocation
• OS-level IDs
• Hardware clock-skew
• Device type and configuration

29. Geofencing
• Logins will be happening within a small geofence
• Using device location can prevent external attacks
• Force logout when user leaves fence

30. Automatic Logouts
• As users move from console to console, they must
log out each time
• Use geolocation, Bluetooth, or NFC to make this
automatic
• Reduce vulnerability through carelessness