runtime-core/io.matthewnelson.kmp.tor.runtime.core.ctrl.builder/BuilderScopeOnionAdd

BuilderScopeOnionAdd

class BuilderScopeOnionAdd : BuilderScopeHSPort.DSL<BuilderScopeOnionAdd> (source)

A DSL builder scope for configuring TorCmd.Onion.Add. The ONION_ADD control command has an extremely overloaded API. This attempts to alleviate some of its pain points and peculiarities by splitting things into 2 "modes" of operation; new and existing.

NOTE: Both "modes" require a minimum of 1 port to be defined. Otherwise, the call will fail.

NEW TorCmd.Onion.Add.new:

Creates a command object that will instruct tor to generate keys for, and add to its runtime, a new Hidden Service.

e.g. (Generating a new Hidden Service)

TorCmd.Onion.Add.new(type = ED25519_V3) {
    port(virtual = Port.HTTP) {
        target(port = 8080.toPort())
    }
}

NOTE: After call completion, the returned HiddenServiceEntry.privateKey should be destroyed when done with it!

EXISTING TorCmd.Onion.Add.existing:

Creates a command object that will instruct tor to add an existing Hidden Service to its runtime, for the provided AddressKey.Private.

e.g. (Adding an existing Hidden Service you have keys for)

TorCmd.Onion.Add.existing(key = "[Blob Redacted]".toED25519_V3PrivateKey()) {
    port(virtual = Port.HTTP) {
        target(port = 8080.toPort())
    }
}

NOTE: FlagsBuilder.DiscardPK is automatically added for this "mode" in order to mitigate unnecessary private key material exposure. It can be disabled by explicitly setting the flag option to false.

NOTE: destroyKeyOnJobCompletion is automatically set to true for this "mode" in order to mitigate unnecessary private key material exposure. It can be disabled by explicitly setting it to `false.

EXAMPLE:

e.g. (A full blown example using kmp-tor:runtime)

// Create new V3 Hidden Service (tor will generate keys)
val entry = runtime.executeAsync(TorCmd.Onion.Add.new(ED25519_V3) {
    port(virtual = Port.HTTP) {
        target(port = 8080.toPort())
    }
    port(virtual = Port.HTTPS) {
        try {
            target(unixSocket = runtime.environment()
                .workDirectory
                .resolve("test_hs.sock"))
        } catch (_: UnsupportedOperationException) {
            // Fallback to TCP if on system w/o
            // UnixSocket support.
            target(port = 8443.toPort())
        }
    }
    maxStreams(25)
})

// Remove the Hidden Service
runtime.executeAsync(TorCmd.Onion.Delete(entry.publicKey))

// Re-add the Hidden Service
//
// entry.privateKey will not be `null` because `DiscardPK`
// flag was not defined when created above.
val newEntry = runtime.executeAsync(TorCmd.Onion.Add.existing(entry.privateKey!!) {
    port(virtual = Port.HTTP) {
        target(port = 8080.toPort())
    }
})

// `destroyKeyOnJobCompletion` was `true` (the default) which
// cleaned things up on call completion.
assertTrue(entry.privateKey!!.isDestroyed())

// The `DiscardPK` flag was automatically added for `existing`
// "mode" and not changed above, so tor did not return one.
assertNull(newEntry.privateKey)

Types

FlagsBuilder

class FlagsBuilder

Configure flags for the TorCmd.Onion.Add object, as described in control-spec#ADD_ONION.

Functions

clientAuth

fun clientAuth(key: X25519.PublicKey): BuilderScopeOnionAdd

Add AuthKey.Public for client authentication.

destroyKeyOnJobCompletion

fun destroyKeyOnJobCompletion(destroy: Boolean): BuilderScopeOnionAdd

When true, an EnqueuedJob.invokeOnCompletion handler is automatically set when the resulting TorCmd.Onion.Add object is enqueued. The handler calls AddressKey.Private.destroy upon job completion (either successfully or by cancellation/error).

flags