]> git.saurik.com Git - apple/security.git/blob - sec/Security/SecOTRSession.h
Security-55471.14.8.tar.gz
[apple/security.git] / sec / Security / SecOTRSession.h
1 //
2 // SecOTRSession.h
3 // libsecurity_libSecOTR
4 //
5 // Created by Mitch Adler on 2/22/11.
6 // Copyright 2011 Apple Inc. All rights reserved.
7 //
8
9 #ifndef _SECOTRSESSION_H_
10 #define _SECOTRSESSION_H_
11
12 #include <CoreFoundation/CFBase.h>
13 #include <CoreFoundation/CFData.h>
14
15 #include <Security/SecOTR.h>
16
17 __BEGIN_DECLS
18
19 // MARK: MessageTypes
20
21 enum SecOTRSMessageKind {
22 kOTRNegotiationPacket,
23 kOTRDataPacket,
24 kOTRUnknownPacket
25 };
26
27 // MARK: OTR Session
28
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
31 };
32
33 /*!
34 @typedef
35 @abstract OTRSessions encapsulate a commuincaiton between to parties using the
36 otr protocol.
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.
39 */
40 typedef struct _SecOTRSession* SecOTRSessionRef;
41
42 SecOTRSessionRef SecOTRSessionCreateFromID(CFAllocatorRef allocator,
43 SecOTRFullIdentityRef myID,
44 SecOTRPublicIdentityRef theirID);
45
46 SecOTRSessionRef SecOTRSessionCreateFromIDAndFlags(CFAllocatorRef allocator,
47 SecOTRFullIdentityRef myID,
48 SecOTRPublicIdentityRef theirID,
49 uint32_t flags);
50
51 SecOTRSessionRef SecOTRSessionCreateFromData(CFAllocatorRef allocator, CFDataRef data);
52
53 void SecOTRSessionReset(SecOTRSessionRef session);
54 OSStatus SecOTRSAppendSerialization(SecOTRSessionRef publicID, CFMutableDataRef serializeInto);
55
56 OSStatus SecOTRSAppendStartPacket(SecOTRSessionRef session, CFMutableDataRef appendInitiatePacket);
57
58 OSStatus SecOTRSAppendRestartPacket(SecOTRSessionRef session, CFMutableDataRef appendPacket);
59
60 OSStatus SecOTRSProcessPacket(SecOTRSessionRef session,
61 CFDataRef incomingPacket,
62 CFMutableDataRef negotiationResponse);
63
64 OSStatus SecOTRSEndSession(SecOTRSessionRef session,
65 CFMutableDataRef messageToSend);
66
67
68 bool SecOTRSGetIsReadyForMessages(SecOTRSessionRef session);
69 bool SecOTRSGetIsIdle(SecOTRSessionRef session);
70
71 enum SecOTRSMessageKind SecOTRSGetMessageKind(SecOTRSessionRef session, CFDataRef incomingPacket);
72
73 /*!
74 @function
75 @abstract Precalculates keys for current key sets to save time when sending or receiving.
76 @param session OTRSession receiving message
77 */
78 void SecOTRSPrecalculateKeys(SecOTRSessionRef session);
79
80 /*!
81 @function
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.
87 */
88
89 OSStatus SecOTRSSignAndProtectMessage(SecOTRSessionRef session,
90 CFDataRef sourceMessage,
91 CFMutableDataRef protectedMessage);
92
93 /*!
94 @function
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.
100 */
101
102 OSStatus SecOTRSVerifyAndExposeMessage(SecOTRSessionRef session,
103 CFDataRef incomingMessage,
104 CFMutableDataRef exposedMessageContents);
105
106
107
108 const char *SecOTRPacketTypeString(CFDataRef message);
109
110 __END_DECLS
111
112 #endif