Skip to content

Commit

Permalink
Improve DocC landing pages (#313)
Browse files Browse the repository at this point in the history
Improve DocC landing pages by mimicking Apple's CryptoKit docs

### Motivation:

Right now the DocC docs group all APIs by protocols, structures and
enums.
By adding a topics section in the landing page we can group them by type
("Ciphers", "Public key cryptography", etc.) exactly in the way Apple
does in [CryptoKit
docs](https://developer.apple.com/documentation/cryptokit/).

### Modifications:

- Fix DocC compilation errors in `_CryptoExtras`
- Add topics section in `_CryptoExtras` landing page
- Add topics section in `Crypto` landing page

### Result:

APIs will be grouped by type.

---------

Co-authored-by: Cory Benfield <[email protected]>
  • Loading branch information
fpseverino and Lukasa authored Dec 16, 2024
1 parent bce1725 commit 0bf9f47
Show file tree
Hide file tree
Showing 3 changed files with 65 additions and 3 deletions.
44 changes: 43 additions & 1 deletion Sources/Crypto/Docs.docc/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,46 @@ Swift Crypto provides a Swift library for common cryptographic operations. It is
* `Crypto` - an open-source implementation of a substantial portion of the API of [Apple CryptoKit](https://developer.apple.com/documentation/cryptokit) suitable for use on Linux platforms. It enables cross-platform or server applications with the advantages of CryptoKit.
* `CryptoExtras` - a collection of additional cryptographic primitives and utilities that are not part of CryptoKit but useful in a server environment.

Swift Crypto is built on top of [BoringSSL](https://boringssl.googlesource.com/boringssl/), Google's fork of OpenSSL. The current features of Swift Crypto cover key exchange, key derivation, encryption and decryption, hashing, message authentication, and more.
Swift Crypto is built on top of [BoringSSL](https://boringssl.googlesource.com/boringssl/), Google's fork of OpenSSL. The current features of Swift Crypto cover key exchange, key derivation, encryption and decryption, hashing, message authentication, and more.

## Topics

### Cryptographically secure hashes

- ``HashFunction``
- ``SHA512``
- ``SHA384``
- ``SHA256``

### Message authentication codes

- ``HMAC``
- ``SymmetricKey``
- ``SymmetricKeySize``

### Ciphers

- ``AES``
- ``ChaChaPoly``

### Public key cryptography

- ``Curve25519``
- ``P521``
- ``P384``
- ``P256``
- ``SharedSecret``
- ``HPKE``

### Key derivation functions

- ``HKDF``

### Errors

- ``CryptoKitError``
- ``CryptoKitASN1Error``

### Legacy algorithms

- ``Insecure``
20 changes: 20 additions & 0 deletions Sources/_CryptoExtras/Docs.docc/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,24 @@

Provides additional cryptographic APIs that are not available in CryptoKit (and therefore the core Crypto library).

## Overview

`CryptoExtras` is a collection of additional cryptographic primitives and utilities that are not part of CryptoKit but useful in a server environment.

## Topics

### Ciphers

- ``_CryptoExtras/Crypto/AES``

### Public key cryptography

- ``_RSA``

### Key derivation functions

- ``KDF``

### Legacy algorithms

- ``_CryptoExtras/Crypto/Insecure``
4 changes: 2 additions & 2 deletions Sources/_CryptoExtras/RSA/RSA+BlindSigning.swift
Original file line number Diff line number Diff line change
Expand Up @@ -410,7 +410,7 @@ extension _RSA.BlindSigning.PublicKey {
/// Prepare a message to be signed using the blind signing protocol.
///
/// - Parameter message: The message to be signed.
/// - Parameter parameters: Parameters used in the blind signing protocol.
///
/// - Returns: A prepared message, modified according to the parameters provided.
///
/// - Seealso: [RFC 9474: Prepare](https://www.rfc-editor.org/rfc/rfc9474.html#name-prepare).
Expand Down Expand Up @@ -440,7 +440,7 @@ extension _RSA.BlindSigning.PublicKey {
///
/// - Parameter signature: The signature of the blinded message.
/// - Parameter message: The message to be signed.
/// - Parameter blindInverse: The inverse from the message blinding.
/// - Parameter blindingInverse: The inverse from the message blinding.
/// - Returns: The signature of the message.
///
/// - Seealso: [RFC 9474: Finalize](https://www.rfc-editor.org/rfc/rfc9474.html#name-finalize).
Expand Down

0 comments on commit 0bf9f47

Please sign in to comment.