SophaxChat/Tor/TorFramework/TORX25519KeyPair.h

1//
2//  TORX25519KeyPair.h
3//  Tor
4//
5//  Created by Benjamin Erhart on 11.10.21.
6//
7
8#import <Foundation/Foundation.h>
9#import "TORAuthKey.h"
10
11NS_ASSUME_NONNULL_BEGIN
12
13/**
14 Class to generate or hold a X25519 public/private key pair encoded in BASE32.
15 */
16NS_SWIFT_NAME(TorX25519KeyPair)
17@interface TORX25519KeyPair : NSObject
18
19
20/**
21 The BASE32 encoded private key. Should be exactly 32 bytes long, resp. 52 characters in BASE32 encoding.
22 */
23@property (nonatomic, nullable, readonly) NSString *privateKey;
24
25/**
26 The BASE32 encoded public key. Should be exactly 32 bytes long, resp. 52 characters in BASE32 encoding.
27 */
28@property (nonatomic, nullable, readonly) NSString *publicKey;
29
30
31/**
32 Generate a new X25519 key pair using Tor's implementation.
33
34 On iOS 13 and up, another option is also available: CryptoKit's \c Curve25519.KeyAggreement.PrivateKey
35 */
36- (instancetype)init;
37
38/**
39 Initialize with a pre-generated, BASE32-encoded X25519 key pair. A valid key pair is exactly 32 bytes long,
40 resp. 52 characters in BASE32 encoding.
41
42 No validity checks are made! It's your responsibility to provide valid key material.
43
44 @param privateKey The private key, BASE32 encoded.
45 @param publicKey The public key, BASE32 encoded.
46 */
47- (instancetype)initWithBase32PrivateKey:(NSString *)privateKey andPublicKey:(NSString *)publicKey;
48
49/**
50 Initialize with a pre-generated X25519 key pair. A valid key pair is exactly 32 bytes long.
51
52 No validity checks are made! It's your responsibility to provide valid key material.
53
54 @param privateKey The private key.
55 @param publicKey The public key.
56  */
57- (instancetype)initWithPrivateKey:(NSData *)privateKey andPublicKey:(NSData *)publicKey;
58
59
60/**
61 Create a private \c TORAuthKey from this key material using the provided domain.
62
63 @param domain The domain name, this private key is for. Must include the \c .onion TLD!
64 @returns the private \c TORAuthKey of this key pair's private key  or \c nil if the \c domain is empty or this class doesn't contain a private key.
65*/
66- (nullable TORAuthKey *)getPrivateAuthKeyForDomain:(nonnull NSString *)domain;
67
68/**
69 Create a private \c TORAuthKey from this key material using the provided domain.
70
71 @param url The domain, this private key is for.
72 @returns the private \c TORAuthKey of this key pair's private key  or \c nil if this class doesn't contain a private key.
73*/
74- (nullable TORAuthKey *)getPrivateAuthKeyForUrl:(nonnull NSURL *)url;
75
76/**
77 Create a public \c TORAuthKey from this key material using the provided name.
78
79 @param name The name used to store that \c TORAuthKey, without the extension!
80 @returns the public \c TORAuthKey of this key pair's public key or \c nil if the \c name is empty or this class doesn't contain a public key.
81 */
82- (nullable TORAuthKey *)getPublicAuthKeyWithName:(nonnull NSString *)name;
83
84
85/**
86 Helper method to BASE32 encode raw binary \c NSData into a \c NSString.
87
88 @param raw The raw binary \c NSData to encode.
89 @returns a BASE32 encoded representation of that binary data.
90 */
91+ (nullable NSString *)base32Encode:(NSData *)raw;
92
93/**
94 Helper method to decode raw binary \c NSData contained in a BASE32 encoded \c NSString.
95
96 @param encoded The BASE32 encoded data  to decode.
97 @returns binary data.
98 */
99+ (nullable NSData *)base32Decode:(NSString *)encoded;
100
101
102@end
103
104NS_ASSUME_NONNULL_END