Open-Transactions  0.93.0-ge03d287
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Token.hpp
Go to the documentation of this file.
1 /************************************************************
2  *
3  * Token.hpp
4  *
5  */
6 
7 /************************************************************
8  -----BEGIN PGP SIGNED MESSAGE-----
9  Hash: SHA1
10 
11  * OPEN TRANSACTIONS
12  *
13  * Financial Cryptography and Digital Cash
14  * Library, Protocol, API, Server, CLI, GUI
15  *
16  * -- Anonymous Numbered Accounts.
17  * -- Untraceable Digital Cash.
18  * -- Triple-Signed Receipts.
19  * -- Cheques, Vouchers, Transfers, Inboxes.
20  * -- Basket Currencies, Markets, Payment Plans.
21  * -- Signed, XML, Ricardian-style Contracts.
22  * -- Scripted smart contracts.
23  *
24  * Copyright (C) 2010-2013 by "Fellow Traveler" (A pseudonym)
25  *
26  * EMAIL:
28  *
29  * BITCOIN: 1NtTPVVjDsUfDWybS4BwvHpG2pdS9RnYyQ
30  *
31  * KEY FINGERPRINT (PGP Key in license file):
32  * 9DD5 90EB 9292 4B48 0484 7910 0308 00ED F951 BB8E
33  *
34  * OFFICIAL PROJECT WIKI(s):
35  * https://github.com/FellowTraveler/Moneychanger
36  * https://github.com/FellowTraveler/Open-Transactions/wiki
37  *
38  * WEBSITE:
39  * http://www.OpenTransactions.org/
40  *
41  * Components and licensing:
42  * -- Moneychanger..A Java client GUI.....LICENSE:.....GPLv3
43  * -- otlib.........A class library.......LICENSE:...LAGPLv3
44  * -- otapi.........A client API..........LICENSE:...LAGPLv3
45  * -- opentxs/ot....Command-line client...LICENSE:...LAGPLv3
46  * -- otserver......Server Application....LICENSE:....AGPLv3
47  * Github.com/FellowTraveler/Open-Transactions/wiki/Components
48  *
49  * All of the above OT components were designed and written by
50  * Fellow Traveler, with the exception of Moneychanger, which
51  * was contracted out to Vicky C ([email protected]).
52  * The open-source community has since actively contributed.
53  *
54  * -----------------------------------------------------
55  *
56  * LICENSE:
57  * This program is free software: you can redistribute it
58  * and/or modify it under the terms of the GNU Affero
59  * General Public License as published by the Free Software
60  * Foundation, either version 3 of the License, or (at your
61  * option) any later version.
62  *
63  * ADDITIONAL PERMISSION under the GNU Affero GPL version 3
64  * section 7: (This paragraph applies only to the LAGPLv3
65  * components listed above.) If you modify this Program, or
66  * any covered work, by linking or combining it with other
67  * code, such other code is not for that reason alone subject
68  * to any of the requirements of the GNU Affero GPL version 3.
69  * (==> This means if you are only using the OT API, then you
70  * don't have to open-source your code--only your changes to
71  * Open-Transactions itself must be open source. Similar to
72  * LGPLv3, except it applies to software-as-a-service, not
73  * just to distributing binaries.)
74  *
75  * Extra WAIVER for OpenSSL, Lucre, and all other libraries
76  * used by Open Transactions: This program is released under
77  * the AGPL with the additional exemption that compiling,
78  * linking, and/or using OpenSSL is allowed. The same is true
79  * for any other open source libraries included in this
80  * project: complete waiver from the AGPL is hereby granted to
81  * compile, link, and/or use them with Open-Transactions,
82  * according to their own terms, as long as the rest of the
83  * Open-Transactions terms remain respected, with regard to
84  * the Open-Transactions code itself.
85  *
86  * Lucre License:
87  * This code is also "dual-license", meaning that Ben Lau-
88  * rie's license must also be included and respected, since
89  * the code for Lucre is also included with Open Transactions.
90  * See Open-Transactions/src/otlib/lucre/LUCRE_LICENSE.txt
91  * The Laurie requirements are light, but if there is any
92  * problem with his license, simply remove the Lucre code.
93  * Although there are no other blind token algorithms in Open
94  * Transactions (yet. credlib is coming), the other functions
95  * will continue to operate.
96  * See Lucre on Github: https://github.com/benlaurie/lucre
97  * -----------------------------------------------------
98  * You should have received a copy of the GNU Affero General
99  * Public License along with this program. If not, see:
100  * http://www.gnu.org/licenses/
101  *
102  * If you would like to use this software outside of the free
103  * software license, please contact FellowTraveler.
104  * (Unfortunately many will run anonymously and untraceably,
105  * so who could really stop them?)
106  *
107  * DISCLAIMER:
108  * This program is distributed in the hope that it will be
109  * useful, but WITHOUT ANY WARRANTY; without even the implied
110  * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
111  * PURPOSE. See the GNU Affero General Public License for
112  * more details.
113 
114  -----BEGIN PGP SIGNATURE-----
115  Version: GnuPG v1.4.9 (Darwin)
116 
117  iQIcBAEBAgAGBQJRSsfJAAoJEAMIAO35UbuOQT8P/RJbka8etf7wbxdHQNAY+2cC
118  vDf8J3X8VI+pwMqv6wgTVy17venMZJa4I4ikXD/MRyWV1XbTG0mBXk/7AZk7Rexk
119  KTvL/U1kWiez6+8XXLye+k2JNM6v7eej8xMrqEcO0ZArh/DsLoIn1y8p8qjBI7+m
120  aE7lhstDiD0z8mwRRLKFLN2IH5rAFaZZUvj5ERJaoYUKdn4c+RcQVei2YOl4T0FU
121  LWND3YLoH8naqJXkaOKEN4UfJINCwxhe5Ke9wyfLWLUO7NamRkWD2T7CJ0xocnD1
122  sjAzlVGNgaFDRflfIF4QhBx1Ddl6wwhJfw+d08bjqblSq8aXDkmFA7HeunSFKkdn
123  oIEOEgyj+veuOMRJC5pnBJ9vV+7qRdDKQWaCKotynt4sWJDGQ9kWGWm74SsNaduN
124  TPMyr9kNmGsfR69Q2Zq/FLcLX/j8ESxU+HYUB4vaARw2xEOu2xwDDv6jt0j3Vqsg
125  x7rWv4S/Eh18FDNDkVRChiNoOIilLYLL6c38uMf1pnItBuxP3uhgY6COm59kVaRh
126  nyGTYCDYD2TK+fI9o89F1297uDCwEJ62U0Q7iTDp5QuXCoxkPfv8/kX6lS6T3y9G
127  M9mqIoLbIQ1EDntFv7/t6fUTS2+46uCrdZWbQ5RjYXdrzjij02nDmJAm2BngnZvd
128  kamH0Y/n11lCvo1oQxM+
129  =uSzz
130  -----END PGP SIGNATURE-----
131  **************************************************************/
132 
133 #ifndef OPENTXS_CASH_TOKEN_HPP
134 #define OPENTXS_CASH_TOKEN_HPP
135 
138 
139 namespace opentxs
140 {
141 
142 class OTIdentifier;
143 class Mint;
144 class OTNym_or_SymmetricKey;
145 class OTPseudonym;
146 class Purse;
147 class OTString;
148 
149 typedef std::map<int32_t, OTASCIIArmor*> mapOfPrototokens;
150 
151 /*
152  Here's a rough sketch of the protocol:
153 
154  Client requests Mint for withdrawal of 100 ithica work hours.
155 
156 1) Client blinds and sends N tokens to the server, each worth 100 hours. Client
157 retains the keys.
158 2) Server responds with a single index, the one the server has chosen for
159 signing.
160 3) Client replies with 99 keys.
161 4) Server unblinds 99 tokens (or some randomly-chosen % of those) and verifies
162 them.
163  He signs the last one and returns it.
164 5) Client receives signed token, unblinds it, stores it for later.
165 6) When token is redeemed, it has already been unblinded. So Server simply
166 verifies it.
167 
168  LAST NAGGING QUESTION: Should the server sign the other 99 tokens before
169 unblinding them and verifying?
170  In fact, what is it verifying at all?? Certainly not the
171 amount, which is not even in
172  the Lucre token. If all it does is verify its signature,
173 then why sign it just to
174  verify it? Why exactly am I sending 99 tokens? What is
175 the server unblinding them
176  to look for?? Just to make sure all the IDs are random?
177 That they aren't spent
178  already?
179  I think that's it. The client has assurance he chose
180 his own random IDs, the server
181  verifies they are random and not spent already, and the
182 ID portion is the only part
183  that has to be randomized.
184 
185  UPDATE:
186  Ben Laurie has confirmed that the Chaumian 99 token requirement does not exist
187 with Lucre. All I have to
188  do is send a single blinded token. The server signs it and sends it back, and
189 the client unblinds it. Only the
190  ID itself is blinded -- the server can clearly see the amount and only the Mint
191 key for that denomination will work.
192  */
193 
194 // This class implements the Lucre coins.
195 //
196 class Token : public OTInstrument
197 {
198 private: // Private prevents erroneous use by other classes.
199  typedef OTInstrument ot_super;
200 
201 public:
202  enum tokenState {
209  };
210  // Wallet must submit at least N prototokens per withdrawal request, for the
211  // server to notarize it.
212  // One server might require at least 5 prototokens per withdrawal. Another
213  // might require 100 because it
214  // needs more security. Another 1000. These provide more security but they
215  // also cost more in terms of
216  // resources to process all those prototokens.
217 
218  EXPORT static int32_t GetMinimumPrototokenCount();
219 
220 protected:
221  bool m_bPasswordProtected; // this token might be encrypted to a passphrase,
222  // instead of a Nym.
223 
224  OTASCIIArmor m_ascSpendable; // This is the final, signed, unblinded token
225  // ID, ready to be spent.
226  // (But still in envelope form, encrypted and ascii-armored.)
227  OTASCIIArmor m_Signature; // This is the Mint's signature on the blinded
228  // prototoken.
229 
230  int64_t m_lDenomination; // The actual value of the token is between issuer
231  // and trader.
232  // The token must have a denomination so we know which Mint Key to verify it
233  // with.
234 
235  // --------------- Prototoken stuff below here.....
236 
237  mapOfPrototokens m_mapPublic; // in protoToken state, this object stores N
238  // prototokens in order to fulfill the
239  // protocol
240  mapOfPrototokens m_mapPrivate; // The elements are accessed [0..N].
241  // mapPublic[2] corresponds to
242  // map_Private[2], etc.
243 
244  int32_t m_nTokenCount; // Official token count is stored here for
245  // serialization, etc. The maps' size should match.
246  int32_t m_nChosenIndex; // When the client submits N prototokens, the server
247  // randomly chooses one to sign.
248  // (The server opens the other (N-1) prototokens to verify the amount is
249  // correct and
250  // that the IDs are random enough.)
251  // Expiration dates are necessary because otherwise the spent token database
252  // must be stored
253  // forever. This may be useful in some applications, but in most, a 1-year
254  // or 1-month expiration
255  // date will be perfectly fine, especially with auto-exchanges performed by
256  // the wallet. Suddenly
257  // it becomes much more feasible a proposition to effectively run a token
258  // server, without having
259  // to hold those spent tokens forever.
260  //
261  // EXPIRATION DATES are in the parent:
262  //
263  // time64_t m_VALID_FROM; // (In the parent)
264  // time64_t m_VALID_TO; // (In the parent)
265  //
266  // Tokens (and Mints) also have a SERIES:
267  //
268  int32_t m_nSeries;
270  bool m_bSavePrivateKeys; // Determines whether it serializes private keys 1
271  // time (yes if true)
272  virtual int32_t ProcessXMLNode(irr::io::IrrXMLReader*& xml);
273  void InitToken();
274  bool ChooseIndex(int32_t nIndex);
275  EXPORT Token();
276  EXPORT Token& operator=(const Token& rhs);
277  EXPORT Token(const OTIdentifier& SERVER_ID, const OTIdentifier& ASSET_ID);
278  EXPORT Token(const Purse& thePurse);
279 
280 public:
281  // Preparing to polymorphize tokens. This will allow us to instantiate
282  // LucreTokens,
283  // and other types of tokens, dynamically, without having to know beforehand
284  // which
285  // OTToken subclass we're dealing with.
286  //
287  EXPORT static Token* TokenFactory(OTString strInput);
288  EXPORT static Token* TokenFactory(OTString strInput, const Purse& thePurse);
289  EXPORT static Token* TokenFactory(OTString strInput,
290  const OTIdentifier& SERVER_ID,
291  const OTIdentifier& ASSET_ID);
292  EXPORT static Token* LowLevelInstantiate(const Purse& thePurse);
293  EXPORT static Token* LowLevelInstantiate(const OTString& strFirstLine);
294  EXPORT static Token* LowLevelInstantiate(const OTString& strFirstLine,
295  const Purse& thePurse);
296  EXPORT static Token* LowLevelInstantiate(const OTString& strFirstLine,
297  const OTIdentifier& SERVER_ID,
298  const OTIdentifier& ASSET_ID);
299  EXPORT virtual ~Token();
300 
301  EXPORT void Release_Token();
302  virtual void Release();
303  EXPORT void ReleasePrototokens();
304 
305  virtual void UpdateContents(); // Before transmission or serialization, this
306  // is where the token saves its contents
307  // Will save the private keys on next serialization (not just public keys)
308  // (SignContract sets m_bSavePrivateKeys back to false again.)
309  inline void SetSavePrivateKeys()
310  {
311  m_bSavePrivateKeys = true;
312  }
313 
314  // When you send a token to the server, you must decrypt it from your own
315  // key,
316  // and re-encrypt it to the server key, before sending. Use this function to
317  // do so.
318  // In the case of exporting a token from a purse, you could create a dummy
319  // Nym, embed
320  // it inside the purse, and then reassign ownership of each token to that
321  // token as you
322  // push them into that purse.
323  // From there, you can hand someone the purse, and password-protect it, if
324  // you like.
325  //
326  EXPORT bool ReassignOwnership(OTNym_or_SymmetricKey& oldOwner,
327  OTNym_or_SymmetricKey& newOwner);
328 
329  inline const OTASCIIArmor& GetSpendable() const
330  {
331  return m_ascSpendable;
332  }
333  inline void SetSpendable(const OTASCIIArmor& theArmor)
334  {
335  m_ascSpendable.Set(theArmor);
336  }
337 
338  EXPORT bool GetSpendableString(OTNym_or_SymmetricKey theOwner,
339  OTString& theString) const; // todo
340  // potentially
341  // return
342  // OTPassword
343  // here instead
344  // of OTString
345  // (more secure.)
346 
348  {
349  return m_State;
350  }
351 
352  // Lucre step 1 (in OTMint) Generate New Mint
353 
354  // Lucre Step 2: Generate Coin Request
355  // nDenomination MUST be one that the Mint supports.
356  // let nTokenCount default to 1, since that's how Lucre works.
357 protected:
358  EXPORT virtual bool GenerateTokenRequest(
359  const OTPseudonym& theNym, Mint& theMint, int64_t lDenomination,
360  int32_t nTokenCount = Token::GetMinimumPrototokenCount()) = 0;
361 
362 public:
364  const Purse& thePurse, const OTPseudonym& theNym, Mint& theMint,
365  int64_t lDenomination,
366  int32_t nTokenCount = Token::GetMinimumPrototokenCount());
367  // Lucre Step 3: Mint signs token (in OTMint)
368  inline int32_t GetSeries() const
369  {
370  return m_nSeries;
371  }
372  inline void SetSeriesAndExpiration // (Called by the mint when signing.)
373  (int32_t nSeries, time64_t VALID_FROM, time64_t VALID_TO)
374  {
375  m_nSeries = nSeries;
376  m_VALID_FROM = VALID_FROM;
377  m_VALID_TO = VALID_TO;
378  }
379 
380  // Lucre step 4: client unblinds token -- now it's ready for use.
381  EXPORT virtual bool ProcessToken(const OTPseudonym& theNym, Mint& theMint,
382  Token& theRequest) = 0;
383 
384  // Lucre step 5: token verifies when it is redeemed by merchant.
385  // Now including spent token database!
386  EXPORT bool VerifyToken(OTPseudonym& theNotary, Mint& theMint);
387  EXPORT bool IsTokenAlreadySpent(OTString& theCleartextToken); // Spent Token
388  // Database
389  EXPORT bool RecordTokenAsSpent(OTString& theCleartextToken); // Spent Token
390  // Database
391  EXPORT void SetSignature(const OTASCIIArmor& theSignature,
392  int32_t nTokenIndex);
393  EXPORT bool GetSignature(OTASCIIArmor& theSignature) const;
394  // The actual denomination of the token is determined by whether or not it
395  // verifies
396  // when the server uses the private verify info for THAT denomination. So if
397  // you set
398  // the denomination here wrong, all that does is cause the server to try to
399  // verify it
400  // with the wrong key. If the proto-token was generated for a different
401  // denomination,
402  // then it cannot verify.
403  // So this value is only here to help you make sure to ask the Mint to use
404  // the right
405  // key when verifying the token. And this only works because we have a
406  // specific set of
407  // denominations for each digital asset, each with its own key pair in the
408  // Mint.
409  inline int64_t GetDenomination() const
410  {
411  return m_lDenomination;
412  }
413  inline void SetDenomination(int64_t lVal)
414  {
415  m_lDenomination = lVal;
416  }
417 
418  // These are not actually necessary for Lucre itself, which only needs
419  // to send a single blinded proto-token. Index is always 0, and Count is
420  // always 1. But this does mean OTToken supports digital cash schemes that
421  // involve multiple prototokens -- even though Lucre is not one of those.
422  EXPORT bool GetPrototoken(OTASCIIArmor& ascPrototoken, int32_t nTokenIndex);
423  EXPORT bool GetPrivatePrototoken(OTASCIIArmor& ascPrototoken,
424  int32_t nTokenIndex);
425 
426  virtual bool SaveContractWallet(std::ofstream& ofs) const;
427 };
428 
429 } // namespace opentxs
430 
431 #endif // OPENTXS_CASH_TOKEN_HPP
int32_t m_nChosenIndex
Definition: Token.hpp:246
static EXPORT int32_t GetMinimumPrototokenCount()
Definition: Token.cpp:180
EXPORT bool GetPrototoken(OTASCIIArmor &ascPrototoken, int32_t nTokenIndex)
Definition: Token.cpp:1039
EXPORT void ReleasePrototokens()
Definition: Token.cpp:310
virtual int32_t ProcessXMLNode(irr::io::IrrXMLReader *&xml)
Definition: Token.cpp:871
OTASCIIArmor m_Signature
Definition: Token.hpp:227
Token::tokenState GetState() const
Definition: Token.hpp:347
int32_t m_nSeries
Definition: Token.hpp:268
EXPORT bool GetSignature(OTASCIIArmor &theSignature) const
Definition: Token.cpp:1148
int32_t GetSeries() const
Definition: Token.hpp:368
virtual bool SaveContractWallet(std::ofstream &ofs) const
Definition: Token.cpp:339
static EXPORT Token * LowLevelInstantiate(const Purse &thePurse)
Definition: Token.cpp:418
EXPORT bool GetSpendableString(OTNym_or_SymmetricKey theOwner, OTString &theString) const
Definition: Token.cpp:751
int64_t time64_t
Definition: Common.hpp:209
EXPORT Token()
Definition: Token.cpp:219
bool m_bSavePrivateKeys
Definition: Token.hpp:270
const OTASCIIArmor & GetSpendable() const
Definition: Token.hpp:329
EXPORT bool GetPrivatePrototoken(OTASCIIArmor &ascPrototoken, int32_t nTokenIndex)
Definition: Token.cpp:1062
void SetDenomination(int64_t lVal)
Definition: Token.hpp:413
EXPORT bool VerifyToken(OTPseudonym &theNotary, Mint &theMint)
Definition: Token.cpp:1162
virtual void UpdateContents()
Definition: Token.cpp:771
static EXPORT Token * InstantiateAndGenerateTokenRequest(const Purse &thePurse, const OTPseudonym &theNym, Mint &theMint, int64_t lDenomination, int32_t nTokenCount=Token::GetMinimumPrototokenCount())
Definition: Token.cpp:1086
virtual EXPORT bool GenerateTokenRequest(const OTPseudonym &theNym, Mint &theMint, int64_t lDenomination, int32_t nTokenCount=Token::GetMinimumPrototokenCount())=0
EXPORT void Set(const char *data, uint32_t enforcedMaxLength=0)
Definition: OTString.cpp:1055
EXPORT void SetSignature(const OTASCIIArmor &theSignature, int32_t nTokenIndex)
Definition: Token.cpp:1119
virtual EXPORT bool ProcessToken(const OTPseudonym &theNym, Mint &theMint, Token &theRequest)=0
void SetSavePrivateKeys()
Definition: Token.hpp:309
int64_t GetDenomination() const
Definition: Token.hpp:409
virtual void Release()
Definition: Token.cpp:286
EXPORT bool IsTokenAlreadySpent(OTString &theCleartextToken)
Definition: Token.cpp:557
mapOfPrototokens m_mapPrivate
Definition: Token.hpp:240
EXPORT bool RecordTokenAsSpent(OTString &theCleartextToken)
Definition: Token.cpp:590
std::map< int32_t, OTASCIIArmor * > mapOfPrototokens
Definition: Token.hpp:147
void SetSeriesAndExpiration(int32_t nSeries, time64_t VALID_FROM, time64_t VALID_TO)
Definition: Token.hpp:373
bool m_bPasswordProtected
Definition: Token.hpp:221
void InitToken()
Definition: Token.cpp:207
OTASCIIArmor m_ascSpendable
Definition: Token.hpp:224
int32_t m_nTokenCount
Definition: Token.hpp:244
EXPORT bool ReassignOwnership(OTNym_or_SymmetricKey &oldOwner, OTNym_or_SymmetricKey &newOwner)
Definition: Token.cpp:716
mapOfPrototokens m_mapPublic
Definition: Token.hpp:237
EXPORT void Release_Token()
Definition: Token.cpp:275
void SetSpendable(const OTASCIIArmor &theArmor)
Definition: Token.hpp:333
EXPORT Token & operator=(const Token &rhs)
tokenState m_State
Definition: Token.hpp:269
static EXPORT Token * TokenFactory(OTString strInput)
Definition: Token.cpp:518
int64_t m_lDenomination
Definition: Token.hpp:230
virtual EXPORT ~Token()
Definition: Token.cpp:294
bool ChooseIndex(int32_t nIndex)
Definition: Token.cpp:1107