You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+84-56Lines changed: 84 additions & 56 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,8 +29,68 @@ script.
29
29
30
30
Running these scripts on Xcode 9.0 (`9A235`) on the revision `94550cefd5921c09a1ea352c759851b7ad0e592b` of libsodium generates files identical to the ones present in this repository.
31
31
32
+
## Secret-key cryptography
33
+
34
+
Messages are encrypted and decrypted using the same secret key.
35
+
36
+
That key can be generated using the `key()` method, derived from a password using the Password Hashing API, or computed using a secret key and the peer's public key with the Key Exchange API.
37
+
38
+
### Authenticated encryption for a sequence of messages
39
+
40
+
```swift
41
+
let sodium =Sodium()
42
+
let message1 ="Message 1".data(using:.utf8)!
43
+
let message2 ="Message 2".data(using:.utf8)!
44
+
let message3 ="Message 3".data(using:.utf8)!
45
+
46
+
let secretkey = sodium.secretStream.xchacha20poly1305.key()!
47
+
48
+
/* stream encryption */
49
+
50
+
let stream_enc = sodium.secretStream.xchacha20poly1305.initPush(secretKey: secretkey)!
51
+
let header = stream_enc.header()
52
+
let encrypted1 = stream_enc.push(message: message1)!
53
+
let encrypted2 = stream_enc.push(message: message2)!
54
+
let encrypted3 = stream_enc.push(message: message3, tag: .FINAL)!
55
+
56
+
/* stream decryption */
57
+
58
+
let stream_dec = sodium.secretStream.xchacha20poly1305.initPull(secretKey: secretkey, header: header)!
59
+
let (message1_dec, tag1) = stream_dec.pull(cipherText: encrypted1)!
60
+
let (message2_dec, tag2) = stream_dec.pull(cipherText: encrypted2)!
61
+
let (message3_dec, tag3) = stream_dec.pull(cipherText: encrypted3)!
62
+
```
63
+
64
+
A stream is a sequence of messages, that will be encrypted as they arrive, and that are expected to be received in the same order as they were received.
65
+
66
+
Streams can be arbitrary long. This API can thus be used for file encryption, by splitting files into small chunks so that the whole content doesn't need to fit in memory.
67
+
68
+
It can also be used to exchange a sequence of messages between two peers.
69
+
70
+
The decryption function automatically checks that chunks have been received without modification, and truncation or reordering.
71
+
72
+
A tag is attached to each message, and can be used to signal the end of a sub-sequence (`PUSH`), or the end of the string (`FINAL`).
73
+
74
+
### Authenticated encryption for independent messages
75
+
76
+
```swift
77
+
let sodium =Sodium()
78
+
let message ="My Test Message".data(using:.utf8)!
79
+
let secretKey = sodium.secretBox.key()!
80
+
let encrypted: Data = sodium.secretBox.seal(message: message, secretKey: secretKey)!
// authenticator is valid, decrypted contains the original message
83
+
}
84
+
```
85
+
86
+
This API encrypts a message. The decryption process check that they haven't been tampered with before decrypting them.
87
+
88
+
Messages encrypted that way are independent: if multiple messages are sent that way, the recipient cannot detect if some messages have been duplicated, deleted or reordered without including additional data to each message.
89
+
32
90
## Public-key Cryptography
33
91
92
+
With public-key cryptography, each peer has two keys: a secret key, that has to remain secret, and a public key that anyone can use to send an encrypted message to that peer. That public key can be only be used to encrypt a message. The related secret is required to decrypt it.
93
+
34
94
### Authenticated Encryption
35
95
36
96
```swift
@@ -80,8 +140,30 @@ let messageDecryptedByBob =
80
140
81
141
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.
82
142
143
+
## Key exchange
144
+
145
+
```swift
146
+
let sodium =Sodium()
147
+
let aliceKeyPair = sodium.keyExchange.keyPair()!
148
+
let bobKeyPair = sodium.keyExchange.keyPair()!
149
+
150
+
let sessionKeyPairForAlice = sodium.keyExchange.sessionKeyPair(publicKey: aliceKeyPair.publicKey,
let aliceToBobKeyEquality = sodium.utils.equals(sessionKeyPairForAlice.tx, sessionKeyPairForBob.xx) // true
237
-
let bobToAliceKeyEquality = sodium.utils.equals(sessionKeyPairForAlice.rx, sessionKeyPairForBob.tx) // true
238
-
```
239
-
240
266
## Authentication tags
241
267
242
268
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.
0 commit comments