@@ -1,7 +1,7 @@ /* - * Copyright (c) 2008-2021 Jonathan Schleifer + * Copyright (c) 2008-2022 Jonathan Schleifer * * All rights reserved. * * This file is part of ObjFW. It may be distributed under the terms of the * Q Public License 1.0, which can be found in the file LICENSE.QPL included in @@ -11,174 +11,166 @@ * Public License, either version 2 or 3, which can be found in the file * LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this * file. */ -#import "OFObject.h" +#import "OFStream.h" +#import "OFRunLoop.h" OF_ASSUME_NONNULL_BEGIN -@class OFString; -@class OFDictionary OF_GENERIC(KeyType, ObjectType); -@protocol OFTLSSocket; - -/** - * @protocol OFTLSSocketDelegate OFTLSSocket.h ObjFW/OFTLSSocket.h - * - * @brief A delegate for classes implementing the OFTLSSocket protocol. - */ -@protocol OFTLSSocketDelegate -@optional -/** - * @brief This callback is called when the TLS socket wants to know if it - * should accept the received certificate. - * - * @note This is only used to verify certain fields of a certificate to allow - * for protocol specific verification. The certificate chain is verified - * using the specified CAs, or the system's CAs if no CAs have been - * specified. - * - * @param socket The socket which wants to know if it should accept the received - * certificate - * @param certificate A dictionary with the fields of the received certificate - * @return Whether the TLS socket should accept the received certificate chain - */ -- (bool)socket: (id )socket - shouldAcceptCertificate: (OFDictionary *)certificate; -@end - -/** - * @protocol OFTLSSocket OFTLSSocket.h ObjFW/OFTLSSocket.h - * - * @brief A protocol that should be implemented by 3rd-party libraries - * implementing TLS. - */ -@protocol OFTLSSocket -/** - * @brief The delegate for the TLS socket. - */ -@property OF_NULLABLE_PROPERTY (assign, nonatomic) - id delegate; - -/** - * @brief The path to the X.509 certificate file to use. - */ -@property OF_NULLABLE_PROPERTY (copy, nonatomic) OFString *certificateFile; - -/** - * @brief The path to the PKCS#8 private key file to use. - */ -@property OF_NULLABLE_PROPERTY (copy, nonatomic) OFString *privateKeyFile; - -/** - * @brief The passphrase to decrypt the PKCS#8 private key file. - * - * @warning You have to ensure that this is in secure memory protected from - * swapping! This is also the reason why this is not an OFString. - */ -@property OF_NULLABLE_PROPERTY (assign, nonatomic) - const char *privateKeyPassphrase; - -/** - * @brief Whether certificates are verified. - * - * The default is enabled. - */ -@property (nonatomic) bool verifiesCertificates; - -/** - * @brief Initializes the TLS socket with the specified TCP socket as its - * underlying socket. - * - * @param socket The TCP socket to use as underlying socket - */ -- (instancetype)initWithSocket: (OFTCPSocket *)socket; - -/** - * @brief Initiates the TLS handshake. - * - * @note This is only useful if you used @ref initWithSocket: to start TLS on - * a TCP socket which is already connected! - * - * @param host The host to expect for certificate verification. - * May be `nil` if certificate verification is disabled. - */ -- (void)startTLSWithExpectedHost: (nullable OFString *)host; - -/** - * @brief Sets the path to the X.509 certificate file to use for the specified - * SNI host. - * - * @param SNIHost The SNI host for which the path of the X.509 certificate file - * should be set - * - * @param certificateFile The path to the X.509 certificate file - */ -- (void)setCertificateFile: (OFString *)certificateFile - forSNIHost: (OFString *)SNIHost; - -/** - * @brief Returns the path of the X.509 certificate file used by the TLS socket - * for the specified SNI host. - * - * @param SNIHost The SNI host for which the path of the X.509 certificate file - * should be returned - * - * @return The path of the X.509 certificate file used by the TLS socket for - * the specified SNI host - */ -- (nullable OFString *)certificateFileForSNIHost: (OFString *)SNIHost; - -/** - * @brief Sets the path to the PKCS#8 private key file to use for the specified - * SNI host. - * - * @param privateKeyFile The path to the PKCS#8 private key file - * @param SNIHost The SNI host for which the path to the PKCS#8 private key - * file should be set - */ -- (void)setPrivateKeyFile: (OFString *)privateKeyFile - forSNIHost: (OFString *)SNIHost; - -/** - * @brief Returns the path of the PKCS#8 private key file used by the TLS - * socket for the specified SNI host. - * - * @param SNIHost The SNI host for which the path of the PKCS#8 private key - * file should be returned - * - * @return The path of the PKCS#8 private key file used by the TLS socket for - * the specified SNI host - */ -- (nullable OFString *)privateKeyFileForSNIHost: (OFString *)SNIHost; - -/** - * @brief Sets the passphrase to decrypt the PKCS#8 private key file for the - * specified SNI host. - * - * @warning You have to ensure that this is in secure memory protected from - * swapping! This is also the reason why this is not an OFString. - * - * @param privateKeyPassphrase The passphrase to decrypt the PKCS#8 private - * key file for the specified SNI host - * @param SNIHost The SNI host for which the passphrase to decrypt the PKCS#8 - * private key file should be set - */ -- (void)setPrivateKeyPassphrase: (const char *)privateKeyPassphrase - forSNIHost: (OFString *)SNIHost; - -/** - * @brief Returns the passphrase to decrypt the PKCS#8 private key file for the - * specified SNI host. - * - * @warning You should not copy this to insecure memory which is swappable! - * - * @param SNIHost The SNI host for which the passphrase to decrypt the PKCS#8 - * private key file should be returned - * - * @return The passphrase to decrypt the PKCS#8 private key file for the - * specified SNI host - */ -- (nullable const char *)privateKeyPassphraseForSNIHost: (OFString *)SNIHost; -@end +/** @file */ + +@class OFTLSStream; + +/** + * @brief An enum representing an error of an OFTLSStream. + */ +typedef enum { + /** @brief An unknown error. */ + OFTLSStreamErrorCodeUnknown, + /** @brief Initialization of the TLS context failed. */ + OFTLSStreamErrorCodeInitializationFailed +} OFTLSStreamErrorCode; + +/** + * @protocol OFTLSStreamDelegate OFTLSStream.h ObjFW/OFTLSStream.h + * + * A delegate for OFTLSStream. + */ +@protocol OFTLSStreamDelegate +/** + * @brief A method which is called when a TLS stream performed the client + * handshake. + * + * @param stream The TLS stream which performed the handshake + * @param host The host for which the handshake was performed + * @param exception An exception that occurred during the handshake, or nil on + * success + */ +- (void)stream: (OFTLSStream *)stream + didPerformClientHandshakeWithHost: (OFString *)host + exception: (nullable id)exception; +@end + +/** + * @class OFTLSStream OFTLSStream.h ObjFW/OFTLSStream.h + * + * @brief A class that provides Transport Layer Security on top of a stream. + * + * This class is a class cluster and returns a suitable OFTLSStream subclass, + * if available. + * + * Subclasses need to override @ref lowlevelReadIntoBuffer:length:, + * @ref lowlevelWriteBuffer:length: and + * @ref asyncPerformClientHandshakeWithHost:runLoopMode:. The method + * @ref hasDataInReadBuffer should be overridden to return `true` if the TLS + * stream has cached unprocessed data internally, while returning + * `self.underlyingStream.hasDataInReadBuffer` if it does not have any + * unprocessed data. In order to get access to the underlying stream, + * @ref underlyingStream can be used. + */ +@interface OFTLSStream: OFStream +{ + OFStream + *_underlyingStream; + bool _verifiesCertificates; + OF_RESERVE_IVARS(OFTLSStream, 4) +} + +/** + * @brief The underlying stream. + */ +@property (readonly, nonatomic) OFStream *underlyingStream; + +/** + * @brief The delegate for asynchronous operations on the stream. + * + * @note The delegate is retained for as long as asynchronous operations are + * still ongoing. + */ +@property OF_NULLABLE_PROPERTY (assign, nonatomic) + id delegate; + +/** + * @brief Whether certificates are verified. Default is true. + */ +@property (nonatomic) bool verifiesCertificates; + +- (instancetype)init OF_UNAVAILABLE; + +/** + * @brief Creates a new TLS stream with the specified stream as its underlying + * stream. + * + * @param stream The stream to use as underlying stream. Must not be closed + * before the TLS stream is closed. + * @return A new, autoreleased TLS stream + */ ++ (instancetype)streamWithStream: (OFStream *)stream; + +/** + * @brief Initializes the TLS stream with the specified stream as its + * underlying stream. + * + * @param stream The stream to use as underlying stream. Must not be closed + * before the TLS stream is closed. + * @return An initialized TLS stream + */ +- (instancetype)initWithStream: (OFStream *)stream + OF_DESIGNATED_INITIALIZER; + +/** + * @brief Asynchronously performs the TLS client handshake for the specified + * host and calls the delegate afterwards. + * + * @param host The host to perform the handshake with + */ +- (void)asyncPerformClientHandshakeWithHost: (OFString *)host; + +/** + * @brief Asynchronously performs the TLS client handshake for the specified + * host and calls the delegate afterwards. + * + * @param host The host to perform the handshake with + * @param runLoopMode The run loop mode in which to perform the async handshake + */ +- (void)asyncPerformClientHandshakeWithHost: (OFString *)host + runLoopMode: (OFRunLoopMode)runLoopMode; + +/** + * @brief Performs the TLS client handshake for the specified host. + * + * @param host The host to perform the handshake with + */ +- (void)performClientHandshakeWithHost: (OFString *)host; +@end + +#ifdef __cplusplus +extern "C" { +#endif +/** + * @brief The implementation for OFTLSStream to use. + * + * This can be set to a class that is always used for OFTLSStream. This is + * useful to either force a specific implementation or use one that ObjFW does + * not know about. + */ +extern Class OFTLSStreamImplementation; + +/** + * @brief Returns a string description for the TLS stream error code. + * + * @param errorCode The error code to return the description for + * @return A string description for the TLS stream error code + */ +extern OFString *OFTLSStreamErrorCodeDescription( + OFTLSStreamErrorCode errorCode); +#ifdef __cplusplus +} +#endif OF_ASSUME_NONNULL_END