Skip to content
This repository was archived by the owner on Apr 12, 2025. It is now read-only.

Commit ab72372

Browse files
N3v1N3v1
committed
(feat): Finished documentation and documentation workflow
1 parent 20ac3aa commit ab72372

File tree

10 files changed

+380
-23
lines changed

10 files changed

+380
-23
lines changed

‎.github/workflows/documentation.yml

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Documentation 🚀
2+
on:
3+
# Runs on pushes targeting the default branch
4+
push:
5+
branches: ["main"]
6+
pull_request:
7+
branches: ["main"]
8+
workflow_dispatch:
9+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
10+
permissions:
11+
contents: read
12+
pages: write
13+
id-token: write
14+
# Allow one concurrent deployment
15+
concurrency:
16+
group: "pages"
17+
cancel-in-progress: true
18+
19+
jobs:
20+
# Single deploy job since we're just deploying
21+
deploy:
22+
environment:
23+
# Must be set to this for deploying to GitHub Pages
24+
name: github-pages
25+
url: ${{ steps.deployment.outputs.page_url }}
26+
runs-on: macos-14
27+
steps:
28+
- name: Checkout 🛎️
29+
uses: actions/checkout@v3
30+
- name: Select Xcode Version ✨
31+
run: |
32+
sudo xcode-select -switch /Applications/Xcode_15.4.app/Contents/Developer
33+
- name: Delete DerivedData directory 🗑️
34+
run: |
35+
rm -rf ~/Library/Developer/Xcode/DerivedData
36+
- name: Build DocC
37+
run: |
38+
xcodebuild docbuild -scheme CryptoSwiftWrapper \
39+
-derivedDataPath /tmp/docbuild \
40+
-destination 'generic/platform=iOS' CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO;
41+
$(xcrun --find docc) process-archive \
42+
transform-for-static-hosting /tmp/docbuild/Build/Products/Debug-iphoneos/CryptoSwiftWrapper.doccarchive \
43+
--hosting-base-path CryptoSwiftWrapper \
44+
--output-path docs;
45+
echo "<script>window.location.href += \"/documentation/cryptoswiftwrapper\"</script>" > docs/index.html;
46+
- name: Upload artifact
47+
uses: actions/upload-pages-artifact@v1
48+
with:
49+
# Upload only docs directory
50+
path: 'docs'
51+
- name: Deploy to GitHub Pages
52+
id: deployment
53+
uses: actions/deploy-pages@v1

‎Package.swift

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import PackageDescription
55

66
let package = Package(
77
name: "CryptoSwiftWrapper",
8-
platforms: [.iOS(.v17), .macOS(.v14)],
8+
platforms: [.iOS(.v18), .macOS(.v15), .macCatalyst(.v18)],
99
products: [
1010
.library(
1111
name: "CryptoSwiftWrapper",

‎Sources/CryptoSwiftWrapper/CYCryptoFunctions.swift

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ import Foundation
3434
///
3535
/// - Returns: A pointer to the allocated memory containing the key and IV.
3636
/// - Note: The caller is responsible for freeing the allocated memory using `free()`.
37-
@_cdecl("s_generate_key_iv")
37+
@_cdecl("generate_key_iv")
3838
public func generate_key_iv() -> UnsafeMutableRawPointer? {
3939
let key = SymmetricKey(size: .bits256)
4040
let iv = SymmetricKey(size: .bits128)
@@ -60,7 +60,7 @@ public func generate_key_iv() -> UnsafeMutableRawPointer? {
6060
/// - iv: Pointer to the AES initialization vector (IV).
6161
/// - ciphertext: Pointer to store the encrypted ciphertext data.
6262
/// - Returns: The length of the encrypted ciphertext data on success, or `CY_ERR_ENCR` on failure.
63-
@_cdecl("s_encrypt_data")
63+
@_cdecl("encrypt_data")
6464
public func encrypt_data(plaintext: UnsafePointer<UInt8>, plaintext_len: Int32, key: UnsafePointer<UInt8>, iv: UnsafePointer<UInt8>, ciphertext: UnsafeMutablePointer<UInt8>) -> Int32 {
6565
let keyData = Data(bytes: key, count: Int(AES_KEY_SIZE))
6666
let ivData = Data(bytes: iv, count: Int(AES_BLOCK_SIZE))
@@ -89,7 +89,7 @@ public func encrypt_data(plaintext: UnsafePointer<UInt8>, plaintext_len: Int32,
8989
/// - tag_len: Length of the authentication tag.
9090
/// - plaintext: Pointer to store the decrypted plaintext data.
9191
/// - Returns: The length of the decrypted plaintext data on success, or `CY_ERR_DECR` on failure.
92-
@_cdecl("s_decrypt_data")
92+
@_cdecl("decrypt_data")
9393
public func decrypt_data(ciphertext: UnsafePointer<UInt8>, ciphertext_len: Int32, key: UnsafePointer<UInt8>, iv: UnsafePointer<UInt8>, tag: UnsafePointer<UInt8>, tag_len: Int32, plaintext: UnsafeMutablePointer<UInt8>) -> Int32 {
9494
let keyData = Data(bytes: key, count: Int(AES_KEY_SIZE / 8))
9595
let ivData = Data(bytes: iv, count: Int(AES_BLOCK_SIZE))

‎Sources/CryptoSwiftWrapper/CryptoSwiftWrapper.h

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
//===-- CryptoSwiftWrapper/CryptoSwiftWrapper.h - Bridging ----- -*- C -*-===//
2+
// //
3+
// This source file is part of the Scribble Foundation open source project //
4+
// //
5+
// Copyright (c) 2024 ScribbleLabApp. and the ScribbleLab project authors //
6+
// Licensed under Apache License v2.0 with Runtime Library Exception //
7+
// //
8+
// You may not use this file except in compliance with the License. //
9+
// You may obtain a copy of the License at //
10+
// //
11+
// http://www.apache.org/licenses/LICENSE-2.0 //
12+
// //
13+
// Unless required by applicable law or agreed to in writing, software //
14+
// distributed under the License is distributed on an "AS IS" BASIS, //
15+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. //
16+
// See the License for the specific language governing permissions and //
17+
// limitations under the License. //
18+
// //
19+
//===----------------------------------------------------------------------===//
20+
21+
#include "CryptoSwiftWrapper/cyfn.h"

‎Sources/CryptoSwiftWrapper/Documentation.docc/CYErrors.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# CYErrors
2+
3+
Defines error codes used by the CryptoSwiftWrapper module to indicate various types of failures during cryptographic operations.
4+
5+
## Overview
6+
7+
The CYErrors constants provide a standardized way to handle errors encountered during key generation, encryption, and decryption operations. These error codes help identify the specific issue that occurred, allowing for better debugging and error handling.
8+
9+
### Error Codes
10+
11+
#### `CY_ERR_GENKEY` (-100)
12+
13+
Error code indicating key generation failure.
14+
15+
#### `CY_ERR_ENCR` (-101)
16+
17+
Error code indicating encryption failure.
18+
19+
#### `CY_ERR_DECR` (-102)
20+
21+
Error code indicating decryption failure.
22+
23+
#### `CY_ERR_INIT` (-103)
24+
25+
Error code indicating initialization failure.

‎Sources/CryptoSwiftWrapper/Documentation.docc/Documentation.md

Lines changed: 33 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,42 @@
11
# ``CryptoSwiftWrapper``
22

3-
<!--@START_MENU_TOKEN@-->Summary<!--@END_MENU_TOKEN@-->
3+
Interact with Swift-Crypto's AES-GCM encryption and decryption capabilities in C
4+
5+
@Metadata {
6+
@Available(iOS, introduced: "18.0")
7+
@Available(iPadOS, introduced: "18.0")
8+
@Available(macOS, introduced: "15.0")
9+
@Available(MacCatalyst, introduced: "18.0")
10+
11+
@Available(Swift, introduced: "6")
12+
13+
@SupportedLanguage(swift)
14+
@SupportedLanguage(c)
15+
}
416

517
## Overview
618

7-
<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
19+
The CryptoSwiftWrapper module provides an easy-to-use interface for cryptographic operations using AES-GCM. It allows Swift code to perform encryption and decryption tasks, while exposing these capabilities to C through a clean API.
20+
21+
Use the CryptoSwiftWrapper to perform common cryptographic operations using Swift-Crypto:
22+
23+
- Generate cryptographically secure keys and initialization vectors.
24+
- Encrypt and decrypt data using AES-GCM.
25+
26+
Prefer CryptoSwiftWrapper for its simplicity and integration with Swift. It abstracts the complexities of managing raw pointers and ensures secure memory handling.
827

928
## Topics
1029

11-
### <!--@START_MENU_TOKEN@-->Group<!--@END_MENU_TOKEN@-->
30+
### Essential
31+
32+
- <doc:UsageExample>
33+
- <doc:CYErrors>
34+
35+
### Key and IV Generation
36+
37+
- ``generate_key_iv()``
38+
39+
### En-/Decryption
1240

13-
- <!--@START_MENU_TOKEN@-->``Symbol``<!--@END_MENU_TOKEN@-->
41+
- ``encrypt_data(plaintext:plaintext_len:key:iv:ciphertext:)``
42+
- ``decrypt_data(ciphertext:ciphertext_len:key:iv:tag:tag_len:plaintext:)``

‎Sources/CryptoSwiftWrapper/Documentation.docc/UsageExample.md

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Integration Guide
2+
3+
Learn how to integrate CryptoSwiftWrapper into your Swift or C project for secure encryption and decryption operations.
4+
5+
## Overview
6+
7+
CryptoSwiftWrapper provides convenient wrappers around Swift-Crypto's AES-GCM encryption and decryption capabilities. This tutorial demonstrates how to generate encryption keys, encrypt plaintext data, decrypt ciphertext data, and handle errors using CryptoSwiftWrapper in both Swift and C.
8+
9+
### Implementation
10+
11+
@TabNavigator {
12+
@Tab("Swift") {
13+
#### Step 1: Add CryptoSwiftWrapper to Your Project
14+
15+
Ensure CryptoSwiftWrapper is included in your project. You can use Swift Package Manager to add it:
16+
17+
```swift
18+
dependencies: [
19+
.package(url: "https://github.com/your-repo/CryptoSwiftWrapper.git", from: "1.0.0")
20+
]
21+
```
22+
23+
#### Step 2: Generate a Key and IV
24+
25+
Use `generate_key_iv()` to generate a key and initialization vector (IV) for AES encryption:
26+
27+
```swift
28+
guard let keyIvPtr = generate_key_iv() else {
29+
fatalError("Failed to generate key and IV")
30+
}
31+
32+
let key = keyIvPtr.assumingMemoryBound(to: UInt8.self)
33+
let iv = key.advanced(by: Int(AES_KEY_SIZE / 8)).assumingMemoryBound(to: UInt8.self)
34+
35+
// Use key and iv for encryption...
36+
```
37+
38+
#### Step 3: Encrypt Data
39+
40+
Encrypt plaintext data using `encrypt_data()`:
41+
42+
```swift
43+
let plaintext: [UInt8] = [0x01, 0x02, 0x03, 0x04]
44+
let ciphertext = UnsafeMutablePointer<UInt8>.allocate(capacity: plaintext.count)
45+
46+
let encryptedLength = encrypt_data(plaintext, Int32(plaintext.count), key, iv, ciphertext)
47+
48+
if encryptedLength < 0 {
49+
fatalError("Encryption failed with error code: \(encryptedLength)")
50+
}
51+
52+
// Use encrypted data...
53+
```
54+
55+
#### Step 4: Decrypt Data
56+
57+
Decrypt ciphertext data using decrypt_data():
58+
59+
```swift
60+
let decrypted = UnsafeMutablePointer<UInt8>.allocate(capacity: Int(encryptedLength))
61+
let decryptedLength = decrypt_data(ciphertext, encryptedLength, key, iv, nil, 0, decrypted)
62+
63+
if decryptedLength < 0 {
64+
fatalError("Decryption failed with error code: \(decryptedLength)")
65+
}
66+
67+
// Use decrypted data...
68+
```
69+
70+
#### Step 5: Cleanup
71+
72+
Don't forget to deallocate memory allocated by `generate_key_iv()`, `encrypt_data()`, and `decrypt_data()`:
73+
74+
```swift
75+
keyIvPtr.deallocate()
76+
ciphertext.deallocate()
77+
decrypted.deallocate()
78+
```
79+
}
80+
81+
@Tab("C") {
82+
#### Step 1: Include CryptoSwiftWrapper in Your Project
83+
84+
Include `cyfn.h` in your C project and link with CryptoSwiftWrapper:
85+
86+
```c
87+
#include "CryptoSwiftWrapper/cyfn.h"
88+
```
89+
90+
#### Step 2: Generate a Key and IV
91+
92+
Use `generate_key_iv()` to generate a key and IV for AES encryption:
93+
94+
```c
95+
unsigned char *key, *iv;
96+
void *keyIvPtr = generate_key_iv();
97+
98+
if (!keyIvPtr) {
99+
fprintf(stderr, "Failed to generate key and IV\n");
100+
exit(CY_ERR_GENKEY);
101+
}
102+
103+
key = keyIvPtr;
104+
iv = key + AES_KEY_SIZE / 8;
105+
106+
// Use key and iv for encryption...
107+
```
108+
109+
#### Step 3: Encrypt Data
110+
111+
Encrypt plaintext data using `encrypt_data()`:
112+
113+
```c
114+
const unsigned char plaintext[] = {0x01, 0x02, 0x03, 0x04};
115+
unsigned char ciphertext[1024];
116+
int ciphertext_len = encrypt_data(plaintext, sizeof(plaintext), key, iv, ciphertext);
117+
118+
if (ciphertext_len < 0) {
119+
fprintf(stderr, "Encryption failed with error code: %d\n", ciphertext_len);
120+
exit(CY_ERR_ENCR);
121+
}
122+
123+
// Use encrypted data...
124+
```
125+
126+
#### Step 4: Decrypt Data
127+
128+
Decrypt ciphertext data using `decrypt_data()`:
129+
130+
```c
131+
unsigned char decrypted[1024];
132+
int decrypted_len = decrypt_data(ciphertext, ciphertext_len, key, iv, NULL, 0, decrypted);
133+
134+
if (decrypted_len < 0) {
135+
fprintf(stderr, "Decryption failed with error code: %d\n", decrypted_len);
136+
exit(CY_ERR_DECR);
137+
}
138+
139+
// Use decrypted data...
140+
```
141+
142+
#### Step 5: Cleanup
143+
144+
Free allocated memory when done:
145+
146+
```c
147+
free(key);
148+
```
149+
}
150+
}

‎Sources/CryptoSwiftWrapper/include/cyfn.h

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
//===-- CryptoSwiftWrapper/cyfn.h - Bridging ------------------- -*- C -*-===//
2+
// //
3+
// This source file is part of the Scribble Foundation open source project //
4+
// //
5+
// Copyright (c) 2024 ScribbleLabApp. and the ScribbleLab project authors //
6+
// Licensed under Apache License v2.0 with Runtime Library Exception //
7+
// //
8+
// You may not use this file except in compliance with the License. //
9+
// You may obtain a copy of the License at //
10+
// //
11+
// http://www.apache.org/licenses/LICENSE-2.0 //
12+
// //
13+
// Unless required by applicable law or agreed to in writing, software //
14+
// distributed under the License is distributed on an "AS IS" BASIS, //
15+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. //
16+
// See the License for the specific language governing permissions and //
17+
// limitations under the License. //
18+
// //
19+
//===----------------------------------------------------------------------===//
20+
21+
// This is a bridging header for cyfn.h to be usable from "CryptoSwiftWrapper/cyfn.h"
22+
23+
#ifndef cyfn_h
24+
#define cyfn_h
25+
26+
// Include the original _cyfn/cyfn.h header
27+
#include "_cyfn/cyfn.h"
28+
29+
#endif /* cyfn_h */

‎Sources/CryptoSwiftWrapper/module.modulemap

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
2+
module CryptoSwiftWrapper {
3+
header "CryptoSwiftWrapper.h"
4+
export *
5+
}

0 commit comments

Comments
 (0)