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