Git Product home page Git Product logo

valet's Introduction

Valet

Valet lets you securely store data in the iOS or OS X Keychain without knowing a thing about how the Keychain works. It’s easy. We promise.

Getting Started

To install Valet in your iOS or OS X project, install with CocoaPods

on iOS:

platform :ios, '6.0'
pod 'Valet'

on OS X:

platform :osx, '10.9'
pod 'Valet'

Or manually checkout the submodule with git submodule add [email protected]:Square/Valet.git, drag Valet.xcodeproj to your project, and add Valet as a build dependency.

Usage

Basic Initialization

VALValet *myValet = [[VALValet alloc] initWithIdentifier:@"Druidia" accessibility:VALAccessibilityWhenUnlocked];

To begin storing data securely using Valet, you need to create a VALValet instance with:

  • An identifier – a string that is used to identify this Valet.
  • An accessibility value – an enum (VALAccessibility) that defines when you will be able to store and retrieve data.

This instance can be used to store and retrieve data securely, but only when the device is unlocked.

Choosing the Best Accessibility Value

The VALAccessibility enum is used to determine when your secrets can be accessed. It’s a good idea to use the strictest accessibility possible that will allow your app to function. For example, if your app does not run in the background you will want to ensure the secrets can only be read when the phone is unlocked by using VALAccessibilityWhenUnlocked or VALAccessibilityWhenUnlockedThisDeviceOnly.

Reading and Writing

NSString *const username = @"Skroob";
[myValet setString:@"12345" forKey:username];
NSString *const myLuggageCombination = [myValet stringForKey:username];

Valet’s API for securely reading and writing data is similar to that of an NSMapTable; use -setObject:forKey: and -setString:forKey: to write objects and -objectForKey: and -stringForKey: to read objects. Valets created with a different class type, via a different initializer, or with a different identifier or accessibility attribute will not be able to read or modify values in myValet.

Sharing Secrets Among Multiple Applications

VALValet *mySharedValet = [[VALValet alloc] initWithSharedAccessGroupIdentifier:@"Druidia" accessibility:VALAccessibilityWhenUnlocked];

This instance can be used to store and retrieve data securely across any app writen by the same developer with the value Druidia under the keychain-access-groups key in the app’s Entitlements file, when the device is unlocked. myValet and mySharedValet can not read or modify one another’s values because the two Valets were created with different initializers. You can use the -initWithSharedAccessGroupIdentifier:accessibility: initializer on any Valet class to allow for sharing secrets across applications written by the same developer.

Sharing Secrets Across Devices with iCloud

VALSynchronizableValet *mySynchronizableValet = [[VALSynchronizableValet alloc] initWithIdentifier:@"Druidia" accessibility:VALAccessibilityWhenUnlocked];

This instance can be used to store and retrieve data that can be retrieved by this app on other devices logged into the same iCloud account with iCloud Keychain enabled. mySynchronizableValet can not read or modify values in myValet or mySharedValet because mySynchronizableValet is of a different class type. If iCloud Keychain is not enabled on this device, secrets can still be read and written, but will not sync to other devices.

Protecting Secrets with Touch ID or iOS Passcode

VALSecureEnclaveValet *mySecureEnclaveValet = [[VALSecureEnclaveValet alloc] initWithIdentifier:@"Druidia"];

This instance can be used to store and retrieve data in the Secure Enclave (supported on iOS 8.0 or later). Reading or modifying items in this Valet will require the user to confirm their presence via Touch ID or by entering their iOS passcode. If no passcode is set on the device, this instance will be unable to access or store data. Data is removed from the Secure Enclave when the user removes a passcode from the device. Storing data using VALSecureEnclaveValet is the most secure way to store data on iOS.

Migrating Existing Keychain Values into Valet

Already using the Keychain and no longer want to maintain your own Keychain code? We feel you. That’s why we wrote -migrateObjectsMatchingQuery:removeOnCompletion:. This method allows you to migrate all your existing Keychain entries to a Valet instance in one line. Just pass in an NSDictionary with the kSecClass, kSecAttrService, and any other kSecAttr* attributes you use – we’ll migrate the data for you.

Contributing

We’re glad you’re interested in Valet, and we’d love to see where you take it.

Any contributors to the master Valet repository must sign the Individual Contributor License Agreement (CLA). It’s a short form that covers our bases and makes sure you’re eligible to contribute.

When you have a change you’d like to see in the master repository, send a pull request. Before we merge your request, we’ll make sure you’re in the list of people who have signed a CLA.

Thanks, and please do take it for a joyride!

valet's People

Contributors

brianpartridge avatar danielribeiro avatar dfed avatar ericmuller22 avatar mthole avatar pwesten avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.