Start docc

Sources/Packages/Sources/SecretKit/Documentation.docc/Documentation.md

@@ -0,0 +1,35 @@
+# ````SecretKit````
+
+SecretKit is a collection of protocols describing secrets and stores.
+
+## Overview
+
+Overview
+
+## Topics
+
+### Base Protocols
+
+- ``Secret``
+- ``SecretStore``
+- ``SecretStoreModifiable``
+
+### Store List
+
+- ``SecretStoreList``
+
+### Type Erasers
+
+- ``AnySecret``
+- ``AnySecretStore``
+- ``AnySecretStoreModifiable``
+
+### OpenSSH 
+
+- ``OpenSSHKeyWriter``
+- ``OpenSSHReader``
+
+### Signing Process
+
+- ``SignedData``
+- ``SigningRequestProvenance``

Sources/Packages/Sources/SecretKit/Erasers/AnySecret.swift

@@ -1,5 +1,6 @@
 import Foundation
 
+/// Type eraser for Secret.
 public struct AnySecret: Secret {
 
     let base: Any

Sources/Packages/Sources/SecretKit/Erasers/AnySecretStore.swift

@@ -1,6 +1,7 @@
 import Foundation
 import Combine
 
+/// Type eraser for SecretStore.
 public class AnySecretStore: SecretStore {
 
     let base: Any

Sources/Packages/Sources/SecretKit/OpenSSH/OpenSSHKeyWriter.swift

@@ -1,24 +1,31 @@
 import Foundation
 import CryptoKit
 
-// For the moment, only supports ecdsa-sha2-nistp256 and ecdsa-sha2-nistp386 keys
+/// Generates OpenSSH representations of Secrets.
 public struct OpenSSHKeyWriter {
 
+    /// Initializes the writer.
     public init() {
     }
 
+    /// Generates an OpenSSH data payload identifying the secret.
+    /// - Returns: OpenSSH data payload identifying the secret.
     public func data<SecretType: Secret>(secret: SecretType) -> Data {
         lengthAndData(of: curveType(for: secret.algorithm, length: secret.keySize).data(using: .utf8)!) +
             lengthAndData(of: curveIdentifier(for: secret.algorithm, length: secret.keySize).data(using: .utf8)!) +
             lengthAndData(of: secret.publicKey)
     }
 
+    /// Generates an OpenSSH string representation of the secret.
+    /// - Returns: OpenSSH string representation of the secret.
     public func openSSHString<SecretType: Secret>(secret: SecretType, comment: String? = nil) -> String {
         [curveType(for: secret.algorithm, length: secret.keySize), data(secret: secret).base64EncodedString(), comment]
             .compactMap { $0 }
             .joined(separator: " ")
     }
 
+    /// Generates an OpenSSH SHA256 fingerprint string.
+    /// - Returns: OpenSSH SHA256 fingerprint string.
     public func openSSHSHA256Fingerprint<SecretType: Secret>(secret: SecretType) -> String {
         // OpenSSL format seems to strip the padding at the end.
         let base64 = Data(SHA256.hash(data: data(secret: secret))).base64EncodedString()
@@ -27,6 +34,8 @@ public struct OpenSSHKeyWriter {
         return "SHA256:\(cleaned)"
     }
 
+    /// Generates an OpenSSH MD5 fingerprint string.
+    /// - Returns: OpenSSH MD5 fingerprint string.
     public func openSSHMD5Fingerprint<SecretType: Secret>(secret: SecretType) -> String {
         Insecure.MD5.hash(data: data(secret: secret))
             .compactMap { ("0" + String($0, radix: 16, uppercase: false)).suffix(2) }
@@ -37,23 +46,37 @@ public struct OpenSSHKeyWriter {
 
 extension OpenSSHKeyWriter {
 
+    /// Creates an OpenSSH protocol style data object, which has a length header, followed by the data payload.
+    /// - Parameter data: the data payload.
+    /// - Returns: OpenSSH data.
     public func lengthAndData(of data: Data) -> Data {
         let rawLength = UInt32(data.count)
         var endian = rawLength.bigEndian
         return Data(bytes: &endian, count: UInt32.bitWidth/8) + data
     }
 
-    public func curveIdentifier(for algorithm: Algorithm, length: Int) -> String {
+    /// The fully qualified OpenSSH identifier for the algorithm.
-        switch algorithm {
+    /// - Parameters:
-        case .ellipticCurve:
+    ///   - algorithm: the algorithm to identify.
-            return "nistp" + String(describing: length)
+    ///   - length: the key length of the algorithm.
-        }
+    /// - Returns: The OpenSSH identifier for the algorithm.
-    }
-
     public func curveType(for algorithm: Algorithm, length: Int) -> String {
         switch algorithm {
         case .ellipticCurve:
             return "ecdsa-sha2-nistp" + String(describing: length)
         }
     }
+
+    /// The OpenSSH identifier for an algorithm.
+    /// - Parameters:
+    ///   - algorithm: the algorithm to identify.
+    ///   - length: the key length of the algorithm.
+    /// - Returns: The OpenSSH identifier for the algorithm.
+    private func curveIdentifier(for algorithm: Algorithm, length: Int) -> String {
+        switch algorithm {
+        case .ellipticCurve:
+            return "nistp" + String(describing: length)
+        }
+    }
+
 }

Sources/Packages/Sources/SecretKit/Types/Secret.swift

@@ -1,16 +1,26 @@
 import Foundation
 
+/// The base protocol for describing a Secret
 public protocol Secret: Identifiable, Hashable {
 
+    /// A user-facing string identifying the Secret
     var name: String { get }
+    /// The algorithm this secret uses.
     var algorithm: Algorithm { get }
+    /// The key size for the secret.
     var keySize: Int { get }
+    /// The public key data for the secret.
     var publicKey: Data { get }
 
 }
 
+/// The type of algorithm the Secret uses. Currently, only elliptic curve algorithms are supported.
 public enum Algorithm: Hashable {
+
     case ellipticCurve
+
+    /// Initializes the Algorithm with a secAttr representation of an algorithm.
+    /// - Parameter secAttr: the secAttr, represented as an NSNumber.
     public init(secAttr: NSNumber) {
         let secAttrString = secAttr.stringValue as CFString
         switch secAttrString {