1//2// TORCircuit.h3// Tor4//5// Created by Benjamin Erhart on 11.12.19.6//7// Documentation this class is modelled after:89// https://gitlab.torproject.org/tpo/core/torspec/-/raw/main/control-spec.txt10// Chapter 4.1.1 Circuit status changed1112#import <Foundation/Foundation.h>13#import "TORNode.h"1415NS_ASSUME_NONNULL_BEGIN1617NS_SWIFT_NAME(TorCircuit)18@interface TORCircuit : NSObject<NSSecureCoding>1920/**21 Regular expression to identify and extract ID, status and circuit path consisting of "LongNames".2223 Syntax of node "LongNames":24 https://torproject.gitlab.io/torspec/control-spec.html#general-use-tokens25 */26@property (class, readonly) NSRegularExpression *mainInfoRegex;2728/**29 - Tag: statusLaunched30 Circuit ID assigned to new circuit.31 */32@property (class, readonly) NSString *statusLaunched;3334/**35 All hops finished, can now accept streams.36 */37@property (class, readonly) NSString *statusBuilt;3839/**40 All hops finished, waiting to see if a circuit with a better guard will be usable.41 */42@property (class, readonly) NSString *statusGuardWait;4344/**45 One more hop has been completed.46 */47@property (class, readonly) NSString *statusExtended;4849/**50 Circuit closed (was not built).51 */52@property (class, readonly) NSString *statusFailed;5354/**55 Circuit closed (was built).56 */57@property (class, readonly) NSString *statusClosed;5859/**60 One-hop circuit, used for tunneled directory conns.61 */62@property (class, readonly) NSString *buildFlagOneHopTunnel;6364/**65 Internal circuit, not to be used for exiting streams.66 */67@property (class, readonly) NSString *buildFlagIsInternal;6869/**70 This circuit must use only high-capacity nodes.71 */72@property (class, readonly) NSString *buildFlagNeedCapacity;7374/**75 This circuit must use only high-uptime nodes.76 */77@property (class, readonly) NSString *buildFlagNeedUptime;7879/**80 Circuit for AP and/or directory request streams.81 */82@property (class, readonly) NSString *purposeGeneral;8384/**85 HS client-side introduction-point circuit.86 */87@property (class, readonly) NSString *purposeHsClientIntro;8889/**90 HS client-side rendezvous circuit; carries AP streams.91 */92@property (class, readonly) NSString *purposeHsClientRend;9394/**95 HS service-side introduction-point circuit.96 */97@property (class, readonly) NSString *purposeHsServiceIntro;9899/**100 HS service-side rendezvous circuit.101 */102@property (class, readonly) NSString *purposeHsServiceRend;103104/**105 Circuit created ahead of time when using HS vanguards, and later repurposed as needed.106 */107@property (class, readonly) NSString *purposeHsVanguards;108109/**110 Reachability-testing circuit; carries no traffic.111 */112@property (class, readonly) NSString *purposeTesting;113114/**115 Circuit built by a controller.116 */117@property (class, readonly) NSString *purposeController;118119/**120 Circuit being kept around to see how long it takes.121 */122@property (class, readonly) NSString *purposeMeasureTimeout;123124/**125 Circuit is part of a conflux multi-path circuit set.126127 https://tpo.pages.torproject.net/core/doc/tor/structcircuit__t.html#a7826adee26af5def133c43d2fe5f83fa128 */129@property (class, readonly) NSString *purposeConfluxLinked;130131/**132 Circuit is in the pending pool usable in future circuit sets.133134 https://tpo.pages.torproject.net/core/doc/tor/structcircuit__t.html#acabcbac5225591a5b7731a6994f438e4135 */136@property (class, readonly) NSString *purposeConfluxUnlinked;137138/**139 Client-side introduction-point circuit state: Connecting to intro point.140 */141@property (class, readonly) NSString *hsStateHsciConnecting;142143/**144 Client-side introduction-point circuit state: Sent INTRODUCE1; waiting for reply from IP.145 */146@property (class, readonly) NSString *hsStateHsciIntroSent;147148/**149 Client-side introduction-point circuit state: Received reply from IP relay; closing.150 */151@property (class, readonly) NSString *hsStateHsciDone;152153/**154 Client-side rendezvous-point circuit state: Connecting to or waiting for reply from RP.155 */156@property (class, readonly) NSString *hsStateHscrConnecting;157158/**159 Client-side rendezvous-point circuit state: Established RP; waiting for introduction.160 */161@property (class, readonly) NSString *hsStateHscrEstablishedIdle;162163/**164 Client-side rendezvous-point circuit state: Introduction sent to HS; waiting for rend.165 */166@property (class, readonly) NSString *hsStateHscrEstablishedWaiting;167168/**169Client-side rendezvous-point circuit state: Connected to HS.170*/171@property (class, readonly) NSString *hsStateHscrJoined;172173/**174 Service-side introduction-point circuit state: Connecting to intro point.175 */176@property (class, readonly) NSString *hsStateHssiConnecting;177178/**179 Service-side introduction-point circuit state: Established intro point.180 */181@property (class, readonly) NSString *hsStateHssiEstablished;182183/**184 Service-side rendezvous-point circuit state: Connecting to client's rend point.185 */186@property (class, readonly) NSString *hsStateHssrConnecting;187188/**189 Service-side rendezvous-point circuit state: Connected to client's RP circuit.190 */191@property (class, readonly) NSString *hsStateHssrJoined;192193/**194 No reason given.195 */196@property (class, readonly) NSString *reasonNone;197198/**199 Tor protocol violation.200 */201@property (class, readonly) NSString *reasonTorProtocol;202203/**204 Internal error.205 */206@property (class, readonly) NSString *reasonInternal;207208/**209 A client sent a TRUNCATE command.210 */211@property (class, readonly) NSString *reasonRequested;212213/**214 Not currently operating; trying to save bandwidth.215 */216@property (class, readonly) NSString *reasonHibernating;217218/**219 Out of memory, sockets, or circuit IDs.220 */221@property (class, readonly) NSString *reasonResourceLimit;222223/**224 Unable to reach relay.225 */226@property (class, readonly) NSString *reasonConnectFailed;227228/**229 Connected to relay, but its OR identity was not as expected.230 */231@property (class, readonly) NSString *reasonOrIdentity;232233/**234 The OR connection that was carrying this circuit died.235 */236@property (class, readonly) NSString *reasonOrConnClosed;237238/**239 Circuit construction took too long.240 */241@property (class, readonly) NSString *reasonTimeout;242243/**244 The circuit has expired for being dirty or old.245 */246@property (class, readonly) NSString *reasonFinished;247248/**249 The circuit was destroyed w/o client TRUNCATE.250 */251@property (class, readonly) NSString *reasonDestroyed;252253/**254 Not enough nodes to make circuit.255 */256@property (class, readonly) NSString *reasonNoPath;257258/**259 Request for unknown hidden service.260 */261@property (class, readonly) NSString *reasonNoSuchService;262263/**264 As @c reasonTimeout, except that we had left the circuit open for measurement purposes to see how long it would take to finish.265 */266@property (class, readonly) NSString *reasonMeasurementExpired;267268269/**270 The raw data this object is constructed from. The unchanged argument from @c initFromString:.271 */272@property (readonly, nullable) NSString *raw;273274/**275The circuit ID. Currently only numbers beginning with "1" but Tor spec says, that could change.276 */277@property (readonly, nullable) NSString *circuitId;278279/**280 The circuit status. Should be one of @c statusLaunched, @c statusBuilt, @c statusGuardWait,281 @c statusExtended, @c statusFailed or @c statusClosed .282 */283@property (readonly, nullable) NSString *status;284285/**286 The circuit path as a list of @c TORNode objects.287 */288@property (readonly, nullable) NSArray<TORNode *>*nodes;289290/**291 Build flags of the circuit. Can be any of @c buildFlagOneHopTunnel, @c buildFlagIsInternal,292 @c buildFlagNeedCapacity, @c buildFlagNeedUptime or a flag which was unknown at the time of293 writing of this class.294*/295@property (readonly, nullable) NSArray<NSString *>*buildFlags;296297/**298 Circuit purpose. May be one of @c purposeGeneral, @c purposeHsClientIntro,299 @c purposeHsClientRend, @c purposeHsServiceIntro, @c purposeHsServiceRend,300 @c purposeTesting, @c purposeController or, @c purposeMeasureTimeout.301 */302@property (readonly, nullable) NSString *purpose;303304/**305 Circuit hidden service state. May be one of @c hsStateHsciConnecting, @c hsStateHsciIntroSent,306 @c hsStateHsciDone, @c hsStateHscrConnecting, @c hsStateHscrEstablishedIdle,307 @c hsStateHscrEstablishedWaiting, @c hsStateHscrJoined, @c hsStateHssiConnecting,308 @c hsStateHssiEstablished, @c hsStateHssrConnecting, @c hsStateHssrJoined309 or a state which was unknown at the time of writing of this class.310 */311@property (readonly, nullable) NSString *hsState;312313/**314 The rendevouz query.315316 Should be equal the onion address this circuit was used for minus the @c .onion postfix.317 */318@property (readonly, nullable) NSString *rendQuery;319320/**321 The circuit's timestamp at which the circuit was created or cannibalized.322 */323@property (readonly, nullable) NSDate *timeCreated;324325/**326 The @c reason field is provided only for @c FAILED and @c CLOSED events, and only if327 extended events are enabled.328329 May be any one of @c reasonNone, @c reasonTorProtocol, @c reasonInternal,330 @c reasonRequested, @c reasonHibernating, @c reasonResourceLimit,331 @c reasonConnectFailed, @c reasonOrIdentity, @c reasonOrConnClosed,332 @c reasonTimeout, @c reasonFinished, @c reasonDestroyed, @c reasonNoPath,333 @c reasonNoSuchService, @c reasonMeasurementExpired or a reason which was unknown at the334 time of writing of this class.335 */336@property (readonly, nullable) NSString *reason;337338/**339 The @c remoteReason field is provided only when we receive a @c DESTROY or @c TRUNCATE cell, and340 only if extended events are enabled. It contains the actual reason given by the remote OR for closing the circuit.341342 May be any one of @c reasonNone, @c reasonTorProtocol, @c reasonInternal,343 @c reasonRequested, @c reasonHibernating, @c reasonResourceLimit,344 @c reasonConnectFailed, @c reasonOrIdentity, @c reasonOrConnClosed,345 @c reasonTimeout, @c reasonFinished, @c reasonDestroyed, @c reasonNoPath,346 @c reasonNoSuchService, @c reasonMeasurementExpired or a reason which was unknown at the347 time of writing of this class.348 */349@property (readonly, nullable) NSString *remoteReason;350351/**352 The @c socksUsername and @c socksPassword fields indicate the credentials that were used by a353 SOCKS client to connect to Tor’s SOCKS port and initiate this circuit.354 */355@property (readonly, nullable) NSString *socksUsername;356357/**358The @c socksUsername and @c socksPassword fields indicate the credentials that were used by a359SOCKS client to connect to Tor’s SOCKS port and initiate this circuit.360*/361@property (readonly, nullable) NSString *socksPassword;362363364/**365Extracts all circuit info from a string which should be the response to a "GETINFO circuit-status".366367See https://torproject.gitlab.io/torspec/control-spec.html#getinfo368369@param circuitsString A string as returned by "GETINFO circuit-status".370*/371+(NSArray<TORCircuit *>*)circuitsFromString:(NSString *)circuitsString;372373374-(instancetype)initFromString:(NSString *)circuitString;375376377@end378379NS_ASSUME_NONNULL_END