<!--
{
  "availability" : [

  ],
  "documentType" : "symbol",
  "framework" : "Tor",
  "identifier" : "/documentation/Tor/OnionKeySpec",
  "metadataVersion" : "0.1.0",
  "role" : "Enumeration",
  "symbol" : {
    "kind" : "Enumeration",
    "modules" : [
      "Tor"
    ],
    "preciseIdentifier" : "s:3Tor12OnionKeySpecO"
  },
  "title" : "OnionKeySpec"
}
-->

# OnionKeySpec

Key-generation policy for an onion service (`ADD_ONION` first argument).

```
enum OnionKeySpec
```

## Overview

Maps 1:1 to the KeyType/KeyBlob syntax in control-spec.txt §3.27
(`ADD_ONION`). Two real choices are supported: ask Tor to generate a
fresh v3 key ([`OnionKeySpec.newV3(discardPrivateKey:)`](/documentation/Tor/OnionKeySpec/newV3(discardPrivateKey:))) or supply an existing
ED25519-V3 private key to re-adopt a previously-registered service
([`OnionKeySpec.providedV3(_:)`](/documentation/Tor/OnionKeySpec/providedV3(_:))).

Only v3 is modelled — v2 (RSA-1024) was deprecated upstream in July
2021 (Tor 0.4.6) and removed in 0.4.7, and is out of scope for
swift-tor.

> Note: Conformance is `Sendable`. The enum is not `Hashable` by
> design: ``doc://Tor/documentation/Tor/OnionKeySpec/providedV3(_:)`` carries private-key material, and
> pattern-matching or comparison on secrets is a security smell
> better handled by the caller explicitly.

> Important: Private keys are ED25519 expanded secrets per
> rend-spec-v3 §2.5 — the blob format Tor emits via `ADD_ONION`
> responses. Do not attempt to construct them by hand; round-trip
> through Tor or Apple’s `CryptoKit.Curve25519.Signing`.

## Topics

### Cases

[`OnionKeySpec.newV3(discardPrivateKey:)`](/documentation/Tor/OnionKeySpec/newV3(discardPrivateKey:))

Ask Tor to generate a fresh v3 onion service key pair.

[`OnionKeySpec.providedV3(_:)`](/documentation/Tor/OnionKeySpec/providedV3(_:))

Re-adopt a previously-registered v3 service by its private key.