1/* 2 * Copyright (c) 2011-2014 Apple Inc. All Rights Reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24 25#ifndef _SECOTRSESSION_H_ 26#define _SECOTRSESSION_H_ 27 28#include <CoreFoundation/CFBase.h> 29#include <CoreFoundation/CFData.h> 30 31#include <Security/SecOTR.h> 32 33__BEGIN_DECLS 34 35// MARK: MessageTypes 36 37enum SecOTRSMessageKind { 38 kOTRNegotiationPacket, 39 kOTRDataPacket, 40 kOTRUnknownPacket 41}; 42 43// MARK: OTR Session 44 45enum SecOTRCreateFlags { 46 kSecOTRSendTextMessages = 1, // OTR messages will be encoded as Base-64 with header/footer per the standard, not just given back in binary 47 kSecOTRUseAppleCustomMessageFormat = 2, // OTR Messages will be encoded without revealing MAC keys and as compact as we can (P-256) 48}; 49 50/*! 51 @typedef 52 @abstract OTRSessions encapsulate a commuincaiton between to parties using the 53 otr protocol. 54 @discussion Sessions start with IDs. One end sends a start packet (created with AppendStartPacket). 55 Both sides process packets they exchange on the negotiation channel. 56 */ 57typedef struct _SecOTRSession* SecOTRSessionRef; 58 59SecOTRSessionRef SecOTRSessionCreateFromID(CFAllocatorRef allocator, 60 SecOTRFullIdentityRef myID, 61 SecOTRPublicIdentityRef theirID); 62 63SecOTRSessionRef SecOTRSessionCreateFromIDAndFlags(CFAllocatorRef allocator, 64 SecOTRFullIdentityRef myID, 65 SecOTRPublicIdentityRef theirID, 66 uint32_t flags); 67 68SecOTRSessionRef SecOTRSessionCreateFromData(CFAllocatorRef allocator, CFDataRef data); 69 70 void SecOTRSessionReset(SecOTRSessionRef session); 71OSStatus SecOTRSAppendSerialization(SecOTRSessionRef publicID, CFMutableDataRef serializeInto); 72 73OSStatus SecOTRSAppendStartPacket(SecOTRSessionRef session, CFMutableDataRef appendInitiatePacket); 74 75OSStatus SecOTRSAppendRestartPacket(SecOTRSessionRef session, CFMutableDataRef appendPacket); 76 77OSStatus SecOTRSProcessPacket(SecOTRSessionRef session, 78 CFDataRef incomingPacket, 79 CFMutableDataRef negotiationResponse); 80 81OSStatus SecOTRSEndSession(SecOTRSessionRef session, 82 CFMutableDataRef messageToSend); 83 84 85bool SecOTRSGetIsReadyForMessages(SecOTRSessionRef session); 86bool SecOTRSGetIsIdle(SecOTRSessionRef session); 87 88enum SecOTRSMessageKind SecOTRSGetMessageKind(SecOTRSessionRef session, CFDataRef incomingPacket); 89 90/*! 91 @function 92 @abstract Precalculates keys for current key sets to save time when sending or receiving. 93 @param session OTRSession receiving message 94 */ 95void SecOTRSPrecalculateKeys(SecOTRSessionRef session); 96 97/*! 98 @function 99 @abstract Encrypts and Signs a message with OTR credentials. 100 @param session OTRSession receiving message 101 @param incomingMessage Cleartext message to protect 102 @param protectedMessage Data to append the encoded protected message to 103 @result OSStatus errSecAuthFailed -> bad signature, no data appended. 104 */ 105 106OSStatus SecOTRSSignAndProtectMessage(SecOTRSessionRef session, 107 CFDataRef sourceMessage, 108 CFMutableDataRef protectedMessage); 109 110/*! 111 @function 112 @abstract Verifies and exposes a message sent via OTR 113 @param session OTRSession receiving message 114 @param incomingMessage Encoded message 115 @param exposedMessageContents Data to append the exposed message to 116 @result OSStatus errSecAuthFailed -> bad signature, no data appended. 117 */ 118 119OSStatus SecOTRSVerifyAndExposeMessage(SecOTRSessionRef session, 120 CFDataRef incomingMessage, 121 CFMutableDataRef exposedMessageContents); 122 123 124 125const char *SecOTRPacketTypeString(CFDataRef message); 126 127CFDataRef SecOTRSessionCreateRemote(CFDataRef publicPeerId, CFErrorRef *error); 128bool SecOTRSessionProcessPacketRemote(CFDataRef sessionData, CFDataRef inputPacket, CFDataRef* outputSessionData, CFDataRef* outputPacket, bool *readyForMessages, CFErrorRef *error); 129 130 131__END_DECLS 132 133#endif 134