3 // libsecurity_libSecOTR
5 // Created by Mitch Adler on 2/22/11.
6 // Copyright 2011 Apple Inc. All rights reserved.
9 #ifndef _SECOTRSESSION_H_
10 #define _SECOTRSESSION_H_
12 #include <CoreFoundation/CFBase.h>
13 #include <CoreFoundation/CFData.h>
15 #include <Security/SecOTR.h>
21 enum SecOTRSMessageKind
{
22 kOTRNegotiationPacket
,
29 enum SecOTRCreateFlags
{
30 kSecOTRSendTextMessages
= 1, // OTR messages will be encoded as Base-64 with header/footer per the standard, not just given back in binary
35 @abstract OTRSessions encapsulate a commuincaiton between to parties using the
37 @discussion Sessions start with IDs. One end sends a start packet (created with AppendStartPacket).
38 Both sides process packets they exchange on the negotiation channel.
40 typedef struct _SecOTRSession
* SecOTRSessionRef
;
42 SecOTRSessionRef
SecOTRSessionCreateFromID(CFAllocatorRef allocator
,
43 SecOTRFullIdentityRef myID
,
44 SecOTRPublicIdentityRef theirID
);
46 SecOTRSessionRef
SecOTRSessionCreateFromIDAndFlags(CFAllocatorRef allocator
,
47 SecOTRFullIdentityRef myID
,
48 SecOTRPublicIdentityRef theirID
,
51 SecOTRSessionRef
SecOTRSessionCreateFromData(CFAllocatorRef allocator
, CFDataRef data
);
53 void SecOTRSessionReset(SecOTRSessionRef session
);
54 OSStatus
SecOTRSAppendSerialization(SecOTRSessionRef publicID
, CFMutableDataRef serializeInto
);
56 OSStatus
SecOTRSAppendStartPacket(SecOTRSessionRef session
, CFMutableDataRef appendInitiatePacket
);
58 OSStatus
SecOTRSAppendRestartPacket(SecOTRSessionRef session
, CFMutableDataRef appendPacket
);
60 OSStatus
SecOTRSProcessPacket(SecOTRSessionRef session
,
61 CFDataRef incomingPacket
,
62 CFMutableDataRef negotiationResponse
);
64 OSStatus
SecOTRSEndSession(SecOTRSessionRef session
,
65 CFMutableDataRef messageToSend
);
68 bool SecOTRSGetIsReadyForMessages(SecOTRSessionRef session
);
69 bool SecOTRSGetIsIdle(SecOTRSessionRef session
);
71 enum SecOTRSMessageKind
SecOTRSGetMessageKind(SecOTRSessionRef session
, CFDataRef incomingPacket
);
75 @abstract Precalculates keys for current key sets to save time when sending or receiving.
76 @param session OTRSession receiving message
78 void SecOTRSPrecalculateKeys(SecOTRSessionRef session
);
82 @abstract Encrypts and Signs a message with OTR credentials.
83 @param session OTRSession receiving message
84 @param incomingMessage Cleartext message to protect
85 @param protectedMessage Data to append the encoded protected message to
86 @result OSStatus errSecAuthFailed -> bad signature, no data appended.
89 OSStatus
SecOTRSSignAndProtectMessage(SecOTRSessionRef session
,
90 CFDataRef sourceMessage
,
91 CFMutableDataRef protectedMessage
);
95 @abstract Verifies and exposes a message sent via OTR
96 @param session OTRSession receiving message
97 @param incomingMessage Encoded message
98 @param exposedMessageContents Data to append the exposed message to
99 @result OSStatus errSecAuthFailed -> bad signature, no data appended.
102 OSStatus
SecOTRSVerifyAndExposeMessage(SecOTRSessionRef session
,
103 CFDataRef incomingMessage
,
104 CFMutableDataRef exposedMessageContents
);
108 const char *SecOTRPacketTypeString(CFDataRef message
);