From 36b11e35a88009461852cdead990243d73422317 Mon Sep 17 00:00:00 2001 From: Frank Denis Date: Sat, 23 Sep 2017 21:31:43 +0200 Subject: [PATCH] Reformat --- README.md | 165 ++++++++++++++++++------------------------------------ 1 file changed, 55 insertions(+), 110 deletions(-) diff --git a/README.md b/README.md index 853119d6..62cf0d71 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,22 @@ # Sodium [![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage) + [![Make a donation to support this project](https://img.shields.io/badge/donate-PayPal-green.svg?style=flat)](https://www.libsodium.org/donate) -Swift-Sodium -============ +# Swift-Sodium -Swift-Sodium provides a safe and easy to use interface to perform -common cryptographic operations on iOS and OSX. +Swift-Sodium provides a safe and easy to use interface to perform common cryptographic operations on iOS and OSX. -It leverages the [Sodium](https://download.libsodium.org/doc/) library, -and although Swift is the primary target, the framework can also be used in -Objective C. +It leverages the [Sodium](https://download.libsodium.org/doc/) library, and although Swift is the primary target, the framework can also be used in Objective C applications. -Usage -===== +## Usage Add `Sodium.framework` as a dependency to your project, and import the module: + ```swift 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 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. It targets Swift 4, introduced in Xcode 9.0. @@ -32,15 +27,11 @@ The `libsodium-osx.a` file has been generated by the [dist-build/osx.sh](https://github.com/jedisct1/libsodium/blob/master/dist-build/osx.sh) script. -Running these scripts on Xcode 9.0 (`9A235`) on the revision -`94550cefd5921c09a1ea352c759851b7ad0e592b` of libsodium generates files -identical to the ones present in this repository. +Running these scripts on Xcode 9.0 (`9A235`) on the revision `94550cefd5921c09a1ea352c759851b7ad0e592b` of libsodium generates files identical to the ones present in this repository. -Public-key Cryptography -======================= +## Public-key Cryptography -Authenticated Encryption ------------------------- +### Authenticated Encryption ```swift let sodium = Sodium(())! @@ -59,18 +50,17 @@ let messageVerifiedAndDecryptedByBob = recipientSecretKey: bobKeyPair.secretKey) ``` -`seal()` automatically generates a nonce and prepends it to the -ciphertext. `open()` extracts the nonce and decrypts the ciphertext. +This operation encrypts and sends a message to someone using their public key. + +The recipient has to know the sender's public key as well, and will reject a message that doesn't appear to be valid for the expected public key. -Optionally, `Box` provides the ability to utilize a user-defined nonce via -`seal(message: recipientPublicKey: senderSecretKey: nonce:)`. +`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. +Optionally, `Box` provides the ability to utilize a user-defined nonce via `seal(message: recipientPublicKey: senderSecretKey: nonce:)`. -Anonymous Encryption (Sealed Boxes) ------------------------------------ +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) ```swift let sodium = Sodium() @@ -86,18 +76,13 @@ let messageDecryptedByBob = 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. +`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 -===================== +## Public-key signatures -Detached signatures -------------------- +### Detached signatures ```swift let sodium = Sodium() @@ -111,8 +96,7 @@ if sodium.sign.verify(message: message, } ``` -Attached signatures -------------------- +### Attached signatures ```swift let sodium = Sodium() @@ -124,11 +108,9 @@ if let unsignedMessage = sodium.sign.open(signedMessage: signedMessage, publicKe } ``` -Secret-key authenticated encryption -=================================== +## Secret-key authenticated encryption -Authenticated encryption for a sequence of messages ---------------------------------------------------- +### Authenticated encryption for a sequence of messages ```swift let sodium = Sodium() @@ -154,8 +136,7 @@ let (message2_dec, tag2) = stream_dec.pull(cipherText: encrypted2)! let (message3_dec, tag3) = stream_dec.pull(cipherText: encrypted3)! ``` -Authenticated encryption for independent messages -------------------------------------------------- +### Authenticated encryption for independent messages ```swift let sodium = Sodium() @@ -167,11 +148,9 @@ if let decrypted = sodium.secretBox.open(nonceAndAuthenticatedCipherText: encryp } ``` -Hashing -======= +## Hashing -Deterministic hashing ---------------------- +### Deterministic hashing ```swift let sodium = Sodium() @@ -179,8 +158,7 @@ let message = "My Test Message".data(using:.utf8)! let h = sodium.genericHash.hash(message: message) ``` -Keyed hashing -------------- +### Keyed hashing ```swift let sodium = Sodium() @@ -189,8 +167,7 @@ let key = "Secret key".data(using:.utf8)! let h = sodium.genericHash.hash(message: message, key: key) ``` -Streaming ---------- +### Streaming ```swift let sodium = Sodium() @@ -203,8 +180,7 @@ stream.update(input: message2) let h = stream.final() ``` -Short-output hashing (SipHash) -============================== +### Short-output hashing (SipHash) ```swift let sodium = Sodium() @@ -213,8 +189,7 @@ let key = sodium.randomBytes.buf(length: sodium.shortHash.KeyBytes)! let h = sodium.shortHash.hash(message: message, key: key) ``` -Random numbers generation -========================= +## Random numbers generation ```swift let sodium = Sodium() @@ -223,8 +198,7 @@ let seed = "0123456789abcdef0123456789abcdef".data(using:.utf8)! let stream = sodium.randomBytes.deterministic(length: 1000, seed: seed)! ``` -Password hashing -================ +## Password hashing ```swift let sodium = Sodium() @@ -247,8 +221,7 @@ if sodium.pwHash.strNeedsRehash(hash: hashedStr, } ``` -Key exchange -============ +## Key exchange ```swift let sodium = Sodium() @@ -264,17 +237,11 @@ let aliceToBobKeyEquality = sodium.utils.equals(sessionKeyPairForAlice.tx, sessi let bobToAliceKeyEquality = sodium.utils.equals(sessionKeyPairForAlice.rx, sessionKeyPairForBob.tx) // true ``` -Authentication tags -=================== +## Authentication tags -The `sodium.auth.tag()` function computes an authentication tag (HMAC) using -a message and a key. Parties knowing the key can then verify the authenticity -of the message using the same parameters and the `sodium.auth.verify()` -function. +The `sodium.auth.tag()` function computes an authentication tag (HMAC) using a message and a key. Parties knowing the key can then verify the authenticity of the message using the same parameters and the `sodium.auth.verify()` function. -Authentication tags are not signatures: the same key is used both for -computing and verifying a tag. Therefore, verifiers can also compute -tags for arbitrary messages. +Authentication tags are not signatures: the same key is used both for computing and verifying a tag. Therefore, verifiers can also compute tags for arbitrary messages. ```swift let sodium = Sodium() @@ -284,13 +251,9 @@ let tag = sodium.auth.tag(message: input, secretKey: key)! let tagIsValid = sodium.auth.verify(message: input, secretKey: key, tag: tag) ``` -Key derivation -============== +## Key derivation -The `sodium.keyDerivation.derive()` function generates a subkey using -an input (master) key, an index, and a 8 bytes string identifying the -context. Up to (2^64) - 1 subkeys can be generated for each context, -by incrementing the index. +The `sodium.keyDerivation.derive()` function generates a subkey using an input (master) key, an index, and a 8 bytes string identifying the context. Up to (2^64) - 1 subkeys can be generated for each context, by incrementing the index. ```swift let sodium = Sodium() @@ -304,11 +267,9 @@ let subKey2 = sodium.keyDerivation.derive(secretKey: secretKey, context: "Context!") ``` -Utilities -========= +## Utilities -Zeroing memory --------------- +### Zeroing memory ```swift let sodium = Sodium() @@ -316,8 +277,7 @@ var dataToZero = "Message".data(using:.utf8)! sodium.utils.zero(&dataToZero) ``` -Constant-time comparison ------------------------- +### Constant-time comparison ```swift let sodium = Sodium() @@ -326,8 +286,7 @@ let secret2 = "Secret key".data(using:.utf8)! let equality = sodium.utils.equals(secret1, secret2) ``` -Padding -------- +### Padding ```swift let sodium = Sodium() @@ -340,8 +299,7 @@ sodium.utils.pad(data: &data, blockSize: 16)! sodium.utils.unpad(data: &data, blockSize: 16)! ``` -Constant-time hexadecimal encoding ----------------------------------- +### Constant-time hexadecimal encoding ```swift let sodium = Sodium() @@ -349,8 +307,7 @@ let data = "Secret key".data(using:.utf8)! let hex = sodium.utils.bin2hex(data) ``` -Hexadecimal decoding --------------------- +### Hexadecimal decoding ```swift let sodium = Sodium() @@ -358,8 +315,7 @@ let data1 = sodium.utils.hex2bin("deadbeef") let data2 = sodium.utils.hex2bin("de:ad be:ef", ignore: " :") ``` -Constant-time base64 encoding ------------------------------ +### Constant-time base64 encoding ```swift let sodium = Sodium() @@ -367,8 +323,7 @@ let b64 = sodium.utils.bin2base64("data".toData()!)! let b64_2 = sodium.utils.bin2base64("data".toData()!, variant: .URLSAFE_NO_PADDING)! ``` -Base64 decoding ---------------- +### Base64 decoding ```swift let data1 = sodium.utils.base642bin(b64) @@ -376,29 +331,19 @@ let data2 = sodium.utils.base642bin(b64, ignore: " \n") let data3 = sodium.utils.base642bin(b64_2, variant: .URLSAFE_NO_PADDING, ignore: " \n") ``` -Helpers to build custom constructions -===================================== +## Helpers to build custom constructions -Only use the functions below if you know that you absolutely need -them, and know how to use them correctly. +Only use the functions below if you know that you absolutely need them, and know how to use them correctly. -Unauthenticated encryption --------------------------- +## Unauthenticated encryption -The `sodium.stream.xor()` function combines (using the XOR operation) -an arbitrary-long input with the output of a deterministic key stream -derived from a key and a nonce. The same operation applied twice -produces the original input. +The `sodium.stream.xor()` function combines (using the XOR operation) an arbitrary-long input with the output of a deterministic key stream derived from a key and a nonce. The same operation applied twice produces the original input. -No authentication tag is added to the output. The data can be tampered -with; an adversary can flip arbitrary bits. +No authentication tag is added to the output. The data can be tampered with; an adversary can flip arbitrary bits. -In order to encrypt data using a secret key, the `SecretBox` class is -likely to be what you are looking for. +In order to encrypt data using a secret key, the `SecretBox` class is likely to be what you are looking for. -In order to generate a deterministic stream out of a seed, the -`RandomBytes.deterministic_rand()` function is likely to be what you -need. +In order to generate a deterministic stream out of a seed, the `RandomBytes.deterministic_rand()` function is likely to be what you need. ```swift let sodium = Sodium()