Methods

Method index

arti:get_client — Return the default client for a session.

Return the default client for a session.

Allocates a new ObjectID, but does not create a new underlying client object.

The returned ObjectID is a handle to a TorClient.

arti:get_client_status — Return current bootstrap and health information for a client.

Return current bootstrap and health information for a client.

arti:get_proxy_info — Get a list of all the currently running proxies.

Get a list of all the currently running proxies.

This method should not be used when deciding which proxy an RPC application should connect to. Instead, the application should use arti:get_rpc_proxy_info.

arti:get_rpc_proxy_info — Get a list of the currently running proxies that are integrated with the RPC system.

Get a list of the currently running proxies that are integrated with the RPC system.

This method returns a list of proxies. The RPC application may be not be able to use all proxies from the list, and may prefer some proxies over other. When multiple proxies are equally preferred, the application SHOULD use whichever appears first in the list.

You typically won't need to invoke this method yourself: your RPC library (like arti-rpc-client-core) should take care if it for you.

arti:new_isolated_client — Create a new isolated client instance.

Create a new isolated client instance.

Returned ObjectID is a handle for a new TorClient, which is isolated from other TorClients: any streams created with the new TorClient will not share circuits with streams created with any other TorClient.

arti:new_oneshot_client — Create a new RpcOneshotClient to wait for a SOCKS request.

Create a new RpcOneshotClient to wait for a SOCKS request.

The resulting ObjectID will be a handle to an RpcOneshotClient. It can be used as the target of a single SOCKS request.

Once used for a SOCKS connect request, the object will become a handle for the the underlying DataStream that was created with the request.

arti:watch_client_status — Run forever, delivering updates about a client's bootstrap and health information.

Run forever, delivering updates about a client's bootstrap and health information.

(This method can return updates that have no visible changes.)

arti:x_list_all_rpc_methods — Return a description of all recognized RPC methods.

Return a description of all recognized RPC methods.

Note that not every recognized method is necessarily invocable in practice. Depending on the session's access level, you might not be able to access any objects that the method might be invocable upon.

This is an experimental method. Methods starting with "x_" are extra-unstable. See RpcDispatchInformation for caveats about type names.

auth:authenticate — Authenticate on an RPC Connection, returning a new Session.

Authenticate on an RPC Connection, returning a new Session.

After connecting to Arti, clients use this method to create a Session, which they then use to access other functionality.

This method supports simple authentication schemes, where only a single pass is necessary to open a session. For now, only the auth:inherent scheme is supported here; other schemes will be implemented in the future.

See also the auth:begin_cookie method.

You typically won't need to invoke this method yourself; instead, your RPC library (such as arti-rpc-client-core) should handle it for you.

auth:cookie_begin — Begin authenticating on an RPC connection, using Cookie authentication.

Begin authenticating on an RPC connection, using Cookie authentication.

In cookie authentication, both parties prove knowledge of a shared secret, written to a file on disk. This method does not prevent MITM attacks on its own.

When cookie authentication is in use, clients use this method to begin cookie authentication by telling the RPC server a temporary nonce.

You typically won't need to invoke this method yourself; instead, your RPC library (such as arti-rpc-client-core) should handle it for you.

See rpc-cookie-sketch.md for full details of this protocol.

auth:cookie_continue — Finish cookie authentication, returning a new RPC Session.

Finish cookie authentication, returning a new RPC Session.

You typically won't need to invoke this method yourself; instead, your RPC library (such as arti-rpc-client-core) should handle it for you.

After invoking this method, the RPC library should use rpc:release to drop its reference to the CookieAuthInProgress: remember, as a rule, RPC methods other than rpc:release do not consume the objects they are invoked on.

See rpc-cookie-sketch.md for full details of this protocol.

auth:query — Ask which authentication methods are supported.

Ask which authentication methods are supported.

This method can be invoked on a Connection pre-authentication; it's used to tell which methods are supported, and what parameters they require.

rpc:cancel — Cancel a single request.

Cancel a single request.

Note that calling this method does not guarantee that the request is actually cancelled: the request might finish first.

What we do guarantee is that either this method returns successfully and the request is cancelled, or that this method fails and the request is not cancelled. We also guarantee that both the request and this method will finish "fairly quickly" after this method is called.

In Arti's current implementation, a cancel request is itself is not cancellable.

For more information see rpc-meta-draft.md.

rpc:release — Release a single ObjectID.

Release a single ObjectID.

Only works if the ObjectID is strong reference (also known as a "handle"): see RPC specification for more information on the distinction. (We intend to relax this requirement in the future.)

After calling this method, the provided ObjectID will no longer be usable, but other ObjectIDs for the same object may still exist.

TODO RPC: Releasing a weak reference is perilous and hard-to-define based on how we have implemented our object ids. If you tell the objmap to "release" a single name for a weak reference, you are releasing every name for that weak reference, which may have surprising results. See also #838.

Objects

Object index

arti::rpc::session::ArtiRpcSession — A top-level RPC session object.

A top-level RPC session object.

This is the first object that an RPC user receives upon authenticating; It is returned by auth:authenticate.

Other objects (TorClient,RpcDataStream, etc) are available using methods on this object. (See the list of available methods.)

This type wraps and delegates to arti_rpcserver::RpcSession, but exposes additional functionality not available at the level of arti_rpcserver, including information about configured proxies.

This ObjectID for this object can be used as the target of a SOCKS stream.

arti_client::client::TorClient — An active client session on the Tor network.

An open client on the Tor network.

A TorClient can be used to open anonymous connections, and (eventually) perform other activities.

You can use an RpcSession as a TorClient, or use the isolated_client method to create a new TorClient whose stream will not share circuits with any other Tor client.

This ObjectID for this object can be used as the target of a SOCKS stream.

arti_rpcserver::connection::Connection — An open connection from an RPC client.

A connection to Arti.

This object is available as soon as you open a connection to Arti RPC, even before you authenticate. Its ObjectId is always "connection".

Because this object is available before authentication, it provides only those methods that you need in order to perform authentication and receive an RpcSession.

arti_rpcserver::connection::auth::cookie::CookieAuthInProgress — An in-progress cookie authentication attempt.

An in-progress cookie authentication attempt.

This object is returned by auth:cookie_begin; it can be used a single time with auth:cookie_continue to finish authentication.

arti_rpcserver::session::RpcSession — An authenticated RPC session: a capability through which most other RPC functionality is available

Base type for an authenticated RPC session.

Upon successful authentication via auth:authenticate, a connection will return either a Session object of this type, or a Session object that wraps this type. All other useful objects are available via an RPC session.

This ObjectID for this object can be used as the target of a SOCKS stream.