Digital Authentication Framework  6.0.1.37
DigitalAuthenticationFramework.h
Go to the documentation of this file.
1 /*
2  * (c) 2014 Good Technology Corporation. All rights reserved.
3  */
4 
10 #ifndef DIGITALAUTHENTICATIONFRAMEWORK_H
11 #define DIGITALAUTHENTICATIONFRAMEWORK_H
12 
13 #include <string>
14 #include <cstring>
15 #include <vector>
16 #include <stdint.h>
17 
20 extern "C" const char *DAF_SDK_VERSION_string;
21 
28 typedef std::vector<uint8_t> DAData;
29 
37 typedef std::vector<uint8_t> DAMechanism;
38 
39 // forward declarations
40 class DADriver;
41 class DAError;
42 class DADevice;
43 class DAMetaData;
44 class DASession;
45 class DAKey;
46 class DAMessage;
47 
51 class DADriver
52 {
53 public:
59  static void initialize();
60 
69  static DADevice *getDevice();
70 
75  static DAError &getLastError();
76 };
77 
81 class DAError
82 {
83 public:
84  enum {
85  SUCCESS = 0,
86  NO_MEMORY = 1,
87  NOT_PROVISIONED = 2,
88  DEVICE_NOT_FOUND = 3,
89  NO_MORE_SESSIONS = 4,
90  DEVICE_DISCONNECTED = 5,
91  DEVICE_PROTOCOL_ERR = 6,
92  BAD_AUTH_TOKEN = 7,
93  KEY_NOT_FOUND = 8,
94  ATTRIB_NOT_FOUND = 9,
95  MECH_NOT_FOUND = 10,
96  VERIFY_FAILED = 11,
97  NOT_IMPLEMENTED = 12,
98  BAD_PARAMETERS = 13,
99  OS_ERROR = 14,
100  UNSUPPORTED_HASH = 15,
101  };
102  // ... and so on. Derived classes will doubtless need their own.
103 
107  virtual ~DAError() {};
108 
113  virtual int getCode() =0;
114 
118  bool isError() { return getCode() != SUCCESS; };
119 
123  virtual void clear() =0;
124 
130  virtual void getAsStringUTF8(std::string &errmsg) =0;
131 };
132 
133 #if !(DOXYGEN)
134 #define ALL_ERRORS(F) \
135  F(DAError::SUCCESS, "Success") \
136  F(DAError::NO_MEMORY, "General memory allocation failure") \
137  F(DAError::NOT_PROVISIONED, "Driver has not been set up with a device") \
138  F(DAError::DEVICE_NOT_FOUND, "Cannot find the device") \
139  F(DAError::NO_MORE_SESSIONS, "The maximum allowed number of concurrent sessions are already connected") \
140  F(DAError::DEVICE_DISCONNECTED, "Link to device lost unexpectedly") \
141  F(DAError::DEVICE_PROTOCOL_ERR, "Error from protocol stack talking to device") \
142  F(DAError::BAD_AUTH_TOKEN, "authToken provided to CreateSession was bad") \
143  F(DAError::KEY_NOT_FOUND, "Requested key does not exist") \
144  F(DAError::ATTRIB_NOT_FOUND, "Requested attribute not available") \
145  F(DAError::MECH_NOT_FOUND, "Requested mechanism is not supported") \
146  F(DAError::VERIFY_FAILED, "Invalid signature or ciphertext") \
147  F(DAError::NOT_IMPLEMENTED, "Function or method is not implemented") \
148  F(DAError::BAD_PARAMETERS, "Missing or invalid parameters to method") \
149  F(DAError::OS_ERROR, "Operating system call failed") \
150  F(DAError::UNSUPPORTED_HASH, "Requested hash function cannot be used here")
151 #endif
152 
159 class DADevice
160 {
161 public:
165  virtual ~DADevice() {};
166 
173  virtual DAMetaData &getInfo () =0;
174 
183  virtual DASession *createSession (DAData &authToken) =0;
184 
188  virtual DAError &getLastError() =0;
189 };
190 
197 {
198 public:
202  virtual ~DASession() {};
203 
206  virtual DADevice &getDevice () =0;
207 
214  virtual DAMetaData &getInfo () =0;
215 
223  virtual bool isConnected() =0;
224 
229  virtual int getKeyCount() =0;
230 
239  virtual DAKey *getKey(int index) =0;
240 
248  virtual DAKey *getKey(const std::string &serial) =0;
249 
253  virtual DAError &getLastError() =0;
254 };
255 
260 class DAKey
261 {
262 public:
266  virtual ~DAKey() {};
267 
271  virtual DAMetaData &getInfo()=0;
272 
276  virtual bool encrypt(DAMessage &msg)=0;
277 
281  virtual bool decrypt(DAMessage &msg)=0;
282 
286  virtual bool sign(DAMessage &msg)=0;
287 
291  virtual bool verify(DAMessage &msg)=0;
292 
300  virtual bool getData(DAData &data)=0;
301 
313  virtual bool setData(const DAData &data)=0;
314 
325  virtual bool generateMaterial()=0;
326 
329  virtual std::vector<DAMechanism> getMechanisms() =0;
330 
331  static const int STORAGE_MESSAGE_SIZE = 32;
335  static const int ENCRYPT_MESSAGE_SIZE = 32;
339  static const int ONEWAY_MESSAGE_SIZE = 32;
342 };
343 
350 typedef enum
351 {
353 
359 
361 }
362  DADigestType;
363 
370 {
371 public:
376  : m_plaintext()
377  , m_ciphertext()
378  , m_iv()
379  , m_mech()
380  , m_flags(0)
381  , m_digestType(DA_DIGEST_NONE)
382  {}
383 
384  /* Default destructor, copy constructor and assignment operator
385  * is OK. */
386 
396  bool getMechanism(DAMechanism &mech) const
397  {
398  if (m_flags & HAVE_MECH)
399  {
400  mech = m_mech;
401  return true;
402  } else {
403  return false;
404  }
405  }
406 
409  bool getIV(DAData &iv) const
410  {
411  if (m_flags & HAVE_IV)
412  {
413  iv = m_iv;
414  return true;
415  } else {
416  return false;
417  }
418  }
419 
422  bool getPlaintext(DAData &data) const
423  {
424  if (m_flags & HAVE_PLAINTEXT)
425  {
426  data = m_plaintext;
427  return true;
428  } else {
429  return false;
430  }
431  }
432 
435  bool getCiphertext(DAData &data) const
436  {
437  if (m_flags & HAVE_CIPHERTEXT)
438  {
439  data = m_ciphertext;
440  return true;
441  } else {
442  return false;
443  }
444  }
445 
450  {
451  return m_digestType;
452  }
453 
456  void setMechanism(const DAMechanism &mech)
457  {
458  m_mech = mech;
459  m_flags |= HAVE_MECH;
460  }
461 
470  bool setMechanismForRSAPkcs1Signature();
471 
480  bool setMechanismForDSA();
481 
490  bool setMechanismForECDSA();
491 
494  void setIV(const DAData &iv)
495  {
496  m_iv = iv;
497  m_flags |= HAVE_IV;
498  }
499 
502  void setPlaintext(const DAData &data)
503  {
504  m_plaintext = data;
505  m_flags |= HAVE_PLAINTEXT;
506  }
507 
510  void setCiphertext(const DAData &data)
511  {
512  m_ciphertext = data;
513  m_flags |= HAVE_CIPHERTEXT;
514  }
515 
519  {
520  m_digestType = dtype;
521  }
522 
525  {
526  m_mech = DAMechanism();
527  m_flags &= ~HAVE_MECH;
528  }
529 
531  void unsetIV()
532  {
533  m_iv = DAData();
534  m_flags &= ~HAVE_IV;
535  }
536 
539  {
540  m_plaintext = DAData();
541  m_flags &= ~HAVE_PLAINTEXT;
542  }
543 
546  {
547  m_ciphertext = DAData();
548  m_flags &= ~HAVE_CIPHERTEXT;
549  }
550 
553  {
554  setDigestType(DA_DIGEST_NONE);
555  }
556 
576  bool applyDefaultDigest();
577 
587  bool getPkcs1SignatureData( DAData &msg );
588 
595  static DADigestType getDigestFromMech( const DAMechanism &mech );
596 
597 protected:
602  unsigned m_flags;
604 
605  enum {
606  HAVE_PLAINTEXT = 1,
607  HAVE_CIPHERTEXT = 2,
608  HAVE_IV = 4,
609  HAVE_MECH = 8
610  };
611 };
612 
620 typedef enum
621 {
622  DA_NAME = 0,
623  DA_SERIAL = 2,
624 
625  DA_HARDWARE = 1000,
629 
630  DA_SMIME_SIGN = 1100,
634  DA_READ_WRITE = 1104,
635  DA_STORAGE = 1105,
636  DA_SYMM_CRYPT = 1106,
637  DA_SYMM_SIGN = 1107,
638 
639  DA_CERTIFICATE = 2100,
640 
643 } DAAttrib;
644 
653 {
654 public:
658  virtual ~DAMetaData() {};
659 
668  virtual bool getString(DAAttrib which, std::string &data) =0;
669 
681  virtual bool getFlag(DAAttrib which) =0;
682 
695  virtual bool getData(DAAttrib which, DAData &data, size_t index=0) =0;
696 
709  virtual bool getSize(DAAttrib which, size_t &len_r) =0;
710 
711 };
712 
716 class DAUtils
717 {
718 public:
723  static DAData mkData(const void *data, size_t len)
724  {
725  DAData ret;
726  const uint8_t *ptr = static_cast<const uint8_t *>(data);
727  while (len-- > 0)
728  ret.push_back(*ptr++);
729  return ret;
730  }
731 
736  static DAData mkData(std::string &str)
737  {
738  return mkData(str.data(), str.size());
739  }
740 
745  static DAData mkData(const char *str)
746  {
747  return mkData(str, strlen(str));
748  }
749 
750 };
751 
752 #endif
DAData m_plaintext
Plaintext bytes.
Definition: DigitalAuthenticationFramework.h:598
void unsetPlaintext()
Remove plaintext.
Definition: DigitalAuthenticationFramework.h:538
Encapsulates a message and various (optional) crypto parameters.
Definition: DigitalAuthenticationFramework.h:369
bool getPlaintext(DAData &data) const
Get the original plaintext/signed message.
Definition: DigitalAuthenticationFramework.h:422
(flag) True if both sign() and verify() work
Definition: DigitalAuthenticationFramework.h:637
unsigned m_flags
Flags (HAVE_PLAINTEXT etc)
Definition: DigitalAuthenticationFramework.h:602
Interface to "session" object.
Definition: DigitalAuthenticationFramework.h:196
DAMechanism m_mech
Mechanism (OID)
Definition: DigitalAuthenticationFramework.h:601
DAData m_ciphertext
Ciphertext bytes.
Definition: DigitalAuthenticationFramework.h:599
(data) X.509 certificate for key
Definition: DigitalAuthenticationFramework.h:639
36-byte MD5+SHA1 dual hash, used by SSL3 and TLS 1.0-1.1
Definition: DigitalAuthenticationFramework.h:360
(flag) True if key can be used for user authentication
Definition: DigitalAuthenticationFramework.h:632
void setIV(const DAData &iv)
Set IV.
Definition: DigitalAuthenticationFramework.h:494
void setDigestType(DADigestType dtype)
Set digest type.
Definition: DigitalAuthenticationFramework.h:518
virtual ~DASession()
virtual destructor
Definition: DigitalAuthenticationFramework.h:202
bool getCiphertext(DAData &data) const
Get the final encrypted message or signature.
Definition: DigitalAuthenticationFramework.h:435
(size) Max size of a decrypted plaintext (in bytes)
Definition: DigitalAuthenticationFramework.h:642
virtual ~DAKey()
virtual destructor
Definition: DigitalAuthenticationFramework.h:266
(string) User-visible name of device or key
Definition: DigitalAuthenticationFramework.h:622
DADigestType getDigestType() const
Gets digest (hash) type used for signature.
Definition: DigitalAuthenticationFramework.h:449
static DAData mkData(std::string &str)
Create a DAData from a std::string.
Definition: DigitalAuthenticationFramework.h:736
static void initialize()
Initialization function.
General metadata interface.
Definition: DigitalAuthenticationFramework.h:652
DAAttrib
Attribute selector.
Definition: DigitalAuthenticationFramework.h:620
void unsetDigestType()
Unset digestType.
Definition: DigitalAuthenticationFramework.h:552
void setMechanism(const DAMechanism &mech)
Set Crypto Algorithm.
Definition: DigitalAuthenticationFramework.h:456
(flag) True if SetData() and/or GenerateMaterial() work
Definition: DigitalAuthenticationFramework.h:634
std::vector< uint8_t > DAMechanism
Identifier of a cryptographic mechanism.
Definition: DigitalAuthenticationFramework.h:37
SHA-512 hash (64 bytes)
Definition: DigitalAuthenticationFramework.h:358
Message has not been hashed.
Definition: DigitalAuthenticationFramework.h:352
(flag) True if authentication token is regular password
Definition: DigitalAuthenticationFramework.h:628
void unsetMechanism()
Remove Crypto Algorithm.
Definition: DigitalAuthenticationFramework.h:524
static DAData mkData(const char *str)
Create a DAData from a C string.
Definition: DigitalAuthenticationFramework.h:745
void unsetIV()
Remove IV.
Definition: DigitalAuthenticationFramework.h:531
Interface for error reporting.
Definition: DigitalAuthenticationFramework.h:81
virtual ~DADevice()
virtual destructor
Definition: DigitalAuthenticationFramework.h:165
SHA-1 hash (20 bytes)
Definition: DigitalAuthenticationFramework.h:354
Utility functions.
Definition: DigitalAuthenticationFramework.h:716
DAMessage()
Constructor Creates an empty message with all zero-length entries.
Definition: DigitalAuthenticationFramework.h:375
DAData m_iv
IV bytes.
Definition: DigitalAuthenticationFramework.h:600
SHA-256 hash (32 bytes)
Definition: DigitalAuthenticationFramework.h:356
bool getMechanism(DAMechanism &mech) const
Return cryptographic mechanism identifier.
Definition: DigitalAuthenticationFramework.h:396
(flag) True if key can be used for SSL/TLS client auth
Definition: DigitalAuthenticationFramework.h:633
SHA-384 hash (48 bytes)
Definition: DigitalAuthenticationFramework.h:357
(flag) True if key can be used for S/MIME decryption
Definition: DigitalAuthenticationFramework.h:631
(size) Size of signature in bytes
Definition: DigitalAuthenticationFramework.h:641
virtual ~DAError()
virtual destructor
Definition: DigitalAuthenticationFramework.h:107
bool getIV(DAData &iv) const
Return IV.
Definition: DigitalAuthenticationFramework.h:409
(flag) True if GetData() and SetData() work
Definition: DigitalAuthenticationFramework.h:635
std::vector< uint8_t > DAData
A data block represented as a sequence of bytes.
Definition: DigitalAuthenticationFramework.h:28
(flag) True if key can be used for S/MIME signing
Definition: DigitalAuthenticationFramework.h:630
Top-level functions provided by the device driver.
Definition: DigitalAuthenticationFramework.h:51
static DAData mkData(const void *data, size_t len)
Create a DAData from pointer and length.
Definition: DigitalAuthenticationFramework.h:723
(flag) True if path to device has eavesdropping protection
Definition: DigitalAuthenticationFramework.h:626
DADigestType m_digestType
Digest used for signed message.
Definition: DigitalAuthenticationFramework.h:603
static DADevice * getDevice()
Returns pointer to device object.
(flag) True if path to device is authenticated
Definition: DigitalAuthenticationFramework.h:627
void setPlaintext(const DAData &data)
Set plaintext buffer.
Definition: DigitalAuthenticationFramework.h:502
SHA-224 hash (28 bytes)
Definition: DigitalAuthenticationFramework.h:355
Interface to device object.
Definition: DigitalAuthenticationFramework.h:159
(flag) True if both encrypt() and decrypt() work
Definition: DigitalAuthenticationFramework.h:636
virtual ~DAMetaData()
Virtual Destructor.
Definition: DigitalAuthenticationFramework.h:658
(string) Unique serial number of device or key
Definition: DigitalAuthenticationFramework.h:623
void unsetCiphertext()
Remove ciphertext.
Definition: DigitalAuthenticationFramework.h:545
void setCiphertext(const DAData &data)
Set ciphertext buffer.
Definition: DigitalAuthenticationFramework.h:510
static DAError & getLastError()
Get current error status for device driver.
(flag) True if implemented in hardware
Definition: DigitalAuthenticationFramework.h:625
bool isError()
test if error has occurred
Definition: DigitalAuthenticationFramework.h:118
Interface to Key objects.
Definition: DigitalAuthenticationFramework.h:260
DADigestType
Identification of hash algorithm used for signature.
Definition: DigitalAuthenticationFramework.h:350
const char * DAF_SDK_VERSION_string
Identifies the version of the DAF SDK.
Definition: DigitalAuthenticationFramework.h:20