SophaxChat/Tor/TorFramework/TORAuthKey.h

1//
2//  TORAuthKey.h
3//  Tor
4//
5//  Created by Benjamin Erhart on 29.09.21.
6//
7
8#import <Foundation/Foundation.h>
9
10NS_ASSUME_NONNULL_BEGIN
11
12/**
13 The representation of one private or public v3 onion service authentication key.
14 */
15NS_SWIFT_NAME(TorAuthKey)
16@interface TORAuthKey : NSObject
17
18/**
19 The location on disk, where this data was read from/will be written to.
20 */
21@property (nonatomic, readonly, nonnull) NSURL *file;
22
23/**
24 Flag, if this is a private (\c YES) or a public (\c NO) key.
25 */
26@property (atomic, readonly) BOOL isPrivate;
27
28/**
29 The full  onion service URL.
30 */
31@property (nonatomic, readonly, nullable) NSURL *onionAddress;
32
33/**
34 The authentication type.
35
36Currently only the \c descriptor type is supported. This class will set this value hard for you.
37 */
38@property (nonatomic, readonly, nonnull) NSString *authType;
39
40/**
41 The key type.
42
43 Currently only \c x25519 is supported. This class will set this value hard for you.
44 Make sure, that the key you provide actually is of that type!
45 */
46@property (nonatomic, readonly, nonnull) NSString *keyType;
47
48/**
49 The actual public OR private key.
50
51 This class doesn't enforce it, but Tor wants this to be in a BASE32 encoded format.
52
53 Make sure, it is of the type \c x25519, as this is currently the only supported type by Tor and by this class!
54 */
55@property (nonatomic, readonly, nonnull) NSString *key;
56
57
58/**
59 Load from a key file on disk.
60
61 See https://2019.www.torproject.org/docs/tor-manual.html.en#ClientOnionAuthDir
62 and https://2019.www.torproject.org/docs/tor-manual.html.en#_client_authorization
63 for the expected format.
64
65 @param url The URL to the file containing the key. Expected to be in the correct format.
66 */
67- (instancetype)initFromUrl:(NSURL *)url;
68
69/**
70 Load from a key file on disk.
71
72 See https://2019.www.torproject.org/docs/tor-manual.html.en#ClientOnionAuthDir
73 and https://2019.www.torproject.org/docs/tor-manual.html.en#_client_authorization
74 for the expected format.
75
76 @param path The path to the file containing the key. Expected to be in the correct format.
77 */
78- (instancetype)initFromFile:(NSString *)path;
79
80/**
81 Create a new private key for a given domain.
82
83 Normally, the domain will be used as file name, but this method will generate a UUID, if no domain can be found.
84
85 @param key A \c BASE32 encoded \c x25519 private key.
86 @param url A URL containing the v3 onion service domain for which this key is.
87 */
88- (instancetype)initPrivate:(NSString * _Nonnull)key forDomain:(NSURL * _Nonnull)url;
89
90/**
91 Create a new public key with the given name.
92
93 The name wil be used as the file name.
94
95 @param key A \c BASE32 encoded \c x25519 public key.
96 @param name A name to identify this key to be used as the file name.
97 */
98- (instancetype)initPublic:(NSString * _Nonnull)key withName: (NSString *)name;
99
100
101/**
102 Set the base directory for the key.
103
104 This needs to be called \b before \c persist, if you created a fresh key.
105
106 @param directory The base directory where this key should be persisted.
107
108 @see -persist
109 */
110- (void)setDirectory:(NSURL *)directory;
111
112/**
113 Persists this key to the file system.
114
115 Call \c setDirectory:, if this instance wasn't created by reading a key from a file!
116
117 @returns \c YES on success, \c NO on failure.
118
119 @see -setDirectory:
120 */
121- (BOOL)persist;
122
123/**
124 Keys are considered equal, if their file URLs match.
125 */
126- (BOOL)isEqualToAuthKey:(TORAuthKey *)authKey;
127
128
129/**
130 Checks, if the given file name has the correct extension for either a private or public key.
131
132 @param url A file URL to a key file.
133
134 @returns \c YES, if this URL contains a key file extension.
135 */
136+ (BOOL)isAuthFile:(NSURL *)url;
137
138@end
139
140NS_ASSUME_NONNULL_END