Release 2.4.0

Author: leif-ibsen

Package.swift

@@ -14,9 +14,9 @@ let package = Package(
     ],
     dependencies: [
         // Dependencies declare other packages that this package depends on.
-        .package(url: "https://github.com/leif-ibsen/BigInt", from: "1.15.0"),
-        .package(url: "https://github.com/leif-ibsen/ASN1", from: "2.3.0"),
-        .package(url: "https://github.com/leif-ibsen/Digest", from: "1.2.0"),
+        .package(url: "https://github.com/leif-ibsen/BigInt", from: "1.16.0"),
+        .package(url: "https://github.com/leif-ibsen/ASN1", from: "2.4.0"),
+        .package(url: "https://github.com/leif-ibsen/Digest", from: "1.3.0"),
     ],
     targets: [
         // Targets are the basic building blocks of a package. A target can define a module or a test suite.

README.md

@@ -10,7 +10,7 @@ including all four modes of operation:
 
 SwiftHPKE requires Swift 5.0. It also requires that the `Int` and `UInt` types be 64 bit types.
 
-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/SwiftHPKE/documentation/swifthpke
 

Sources/SwiftHPKE/AEAD.swift

@@ -7,7 +7,7 @@
 
 import CryptoKit
 
-/// AEAD encryption algorithms
+/// The AEAD encryption algorithms
 public enum AEAD: CustomStringConvertible, CaseIterable {
 
     /// Textual description of `self`

Sources/SwiftHPKE/CipherSuite.swift

@@ -14,7 +14,6 @@ public typealias Byte = UInt8
 /// Array of unsigned 8 bit values
 public typealias Bytes = [UInt8]
 
-/// The CipherSuite structure
 public struct CipherSuite: CustomStringConvertible {
 
     let kemStructure: KEMStructure

Sources/SwiftHPKE/Exception.swift

@@ -5,7 +5,7 @@
 //  Created by Leif Ibsen on 18/02/2020.
 //
 
-/// HPKE exceptions
+/// The HPKE exceptions
 public enum HPKEException: Error, CustomStringConvertible {
 
     /// Textual description of `self`

Sources/SwiftHPKE/KDF.swift

@@ -7,7 +7,7 @@
 
 import Digest
 
-/// Key derivation functions
+/// The key derivation functions
 public enum KDF: CustomStringConvertible, CaseIterable {
 
     /// Textual description of `self`

Sources/SwiftHPKE/KEM.swift

@@ -8,7 +8,7 @@
 import Foundation
 import BigInt
 
-/// Key encapsulation mechanisms
+/// The key encapsulation mechanisms
 public enum KEM: CustomStringConvertible, CaseIterable {
 
     /// Textual description of `self`

Sources/SwiftHPKE/PrivateKey.swift

@@ -8,7 +8,6 @@
 import ASN1
 import BigInt
 
-/// The PrivateKey structure
 public struct PrivateKey: CustomStringConvertible, Equatable {
 
     let kem: KEM

Sources/SwiftHPKE/PublicKey.swift

@@ -8,7 +8,6 @@
 import ASN1
 import BigInt
 
-/// The PublicKey structure
 public struct PublicKey: CustomStringConvertible, Equatable {
 
     let kem: KEM

Sources/SwiftHPKE/Recipient.swift

@@ -5,7 +5,6 @@
 //  Created by Leif Ibsen on 19/06/2023.
 //
 
-/// The Recipient class
 public class Recipient {
 
     let suite: CipherSuite

Sources/SwiftHPKE/Sender.swift

@@ -5,7 +5,6 @@
 //  Created by Leif Ibsen on 19/06/2023.
 //
 
-/// The Sender class
 public class Sender {
 
     let suite: CipherSuite

Sources/SwiftHPKE/SwiftHPKE.docc/Articles/Basics.md

@@ -1,9 +1,10 @@
-# Apple CryptoKit Compatibility
+# CryptoKit Compatibility
+
+SwiftHPKE is compatible with Apple’s CryptoKit framework
 
 ## 
 
-The SwiftHPKE keys of type `.P256`, `.P384`, `.P521` and `.X25519` correspond to Apple
-CryptoKit keys of type `P256`, `P384`, `P521` and `Curve25519`. Keys of type `.X448` is not supported in CryptoKit.
+The SwiftHPKE keys of type `.P256`, `.P384`, `.P521` and `.X25519` correspond to CryptoKit keys of type `P256`, `P384`, `P521` and `Curve25519`. Keys of type `.X448` is not supported in CryptoKit.
 
 To convert CryptoKit `P256` keys (similarly for `P384` and `P521`) - say `ckPriv` and `ckPub` to SwiftHPKE keys:
 

Sources/SwiftHPKE/SwiftHPKE.docc/Articles/CreateKeys.md

@@ -1,8 +1,42 @@
-# Loading Existing Keys
+# Key Management
+
+Creating new keys and loading exsisting keys
 
 ## 
+
+### Create new Keys
+
+Given a ``SwiftHPKE/CipherSuite`` instance it is possible to generate new ``SwiftHPKE/PublicKey``'s and ``SwiftHPKE/PrivateKey``'s.
+
+```swift
+import SwiftHPKE
+
+let suite = CipherSuite(kem: .X25519, kdf: .KDF256, aead: .CHACHAPOLY)
+let (pubKey, privKey) = try suite.makeKeyPair()
+
+// See the key ASN1 structures
+
+print(pubKey)
+print(privKey)
+```
+giving (for example):
+```swift
+Sequence (2):
+  Sequence (1):
+    Object Identifier: 1.3.101.110
+  Bit String (256): 11100111 11100111 00010111 11110101 10101000 10010101 01001010 00100010 00011010 10001001 11001011 11010001 11101101 10000101 01110101 11011111 11010110 00001101 01001110 10100100 00111011 00110100 01110000 01011000 00111111 01011011 10001010 11111010 01101000 10010011 10100001 00001101
+
+Sequence (3):
+  Integer: 0
+  Sequence (1):
+    Object Identifier: 1.3.101.110
+  Octet String (34): 04 20 b0 e5 94 7d f8 72 04 8f 90 79 5f d5 b7 e4 6e ca 56 18 58 30 2e 4e 79 83 d6 46 bb 42 70 2a 34 68
+```
+
+### Load existing Keys
+
 It is possible to load existing keys from their PEM encodings or DER encodings.
-### Example
+
 ```swift
 import SwiftHPKE
 
@@ -50,3 +84,4 @@ Sequence (3):
     Object Identifier: 1.3.132.0.34
   Octet String (167): 30 81 a4 02 01 01 04 30 66 a4 dc e2 49 89 86 a1 6c 25 ed aa 49 33 d6 5d 0c 1c 64 26 a9 b1 31 27 07 19 71 b8 e5 94 17 4a fe df 22 e2 65 b1 2c 31 2b be a7 52 28 8e ee 08 a0 07 06 05 2b 81 04 00 22 a1 64 03 62 00 04 41 6f cc 6a 13 30 31 31 63 c1 8f 79 b8 e1 1d 7c 15 42 ec 7a d0 85 31 86 4f 0c 62 3e 58 03 88 04 6a 0b ac ba 11 0d 40 8e 4b a1 7b 80 34 d9 63 a5 b5 16 10 45 72 b2 b7 3b 29 39 1d b9 51 f8 2d 6a 05 11 03 0c 55 15 8c d1 f5 c9 a2 e8 54 66 be fa bf 4e c8 a0 77 f7 40 8b 81 4d 8e 78 91 ef f3 e0
 ```
+

Sources/SwiftHPKE/SwiftHPKE.docc/Articles/CryptoKit.md

@@ -1,5 +1,7 @@
 # Performance
 
+Encryption and decryption speed
+
 ## 
 
 SwiftHPKE's encryption and decryption performance was measured on an iMac 2021, Apple M1 chip.

Sources/SwiftHPKE/SwiftHPKE.docc/Articles/Dependencies.md

@@ -1,9 +1,8 @@
 # References
 
-## 
+Algorithms from the following books and papers have been used in the implementation
 
-Algorithms from the following books and papers have been used in the implementation.
-There are references in the source code where appropriate.
+## 
 
 * [FIPS 180-4] - FIPS PUB 180-4 - Secure Hash Standard (SHS), August 2015
 * [GUIDE] - Hankerson, Menezes, Vanstone: Guide to Elliptic Curve Cryptography. Springer 2004

Sources/SwiftHPKE/SwiftHPKE.docc/Articles/EncryptDecrypt.md

@@ -1,9 +1,13 @@
 # Secret Export
 
+Creating secret messages
+
 ## 
+
 Given the recipient's public key, a sender can generate a secret that only the recipient can know.
 
 ### Example 1
+
 ```swift
 import SwiftHPKE
 
@@ -29,6 +33,7 @@ Retrieved secret: [172, 169, 119, 121, 167, 53, 213, 12, 0, 29]
 ```
 
 ### Example 2
+
 ```swift
 import SwiftHPKE
 

Sources/SwiftHPKE/SwiftHPKE.docc/Articles/LoadKeys.md Sources/SwiftHPKE/SwiftHPKE.docc/Articles/KeyManagement.md

@@ -1,5 +1,7 @@
 # ``SwiftHPKE/Base64``
 
+The Base64 structure
+
 ## Overview
 
 Base64 exists to provide a namespace. It contains static methods for Base64 encoding and decoding. There is no Base64 instances.