Release 2.4.0

README.md

@@ -3,7 +3,7 @@
 SwiftChaChaPoly implements Authenticated Encryption with Associated Data as defined in [RFC-8439].  
 It is based on the ChaCha20 stream cipher and Poly1305 authentication.
 
-Its documentation is build with the DocC tool and published on GitHub Pages at this location:
+Its documentation is build with the DocC plugin and published on GitHub Pages at this location:
 
 https://leif-ibsen.github.io/SwiftChaChaPoly/documentation/swiftchachapoly
 

Sources/SwiftChaChaPoly/ChaChaPoly.swift

@@ -7,6 +7,7 @@
 
 /// Unsigned 8 bit value
 public typealias Byte = UInt8
+
 /// Array of unsigned 8 bit values
 public typealias Bytes = [UInt8]
 
@@ -15,9 +16,7 @@ public struct ChaChaPoly {
 
     // MARK: Exceptions
 
-    ///
-    /// ChaChaPoly exceptions
-    ///
+    /// The ChaChaPoly exceptions
     public enum Ex: Error, CustomStringConvertible {
 
         /// Textual description of `self`

Sources/SwiftChaChaPoly/SwiftChaChaPoly.docc/Articles/CryptoKit.md

@@ -1,8 +1,9 @@
 # CryptoKit Compatibility
 
+SwiftChaChaPoly is compatible with Apple's CryptoKit framework
+
 ## 
 
-SwiftChaChaPoly is compatible with Apple's CryptoKit framework as the following examples show:
 
 ### Example 1
 

Sources/SwiftChaChaPoly/SwiftChaChaPoly.docc/Articles/Performance.md

@@ -1,6 +1,9 @@
 # Performance
 
+Encryption and decryption speed
+
 ## 
+
 The encryption and decryption speed was measured on a iMac 2021, Apple M1 chip. The results are:
 
 * Encryption: 290 MBytes / sec (11 cycles / byte)

Sources/SwiftChaChaPoly/SwiftChaChaPoly.docc/Articles/References.md

@@ -1,9 +1,8 @@
 # References
 
-## 
+Algorithms from the following papers have been used in the implementation
 
-Algorithms from the following papers have been used in the implementation.
-There are references in the source code where appropriate.
+## 
 
 * [FILIPPO] - Filippo Valsorda: A GO IMPLEMENTATION OF POLY1305 THAT MAKES SENSE, April 2019
 * [RFC 8439] - ChaCha20 and Poly1305 for IETF Protocols, June 2018

Sources/SwiftChaChaPoly/SwiftChaChaPoly.docc/Extensions/ExExtension.md

@@ -5,4 +5,3 @@
 ### Properties
 
 - ``description``
-

Sources/SwiftChaChaPoly/SwiftChaChaPoly.docc/SwiftChaChaPoly.md

@@ -1,19 +1,72 @@
 # ``SwiftChaChaPoly``
 
+Authenticated Encryption with Associated Data
+
 ## Overview
 
 SwiftChaChaPoly implements Authenticated Encryption with Associated Data as defined in [RFC 8439].
 
 It is based on the ChaCha20 stream cipher and Poly1305 authentication.
 
+### Example
+
+```swift
+import SwiftChaChaPoly
+
+// This example is from section 2.8.2 in [RFC 8439].
+
+let key: Bytes = [
+    0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8a, 0x8b, 0x8c, 0x8d, 0x8e, 0x8f,
+    0x90, 0x91, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9a, 0x9b, 0x9c, 0x9d, 0x9e, 0x9f]
+let nonce: Bytes = [
+    0x07, 0x00, 0x00, 0x00, 0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47]
+let aad: Bytes = [
+    0x50, 0x51, 0x52, 0x53, 0xc0, 0xc1, 0xc2, 0xc3, 0xc4, 0xc5, 0xc6, 0xc7]
+let text = "Ladies and Gentlemen of the class of '99: If I could offer you only one tip for the future, sunscreen would be it."
+
+var bytes = Bytes(text.utf8)
+
+let chacha = try ChaChaPoly(key, nonce)
+let tag = chacha.encrypt(&bytes, aad)
+print(tag)
+let ok = chacha.decrypt(&bytes, tag, aad)
+print(ok && bytes == Bytes(text.utf8) ? "Ok" : "Fail")
+```
+Giving
+```swift
+[26, 225, 11, 89, 79, 9, 226, 106, 126, 144, 46, 203, 208, 96, 6, 145]
+Ok
+```
+
+### Usage
+
+To use SwiftChaChaPoly, in your project *Package.swift* file add a dependency like
+
+```swift
+dependencies: [
+  .package(url: "https://github.com/leif-ibsen/SwiftChaChaPoly", from: "2.4.0"),
+]
+```
+
+SwiftChaChaPoly itself does not depend on other packages.
+
 > Important:
 SwiftChaChaPoly requires Swift 5.0. It also requires that the `Int` and `UInt` types be 64 bit types.
 
 ## Topics
 
-- <doc:Usage>
-- <doc:Example>
+### Structures
+
+- ``ChaChaPoly``
+
+### Type Aliases
+
+- ``SwiftChaChaPoly/Byte``
+- ``SwiftChaChaPoly/Bytes``
+
+### Additional Information
+
 - <doc:CryptoKit>
 - <doc:Performance>
-- <doc:Dependencies>
 - <doc:References>
+

SwiftChaChaPoly.doccarchive/data/documentation/swiftchachapoly.json

@@ -1 +1 @@
-{"sections":[],"identifier":{"interfaceLanguage":"swift","url":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly"},"topicSections":[{"identifiers":["doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Usage","doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Example","doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/CryptoKit","doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Performance","doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Dependencies","doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/References"]},{"title":"Structures","identifiers":["doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/ChaChaPoly"]},{"identifiers":["doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Byte","doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Bytes"],"title":"Type Aliases"}],"variants":[{"paths":["\/documentation\/swiftchachapoly"],"traits":[{"interfaceLanguage":"swift"}]}],"hierarchy":{"paths":[[]]},"primaryContentSections":[{"kind":"content","content":[{"anchor":"Overview","level":2,"text":"Overview","type":"heading"},{"inlineContent":[{"text":"SwiftChaChaPoly implements Authenticated Encryption with Associated Data as defined in [RFC 8439].","type":"text"}],"type":"paragraph"},{"inlineContent":[{"type":"text","text":"It is based on the ChaCha20 stream cipher and Poly1305 authentication."}],"type":"paragraph"},{"type":"aside","name":"Important","content":[{"type":"paragraph","inlineContent":[{"text":"","type":"text"},{"text":" ","type":"text"},{"text":"SwiftChaChaPoly requires Swift 5.0. It also requires that the ","type":"text"},{"type":"codeVoice","code":"Int"},{"text":" and ","type":"text"},{"type":"codeVoice","code":"UInt"},{"text":" types be 64 bit types.","type":"text"}]}],"style":"important"}]}],"schemaVersion":{"major":0,"patch":0,"minor":3},"kind":"symbol","metadata":{"modules":[{"name":"SwiftChaChaPoly"}],"symbolKind":"module","externalID":"SwiftChaChaPoly","roleHeading":"Framework","role":"collection","title":"SwiftChaChaPoly"},"references":{"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/Dependencies":{"url":"\/documentation\/swiftchachapoly\/dependencies","type":"topic","title":"Dependencies","role":"article","kind":"article","abstract":[],"identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Dependencies"},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/References":{"url":"\/documentation\/swiftchachapoly\/references","identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/References","abstract":[],"role":"article","kind":"article","title":"References","type":"topic"},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/Example":{"url":"\/documentation\/swiftchachapoly\/example","abstract":[],"role":"article","kind":"article","identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Example","type":"topic","title":"Example"},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/Usage":{"url":"\/documentation\/swiftchachapoly\/usage","type":"topic","kind":"article","role":"article","title":"Usage","identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Usage","abstract":[]},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/Performance":{"url":"\/documentation\/swiftchachapoly\/performance","abstract":[],"role":"article","kind":"article","identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Performance","type":"topic","title":"Performance"},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly":{"url":"\/documentation\/swiftchachapoly","type":"topic","title":"SwiftChaChaPoly","role":"collection","kind":"symbol","abstract":[],"identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly"},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/CryptoKit":{"url":"\/documentation\/swiftchachapoly\/cryptokit","abstract":[],"role":"article","kind":"article","identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/CryptoKit","type":"topic","title":"CryptoKit Compatibility"},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/ChaChaPoly":{"type":"topic","url":"\/documentation\/swiftchachapoly\/chachapoly","kind":"symbol","role":"symbol","navigatorTitle":[{"kind":"identifier","text":"ChaChaPoly"}],"title":"ChaChaPoly","identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/ChaChaPoly","fragments":[{"text":"struct","kind":"keyword"},{"kind":"text","text":" "},{"kind":"identifier","text":"ChaChaPoly"}],"abstract":[{"type":"text","text":"The ChaChaPoly structure"}]},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/Bytes":{"fragments":[{"kind":"keyword","text":"typealias"},{"kind":"text","text":" "},{"kind":"identifier","text":"Bytes"}],"identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Bytes","kind":"symbol","abstract":[{"text":"Array of unsigned 8 bit values","type":"text"}],"url":"\/documentation\/swiftchachapoly\/bytes","role":"symbol","type":"topic","title":"Bytes","navigatorTitle":[{"text":"Bytes","kind":"identifier"}]},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/Byte":{"fragments":[{"text":"typealias","kind":"keyword"},{"kind":"text","text":" "},{"kind":"identifier","text":"Byte"}],"identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Byte","kind":"symbol","abstract":[{"type":"text","text":"Unsigned 8 bit value"}],"url":"\/documentation\/swiftchachapoly\/byte","role":"symbol","type":"topic","title":"Byte","navigatorTitle":[{"kind":"identifier","text":"Byte"}]}}}
+{"kind":"symbol","sections":[],"identifier":{"interfaceLanguage":"swift","url":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly"},"variants":[{"traits":[{"interfaceLanguage":"swift"}],"paths":["\/documentation\/swiftchachapoly"]}],"metadata":{"roleHeading":"Framework","modules":[{"name":"SwiftChaChaPoly"}],"title":"SwiftChaChaPoly","externalID":"SwiftChaChaPoly","role":"collection","symbolKind":"module"},"hierarchy":{"paths":[[]]},"schemaVersion":{"minor":3,"patch":0,"major":0},"abstract":[{"type":"text","text":"Authenticated Encryption with Associated Data"}],"topicSections":[{"title":"Structures","identifiers":["doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/ChaChaPoly"]},{"title":"Type Aliases","identifiers":["doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Byte","doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Bytes"]},{"title":"Additional Information","identifiers":["doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/CryptoKit","doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Performance","doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/References"]}],"primaryContentSections":[{"content":[{"level":2,"anchor":"Overview","text":"Overview","type":"heading"},{"inlineContent":[{"type":"text","text":"SwiftChaChaPoly implements Authenticated Encryption with Associated Data as defined in [RFC 8439]."}],"type":"paragraph"},{"type":"paragraph","inlineContent":[{"type":"text","text":"It is based on the ChaCha20 stream cipher and Poly1305 authentication."}]},{"anchor":"Example","level":3,"text":"Example","type":"heading"},{"syntax":"swift","code":["import SwiftChaChaPoly","","\/\/ This example is from section 2.8.2 in [RFC 8439].","","let key: Bytes = [","    0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8a, 0x8b, 0x8c, 0x8d, 0x8e, 0x8f,","    0x90, 0x91, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9a, 0x9b, 0x9c, 0x9d, 0x9e, 0x9f]","let nonce: Bytes = [","    0x07, 0x00, 0x00, 0x00, 0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47]","let aad: Bytes = [","    0x50, 0x51, 0x52, 0x53, 0xc0, 0xc1, 0xc2, 0xc3, 0xc4, 0xc5, 0xc6, 0xc7]","let text = \"Ladies and Gentlemen of the class of '99: If I could offer you only one tip for the future, sunscreen would be it.\"","","var bytes = Bytes(text.utf8)","","let chacha = try ChaChaPoly(key, nonce)","let tag = chacha.encrypt(&bytes, aad)","print(tag)","let ok = chacha.decrypt(&bytes, tag, aad)","print(ok && bytes == Bytes(text.utf8) ? \"Ok\" : \"Fail\")"],"type":"codeListing"},{"inlineContent":[{"type":"text","text":"Giving"}],"type":"paragraph"},{"type":"codeListing","code":["[26, 225, 11, 89, 79, 9, 226, 106, 126, 144, 46, 203, 208, 96, 6, 145]","Ok"],"syntax":"swift"},{"text":"Usage","anchor":"Usage","type":"heading","level":3},{"type":"paragraph","inlineContent":[{"type":"text","text":"To use SwiftChaChaPoly, in your project "},{"type":"emphasis","inlineContent":[{"text":"Package.swift","type":"text"}]},{"text":" file add a dependency like","type":"text"}]},{"code":["dependencies: [","  .package(url: \"https:\/\/github.com\/leif-ibsen\/SwiftChaChaPoly\", from: \"2.4.0\"),","]"],"type":"codeListing","syntax":"swift"},{"inlineContent":[{"type":"text","text":"SwiftChaChaPoly itself does not depend on other packages."}],"type":"paragraph"},{"style":"important","name":"Important","content":[{"type":"paragraph","inlineContent":[{"type":"text","text":""},{"type":"text","text":" "},{"text":"SwiftChaChaPoly requires Swift 5.0. It also requires that the ","type":"text"},{"code":"Int","type":"codeVoice"},{"text":" and ","type":"text"},{"code":"UInt","type":"codeVoice"},{"text":" types be 64 bit types.","type":"text"}]}],"type":"aside"}],"kind":"content"}],"references":{"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/Performance":{"title":"Performance","role":"article","url":"\/documentation\/swiftchachapoly\/performance","abstract":[{"text":"Encryption and decryption speed","type":"text"}],"kind":"article","type":"topic","identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Performance"},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/Byte":{"title":"Byte","navigatorTitle":[{"kind":"identifier","text":"Byte"}],"identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Byte","role":"symbol","kind":"symbol","url":"\/documentation\/swiftchachapoly\/byte","fragments":[{"kind":"keyword","text":"typealias"},{"kind":"text","text":" "},{"text":"Byte","kind":"identifier"}],"type":"topic","abstract":[{"text":"Unsigned 8 bit value","type":"text"}]},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/ChaChaPoly":{"title":"ChaChaPoly","url":"\/documentation\/swiftchachapoly\/chachapoly","kind":"symbol","identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/ChaChaPoly","role":"symbol","abstract":[{"type":"text","text":"The ChaChaPoly structure"}],"navigatorTitle":[{"text":"ChaChaPoly","kind":"identifier"}],"type":"topic","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"text":"ChaChaPoly","kind":"identifier"}]},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/Bytes":{"identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/Bytes","url":"\/documentation\/swiftchachapoly\/bytes","role":"symbol","fragments":[{"kind":"keyword","text":"typealias"},{"text":" ","kind":"text"},{"text":"Bytes","kind":"identifier"}],"title":"Bytes","navigatorTitle":[{"text":"Bytes","kind":"identifier"}],"abstract":[{"type":"text","text":"Array of unsigned 8 bit values"}],"kind":"symbol","type":"topic"},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly":{"url":"\/documentation\/swiftchachapoly","type":"topic","kind":"symbol","role":"collection","title":"SwiftChaChaPoly","identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly","abstract":[{"type":"text","text":"Authenticated Encryption with Associated Data"}]},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/CryptoKit":{"kind":"article","identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/CryptoKit","type":"topic","url":"\/documentation\/swiftchachapoly\/cryptokit","role":"article","abstract":[{"type":"text","text":"SwiftChaChaPoly is compatible with Apple’s CryptoKit framework"}],"title":"CryptoKit Compatibility"},"doc://SwiftChaChaPoly/documentation/SwiftChaChaPoly/References":{"identifier":"doc:\/\/SwiftChaChaPoly\/documentation\/SwiftChaChaPoly\/References","url":"\/documentation\/swiftchachapoly\/references","role":"article","title":"References","abstract":[{"text":"Algorithms from the following papers have been used in the implementation","type":"text"}],"kind":"article","type":"topic"}}}