security.h

伯克利做的SFTP安全文件传输协议

// security.h
// defines security protocol interfaces
//   (security.h is *protocol* primitives,
//    trans.h is *cryptographic* primitives)
// copyright SafeTP Development Group, Inc., 2000  Terms of use are as specified in license.txt

#ifndef __SECURITY_H
#define __SECURITY_H

#include "trans.h"        // Trans
#include "exc.h"          // exceptions
#include "socketd.h"      // IPAddress

// exception to raise when there has been a possible attack
// e.g., THROW(xSecurity("All hell has broken loose!"));
class xSecurity : public xBase {
public:
  xSecurity(char const *msg) : xBase(msg) {}
  xSecurity(xSecurity const &obj) : xBase(obj) {}
  ~xSecurity() {}
};

// obviates need to use THROW, which VC sometimes needs
// handholding to make work
void xsecurity(char const *msg);


// an object of this type knows how to encrypt outgoing data and
// decrypt incoming data; however, encryption and decryption are
// not necessarily inverses (e.g., they might use different keys
// or different algorithms)
class SecureEndpoint {
public:
  // size relationships, for allocating buffers in advance
  virtual int maximumEncodedSize(int decodedSize) const=0;
  virtual int maximumDecodedSize(int encodedSize) const=0;

  // encrypt and decrypt, themselves; data is modified in-place
  virtual void encode(DataBlock &data)=0;
  virtual void decode(DataBlock &data)=0;

  // test that two endpoints can communicate; return false on error
  bool testWithEndpoint(SecureEndpoint &other,
                        int iters, bool echo=false);

  // this isn't necessary, but it pacifies g++, and doesn't hurt
  virtual ~SecureEndpoint() {}
};


// useful for testing, and possible other places:
// treat a protocol endpoint as a transformation
class EndpointAsTrans : public Trans {
private:     // data
  SecureEndpoint &endpoint;
  bool encode;       // true=encode, false=decode

public:
  EndpointAsTrans(SecureEndpoint &pt, bool enc)
    : endpoint(pt), encode(enc) {}

  virtual int minOutputSize(int inputSize) const;
  virtual int maxOutputSize(int inputSize) const;
  virtual void trans(DataBlock &data);
};



// levels of data protection; implementations of DataSecurity are
// not required to support all of them; while the implementation of
// each security level is left up to the DataSecurity implementation,
// each level defines a specific over-the-wire protocol
//
// note that while there is an obvious parallel between the levels
// currently defined and the PROT levels of RFC 2228, there are
// several important differences -- see comments at end of file
enum DataSecurityLevel {
  DSL_CLEAR = 1,               // data in the clear; no protection
  DSL_INTEGRITY = 2,           // data protected from tampering
  DSL_CONFIDENTIAL = 4,        // data protected from eavesdropping
  DSL_PRIVATE = 8,             // both integrity and confidentiality

  DSL_NONE = 0,                // no bits set
  DSL_ALL_LEVELS = 0xF,        // all bits set; last item in enum
};

// maps the single-1-bit constants to corresponding strings
char const *getDSLString(DataSecurityLevel level);


// data-channel security mechanism
class DataSecurity : public SecureEndpoint {
public:
  virtual DataSecurityLevel getSupportedProtLevels() const;
    // call this to retrieve the protocol-supported data channel
    // security characteristics as a bitmap of the DataSecurityLevel
    // constants

  virtual void newFile(DataSecurityLevel level);
    // call this to indicate that the transform is about to be used
    // to encrypt data from a new file (e.g., this might increment
    // a per-file sequence #) -- this MUST be called before the first
    // call to encode or decode
    //
    // 'level' indicates the required data channel security level
    // for this transfer; it must be among those returned by
    // getSupportedProtLevels() (the default implementation simply
    // checks this)

  virtual char getCodeForLevel(DataSecurityLevel level) const;
    // given a single level from among those supported, return the
    // single-character code that stands for it in a PROT command

  virtual DataSecurityLevel getLevelForCode(char code) const;
    // given a single-character code, map that to a level, or return
    // DSL_NONE if it is an invalid code

  virtual int maximumCleartextSizeForBlock(int maxBlockSize) const;
    // maximum x, such that there is no size s <= x such that
    // maximumEncodedSize(s) > maxBlockSize
    //
    // this value should be the maximum over *all* supported 
    // DataSecurityLevels, and *not* simply the max for the current
    // level (if any -- this fn can be called before newFile)

  virtual int minimumPBSZ() const;
    // smallest PBSZ that lets us encode at least 1 byte of real data
};


// control-channel security mechanism; knows about ADATs
// (it is an error to call SecureEndpoint functions until the
// ADAT exchange is complete)
class ControlSecurity : public SecureEndpoint {
public:
  // ADAT exchanges
  virtual bool hasOutgoingAdat() const;
    // return true if we have data to send
    // default: returns false

  virtual void getNextOutgoingAdat(DataBlock &block);
    // set 'block' to the next block of data to send
    // default: fails xassertion

  virtual bool expectingIncomingAdat() const;
    // return true if we still need more data
    // default: returns false

  virtual void incomingAdat(DataBlock &block);
    // process the next block of data
    // default: fails xassertion
};


// SM: SecurityProvider has been moved to provider.h, to
// separate code that only knows about interfaces (security.cc)
// from code that knows about all implementations (provider.cc).


/*
 * DataSecurityLevel vs RFC 2228 PROT levels
 * -----------------------------------------
 *
 * This basic difference is that RFC 2228 defines four overlapping
 * categories of protection (overlapping because it allows, say,
 * integrity-only mode to actually do encryption too), while
 * DataSecurityLevel defines some number (currently four but we allow
 * for expansion) of precise, non-overlapping protection levels.
 *
 * The distinction is important because both peers in the protocol
 * conversation must agree exactly about what they're doing.  So if
 * one peer is given DSL_INTEGRITY, that specifies a precise protocol,
 * and when the other peer is given the same level, they can talk.  If
 * room is left for under-the-covers "upgrades" of protection level,
 * it leaves the chance the two sides will not coordinate properly.
 *
 * Among other things, this means that DSL_INTEGRITY is not allowed to
 * spend time encrypting, so callers can rely on the fact that its
 * *performance* is superior to DSL_PRIVATE, when both are supported.
 * This acknowledgement of multiple dimensions of tradeoff (rather
 * than just focusing on data protection level) is missing in RFC
 * 2228's interpretations.
 *
 * Now, we still use the PROT mechanism to communicate the levels, but
 * we let each DataSecurity implementation decide how to map levels
 * into character codes -- essentially, we abandon RFC 2228's
 * interpretations of the codes.  (Though we try to use the same letter
 * for roughly the same meaning.)
 *
 */

#endif // __SECURITY_H