From fc294d9f3c9e8da5c7ca0fcce07066997b970577 Mon Sep 17 00:00:00 2001 From: Max Goedjen Date: Sat, 1 Jan 2022 17:29:44 -0800 Subject: [PATCH] Start docc --- .../Documentation.docc/Documentation.md | 35 +++++++++++++++++ .../Sources/SecretKit/Erasers/AnySecret.swift | 1 + .../SecretKit/Erasers/AnySecretStore.swift | 1 + .../SecretKit/OpenSSH/OpenSSHKeyWriter.swift | 39 +++++++++++++++---- .../Sources/SecretKit/Types/Secret.swift | 10 +++++ 5 files changed, 78 insertions(+), 8 deletions(-) create mode 100644 Sources/Packages/Sources/SecretKit/Documentation.docc/Documentation.md diff --git a/Sources/Packages/Sources/SecretKit/Documentation.docc/Documentation.md b/Sources/Packages/Sources/SecretKit/Documentation.docc/Documentation.md new file mode 100644 index 0000000..c278de7 --- /dev/null +++ b/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`` diff --git a/Sources/Packages/Sources/SecretKit/Erasers/AnySecret.swift b/Sources/Packages/Sources/SecretKit/Erasers/AnySecret.swift index a3c0415..b5a748d 100644 --- a/Sources/Packages/Sources/SecretKit/Erasers/AnySecret.swift +++ b/Sources/Packages/Sources/SecretKit/Erasers/AnySecret.swift @@ -1,5 +1,6 @@ import Foundation +/// Type eraser for Secret. public struct AnySecret: Secret { let base: Any diff --git a/Sources/Packages/Sources/SecretKit/Erasers/AnySecretStore.swift b/Sources/Packages/Sources/SecretKit/Erasers/AnySecretStore.swift index 7b565fe..305ecd2 100644 --- a/Sources/Packages/Sources/SecretKit/Erasers/AnySecretStore.swift +++ b/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 diff --git a/Sources/Packages/Sources/SecretKit/OpenSSH/OpenSSHKeyWriter.swift b/Sources/Packages/Sources/SecretKit/OpenSSH/OpenSSHKeyWriter.swift index a577476..fd01418 100644 --- a/Sources/Packages/Sources/SecretKit/OpenSSH/OpenSSHKeyWriter.swift +++ b/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(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(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(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(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 { - switch algorithm { - case .ellipticCurve: - return "nistp" + String(describing: length) - } - } - + /// The fully qualified OpenSSH identifier for the algorithm. + /// - Parameters: + /// - algorithm: the algorithm to identify. + /// - 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) + } + } + } diff --git a/Sources/Packages/Sources/SecretKit/Types/Secret.swift b/Sources/Packages/Sources/SecretKit/Types/Secret.swift index 1df3bf1..aa36314 100644 --- a/Sources/Packages/Sources/SecretKit/Types/Secret.swift +++ b/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 {