https://github.com/lordcodes/cloak-swift
Encrypt and obfuscate secrets, then pass them into Swift applications
https://github.com/lordcodes/cloak-swift
encryption swift swift-package-manager
Last synced: 5 months ago
JSON representation
Encrypt and obfuscate secrets, then pass them into Swift applications
- Host: GitHub
- URL: https://github.com/lordcodes/cloak-swift
- Owner: lordcodes
- License: apache-2.0
- Created: 2022-07-03T08:20:10.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-03-11T15:29:37.000Z (over 2 years ago)
- Last Synced: 2025-10-08T14:53:50.055Z (9 months ago)
- Topics: encryption, swift, swift-package-manager
- Language: Swift
- Homepage:
- Size: 299 KB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
---
This is **Cloak Swift** - a CLI tool to encrypt secrets and then pass them in an obfuscated form into Swift applications.
Features • Install • Usage • Contributing
## Features
#### ☑️ Keep your secrets out of Git
Set up secrets locally outside of the Git repository to avoid them being embedded into the code.
#### ☑️ Encrypt secrets
Create encryption key and encrypt secrets ready for use.
#### ☑️ Access secrets from your app
Generate a Swift file to access the secrets from your app's code.
#### ☑️ Obfuscation
The generated Swift uses obfuscation of the values rather than as raw strings.
## Install
### ▶︎ ⚙️ Mise
Cloak Swift can be installed using Mise or ASDF either globally or with a project-specific version.
Note: Currently, the plugin URL needs to be specified. The plugin will be added to the registry soon so that this is no longer required.
**Mise `.mise.toml`**
```toml
[tools]
cloak-swift = "0.4.0"
[plugins]
cloak-swift = "https://github.com/lordcodes/asdf-cloak-swift"
```
### ▶︎ 🖥 Standalone via Swift Package Manager
Cloak Swift can be easily installed globally using Swift Package Manager.
```terminal
git clone https://github.com/lordcodes/cloak-swift
cd cloak-swift
make install
```
This will install cloakswift into `/usr/local/bin`. If you get a permission error it may be that you don't have permission to write there in which case you just need to adjust permissions using `sudo chown -R $(whoami) /usr/local/bin`.
You can uninstall it again using `make uninstall` which simply deletes it from `/usr/local/bin`.
### ▶︎ 🍀 Mint
You can install Cloak Swift on MacOS using [Mint](https://github.com/yonaskolb/Mint) as follows:
```terminal
mint install lordcodes/cloak-swift
```
### ▶︎ 📦 As a Swift package
To install Cloak Swift for use in your own Swift code, add it is a Swift Package Manager dependency within your `Package.swift` file. For help in doing this, please check out the Swift Package Manager documentation.
```swift
.package(url: "https://github.com/lordcodes/cloak-swift", exact: "0.4.0")
```
## Usage
### Set up configuration
Create a configuration file within your project: `.cloak/config`, this file should be kept in Git and shared between contributors. Enter key-value pairs into the file [EnvironmentKey](Sources/CloakKit/Configuration/EnvironmentKey.swift).
* CLOAK_SECRETS_CLASS_NAME -> Name to give the generated Swift enum that contains the secrets in-app.
* CLOAK_SECRETS_OUTPUT_FILEPATH -> File path to put the generated Swift file.
* CLOAK_SECRETS_ACCESS_LEVEL -> Swift access level to give to the enum and each secret static property. E.g. public.
Each of these settings can be provided as an environment variable instead of listed in the configuration file. The config file will take precedance.
For example:
```
CLOAK_SECRETS_CLASS_NAME=AppSecrets
CLOAK_SECRETS_OUTPUT_FILEPATH=Sources/Generated/AppSecrets.swift
CLOAK_SECRETS_ACCESS_LEVEL=public
```
### Configure required secret keys
You can list the required secret keys for your project in a `.cloak/secret-keys` file, which can be kept in Git. This ensures each contributor has provided all required secrets locally. Secret keys should be listed one on each line.
For example:
```
ANALYTICS_WRITE_KEY
API_CLIENT_ID
API_CLIENT_SECRET
```
### Configure secrets
Each contributor on a project will need to create a file at `.cloak/secrets` that uses the same format as the `config` file but that lists secret key names and values. This file should be added to your project's `.gitignore` to keep them out of Git.
You should also add your encryption key to this file using the key name `CLOAK_ENCRYPTION_KEY`. This will allow the encrypt/decrypt commands to function and will also allow it to be included into the generated Swift file so that your app can decrypt the secrets at runtime in order to use them.
If the secret keys are specified in the required keys file `secret-keys`, then they will be read as environment variables as well, where the environment variables take precendence. This is useful in a CI environment where you can specify them as environment variables and avoid having to write them to a file as you would locally.
The best practice is that the values should be encrypted first.
### 🖥 Via the Standalone CLI
Run Cloak's tasks via a CLI. The tool will check paths relative to the working directory for the `.cloak` directory configured above.
```terminal
USAGE: cloakswift [-q|--quiet]
SUBCOMMANDS:
createkey Create encryption key.
decrypt Decrypt a value encrypted using cloak.
encrypt Encrypt a value.
generate Read in secrets, obfuscate them and then generate a Swift file to access them within an app.
version Print version.
OPTIONS:
-q, --quiet Silence any output except errors
```
You can obtain help using `cloakswift --help` and also obtain help for each subcommand using `cloakswift --help`.
#### Create encryption key
Generates an encryption key, that can then be used within your project to encrypt secrets. This key is then passed into your app so that you can decrypt them at runtime.
`cloakswift createkey`
#### Encrypt a value
Provide a value and the encrypted version will be returned. Your encryption key should be provided as described above.
`cloakswift encrypt `
#### Decrypt an encrypted value
Provide an encrypted value and the decrypted version will be returned. Your encryption key should be provided as described above.
`cloakswift decrypt `
#### Generate a secrets file in-app
Generate a Swift file that can be used to access your secrets within your app at runtime. Certain aspects of the generated file can be customised using the `config` file as described above. The secrets will be obfuscated and included as `[UInt8]`, but with Swift properties to return them as `String` in their usable form.
`cloakswift generate`
### 📦 As a Swift Package
To use Cloak Swift within your own Swift code, import and use the public API of `CloakKit`.
```swift
import CloakKit
// Configure printing
Cloak.shared.printer = ConsolePrinter(quiet: false)
EncryptionService().createKey()
```
## Contributing or Help
If you notice any bugs or have a new feature to suggest, please check out the [contributing guide](https://github.com/lordcodes/cloak-swift/blob/master/CONTRIBUTING.md). If you want to make changes, please make sure to discuss anything big before putting in the effort of creating the PR.
To reach out, please contact [@lordcodes on Twitter](https://twitter.com/lordcodes).