SecureDefaults for iOS, macOS

Requirements • Usage • Installation • Contributing • Acknowledgments • Contributing • Author • License

SecureDefaults is a wrapper over UserDefaults/NSUserDefaults with an extra AES-256 encryption layer (key size has 256-bit length). It encludes:

• AES-256 encryption
• Password stretching with PBKDF2
• Encrypt-then-hash HMAC
• Password salting
• Random IV

The design and strength of all key lengths of the AES algorithm (i.e., 128, 192 and 256) are sufficient to protect classified information up to the SECRET level. TOP SECRET information will require use of either the 192 or 256 key lengths. The implementation of AES in products intended to protect national security systems and/or information must be reviewed and certified by NSA prior to their acquisition and use. ^[1]

Motivation

• Avoiding the behavior of leaving keychain items behind when an app is uninstalled (although there may still be a key present, there is no data associated with it)
• Avoiding the decision-making process of determining the best location to store a particular value (Keychain vs. UserDefaults)
• Improving security on the iOS platform by encouraging the use of Keychain for storing sensitive data (such as access tokens and passwords) rather than using UserDefaults
• Avoiding the practice of storing many simple keys in Keychain, as this may not be the most effective use of the tool.

Requirements

• iOS 8.0+
• macOS 10.11+
• Xcode 10.1+
• Swift 4.2+

Usage

It is pretty simple to use SecureDefaults instead of UserDefaults/NSUserDefaults. In most cases, it is the same thing that is UserDefaults. You just need to set a password to make it work.

Replace the following code:

UserDefaults.standard

by this one:

let defaults = SecureDefaults.shared
// Ensures that a password has not already been set. 
// Setting a password multiple times will cause the key to be regenerated, 
// resulting in the loss of any previously encrypted data.
if !defaults.isKeyCreated {
    defaults.password = NSUUID().uuidString // Or any password you wish
}

To use the app and keychain groups:

let defaults = SecureDefaults(suitName: "app.group") // Sets a shared app group
defaults.keychainAccessGroup = "keychain.group" // Sets a shrared keychain group 
if !defaults.isKeyCreated {
    defaults.password = NSUUID().uuidString // Or any password you wish
}

SecureDefaults is not able to catch that any particular data is encrypted, to obtain a raw value, use the following method:

public func rawObject(forKey defaultName: String) -> Any?

Installation

CocoaPods

SecureDefaults is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'SecureDefaults', '1.1.0' # Swift 5.0

Carthage

Add this to Cartfile

github "vpeschenkov/SecureDefaults" == 1.1.0

$ carthage update

Swift Package Manager

Create a Package.swift file.

import PackageDescription

let package = Package(
  name: "YourProject",
  dependencies: [
    .package(url: "https://github.com/vpeschenkov/SecureDefaults", "1.1.0")
  ],
  targets: [
    .target(name: "YourProject", dependencies: ["SecureDefaults"])
  ]
)

$ swift build

Contributing

• If you need help or you'd like to ask a general question, open an issue.
• If you found a bug, open an issue.
• If you have a feature request, open an issue.
• If you want to contribute, submit a pull request.

Acknowledgments

A big thanks to the following individuals:

• Rob Napier - for this awesome article "Properly Encrypting With AES With CommonCrypto"
• Håvard Fossli - for this awesome Gist "AES 256 in swift 4 with CommonCrypto"

Author

Victor Peschenkov, v.peschenkov@gmail.com

License

SecureDefaults is available under the MIT license. See the LICENSE file for more info.