OTRKit is an Objective-C wrapper for the OTRv3 encrypted messaging protocol, using libotr. This library was designed for use with the encrypted iOS messaging app ChatSecure, but should theoretically work for Mac OS X as well with some minor tweaking to the build scripts.
- libgpg-error v1.19 - 2015-4-10
- libgcrypt v1.6.3 - 2015-02-27
- libotr v4.1.0 - 21 Oct 2014
To compile libotr and dependencies for iOS, run the included script, build-all.sh
.
$ bash build-all.sh
We now support Cocoapods but haven't pushed OTRKit.podspec
to the public repository yet. Feel free to use the one in this repo in the meantime, but the public API may change slightly before release.
pod 'OTRKit', :git => 'https://github.com/ChatSecure/OTRKit.git'
Check out OTRKit.h because it is the most up-to-date reference at the moment.
Implement the required delegate methods somewhere that makes sense for your project.
@protocol OTRKitDelegate <NSObject>
@required
/**
* This method **MUST** be implemented or OTR will not work. All outgoing messages
* should be sent first through OTRKit encodeMessage and then passed from this delegate
* to the appropriate chat protocol manager to send the actual message.
*
* @param otrKit reference to shared instance
* @param message message to be sent over the network. may contain ciphertext.
* @param recipient intended recipient of the message
* @param accountName your local account name
* @param protocol protocol for account name such as "xmpp"
* @param tag optional tag to attached to message. Only used locally.
*/
- (void) otrKit:(OTRKit*)otrKit
injectMessage:(NSString*)message
username:(NSString*)username
accountName:(NSString*)accountName
protocol:(NSString*)protocol
tag:(id)tag;
/**
* All outgoing messages should be sent to the OTRKit encodeMessage method before being
* sent over the network.
*
* @param otrKit reference to shared instance
* @param message plaintext message
* @param sender buddy who sent the message
* @param accountName your local account name
* @param protocol protocol for account name such as "xmpp"
* @param tag optional tag to attach additional application-specific data to message. Only used locally.
*/
- (void) otrKit:(OTRKit*)otrKit
encodedMessage:(NSString*)encodedMessage
username:(NSString*)username
accountName:(NSString*)accountName
protocol:(NSString*)protocol
tag:(id)tag
error:(NSError*)error;
/**
* All incoming messages should be sent to the OTRKit decodeMessage method before being
* processed by your application. You should only display the messages coming from this delegate method.
*
* @param otrKit reference to shared instance
* @param message plaintext message
* @param tlvs OTRTLV values that may be present.
* @param sender buddy who sent the message
* @param accountName your local account name
* @param protocol protocol for account name such as "xmpp"
* @param tag optional tag to attach additional application-specific data to message. Only used locally.
*/
- (void) otrKit:(OTRKit*)otrKit
decodedMessage:(NSString*)decodedMessage
tlvs:(NSArray*)tlvs
username:(NSString*)username
accountName:(NSString*)accountName
protocol:(NSString*)protocol
tag:(id)tag;
/**
* When the encryption status changes this method is called
*
* @param otrKit reference to shared instance
* @param messageState plaintext, encrypted or finished
* @param username buddy whose state has changed
* @param accountName your local account name
* @param protocol protocol for account name such as "xmpp"
*/
- (void) otrKit:(OTRKit*)otrKit
updateMessageState:(OTRKitMessageState)messageState
username:(NSString*)username
accountName:(NSString*)accountName
protocol:(NSString*)protocol;
...
To encode a message:
/**
* Encodes a message and optional array of OTRTLVs, splits it into fragments,
* then injects the encoded data via the injectMessage: delegate method.
* @param message The message to be encoded
* @param tlvs Array of OTRTLVs, the data length of each TLV must be smaller than UINT16_MAX or it will be ignored.
* @param recipient The intended recipient of the message
* @param accountName Your account name
* @param protocol the protocol of accountName, such as @"xmpp"
* @param tag optional tag to attach additional application-specific data to message. Only used locally.
*/
- (void)encodeMessage:(NSString*)message
tlvs:(NSArray*)tlvs
username:(NSString*)username
accountName:(NSString*)accountName
protocol:(NSString*)protocol
tag:(id)tag;
To decode a message:
/**
* All messages should be sent through here before being processed by your program.
*
* @param message Encoded or plaintext incoming message
* @param sender account name of buddy who sent the message
* @param accountName your account name
* @param protocol the protocol of accountName, such as @"xmpp"
* @param tag optional tag to attach additional application-specific data to message. Only used locally.
*/
- (void)decodeMessage:(NSString*)message
username:(NSString*)username
accountName:(NSString*)accountName
protocol:(NSString*)protocol
tag:(id)tag;
- Documentation!
- Add Mac OS X support
- Tests
Please fork the project and submit a pull request and (preferrably) squash your commits. Thank you! If you're interested in privacy and security, check out chatsecure.org and The Guardian Project.
The code for this project is dual licensed under the LGPLv2.1+ and MPL 2.0. The required dependencies are under terms of a seperate license (LGPL). More information is available in the LICENSE file.