Sodium

Swift-Sodium

Swift-Sodium provides a safe and easy to use interface to perform common cryptographic operations on iOS and OSX.

It leverages the Sodium library, and although Swift is the primary target, the framework can also be used in Objective C.

Swift-Sodium requires Swift 2.0 (introduced in Xcode 7).

Usage

Add Sodium.framework as a dependency to your project, and import the module:

import Sodium

The Sodium library itself doesn't have to be installed on the system: the repository already includes a precompiled library for armv7, armv7s, arm64, as well as for the iOS simulator.

The libsodium-ios.a file has been generated by the dist-build/ios.sh script. The libsodium-osx.a file has been generated by the dist-build/osx.sh script.

Running these scripts on Xcode 7.0 (7A220) on the revision 342f209cbe1c1c05330b832abf5b6d39f698e685 of libsodium generate files identical to the ones present in this repository.

Public-key Cryptography

Authenticated Encryption

let sodium = Sodium()!
let aliceKeyPair = sodium.box.keyPair()!
let bobKeyPair = sodium.box.keyPair()!
let message: NSData = "My Test Message".toData()!

let encryptedMessageFromAliceToBob: NSData =
  sodium.box.seal(message,
                  recipientPublicKey: bobKeyPair.publicKey,
                  senderSecretKey: aliceKeyPair.secretKey)!

let messageVerifiedAndDecryptedByBob =
  sodium.box.open(encryptedMessageFromAliceToBob,
                  senderPublicKey: bobKeyPair.publicKey,
                  recipientSecretKey: aliceKeyPair.secretKey)

seal() automatically generates a nonce and prepends it to the ciphertext. open() extracts the nonce and decrypts the ciphertext.

The Box class also provides alternative functions and parameters to deterministically generate key pairs, to retrieve the nonce and/or the authenticator, and to detach them from the original message.

Anonymous Encryption (Sealed Boxes)

let sodium = Sodium()!
let bobKeyPair = sodium.box.keyPair()!
let message: NSData = "My Test Message".toData()!

let encryptedMessageToBob: NSData =
  sodium.box.seal(message, recipientPublicKey: bobKeyPair.publicKey)!

let messageDecryptedByBob =
  sodium.box.open(encryptedMessageToBob,
                  recipientPublicKey: bobKeyPair.publicKey,
                  recipientSecretKey: bobKeyPair.secretKey)

seal() generates an ephemeral keypair, uses the ephemeral secret key in the encryption process, combines the ephemeral public key with the ciphertext, then destroys the keypair. The sender can not decrypt the resulting ciphertext. open() extracts the public key and decrypts using the recipient's secret key. Message integrity is verified, but the sender's identity cannot be correlated to the ciphertext.

Public-key signatures

Detached signatures

let sodium = Sodium()!
let message = "My Test Message".toData()!
let keyPair = sodium.sign.keyPair()!
let signature = sodium.sign.signature(message, secretKey: keyPair.secretKey)!
if sodium.sign.verify(message,
                      publicKey: keyPair.publicKey,
                      signature: signature) {
  // signature is valid
}

Attached signatures

let sodium = Sodium()!
let message = "My Test Message".toData()!
let keyPair = sodium.sign.keyPair()!
let signedMessage = sodium.sign.sign(message, secretKey: keyPair.secretKey)!
if let unsignedMessage = sodium.sign.open(signedMessage, publicKey: keyPair.publicKey) {
  // signature is valid
}

Secret-key authenticated encryption

let message = "My Test Message".toData()!
let secretKey = sodium.secretBox.key()!
let encrypted: NSData = sodium.secretBox.seal(message, secretKey: secretKey)!
if let decrypted = sodium.secretBox.open(encrypted, secretKey: secretKey) {
  // authenticator is valid, decrypted contains the original message
}

Hashing

Deterministic hashing

let sodium = Sodium()!
let message = "My Test Message".toData()!
let h = sodium.genericHash.hash(message)

Keyed hashing

let sodium = Sodium()!
let message = "My Test Message".toData()!
let key = "Secret key".toData()!
let h = sodium.genericHash.hash(message, key: key)

Streaming

let sodium = Sodium()!
let (message1, message2) = ("My Test ".toData()!, "Message".toData()!)
let key = "Secret key".toData()!
let stream = sodium.genericHash.initStream(key)!
stream.update(message1)
stream.update(message2)
let h = stream.final()

Short-output hashing (SipHash)

let sodium = Sodium!
let message = "My Test Message".toData()!
let key = sodium.randomBytes.buf(ShortHash.KeyBytes)!
let h = sodium.shortHash.hash(message, key: key)

Random numbers generation

let sodium = Sodium()!
let randomData = sodium.randomBytes.buf(1000)

Password hashing

let sodium = Sodium()!
let password = "Correct Horse Battery Staple".toData()!
let hashedStr = sodium.pwHash.scrypt.str(password,
  opsLimit: sodium.pwHash.scrypt.OpsLimitInteractive,
  memLimit: sodium.pwHash.scrypt.MemLimitInteractive)!

if sodium.pwHash.scrypt.strVerify(hashStr, passwd: password) == false {
  // Password doesn't match the given hash string
}

Utilities

Zeroing memory

var dataToZero: NSMutableData
sodium.utils.zero(dataToZero)

Constant-time comparison

let secret1: NSData
let secret2: NSData
let equality = sodium.utils.equals(secret1, secret2)

Constant-time hexadecimal encoding

let data: NSData
let hex = sodium.utils.bin2hex(data)

Hexadecimal decoding

let data1 = sodium.utils.hex2bin("deadbeef")
let data2 = sodium.utils.hex2bin("de:ad be:ef", ignore: " :")

joshjdevl / swift-sodium