7b4a052793c9dfbfff094b3af5f4ea82d4a75efc
[gnuk/gnuk.git] / doc / NOTES
1 USB communication (current)
2 ===========================
3
4 * Get response, command chaining, short APDU only.
5
6
7 If it were only for token and no smartcard:
8
9 * Get response, command chaining and short APDU would be considered
10   useless.
11
12 * It would be wise to use extended APDU and CCID/ICCD block chaining.
13
14 The question would be: When lower layer (CCID/ICCD layer) support
15 enough mechanism of block assembly, why not use one in the application
16 layer (ISO 7816)?
17
18 For token implementation, CCID/ICCD would be lower layer and ISO 7816
19 would be higher layer, but it's different in fact.  The figure of
20 communication is like::
21
22     host <-----------> reader <---------> smartcard
23            CCID/ICCD           ISO 7816
24     
25     host <--> token
26
27 Given the situation host side (GnuPG) already has the features of
28 handling get response, command chaining, and short APDU only, it is
29 rather better to do that on token side too.
30
31 Besides, supporting extended APDU on host side, it would be needed to
32 prepare 64KB buffer (that's the maximum size), as there is no explicit
33 limitation for buffer size.  64KB would be large, and this could be
34 avoided when we use short APDU only.
35
36
37 USB communication (second attempt)
38 ==================================
39
40 * No get response, no command chaining, but extended APDU and extended
41   Lc and Le.  I think that this keep the code simple.
42
43 * The value of dwMaxCCIDMessageLength is 320, that's the size
44   of header of ICC block plus size of maximum APDU (by 64
45   granularity).  Still, some ccid implementation (ccid 1.3.11, for
46   example) sends ICC block using chaining unfortunately, so we keep
47   the code of ICC block chaining.
48
49
50 USB communication (initial attempt)
51 ===================================
52
53 * Once in the past (version <= 0.4), the value of
54   dwMaxCCIDMessageLength was 64 and we supported CCID/ICCD block chaining,
55   so that we could not handle multple Bulk transactions.
56
57
58 OpenPGP card protocol implementation
59 ====================================
60
61 I try to follow "no clear password(s)" policy, even if it is on
62 protected flash memory.  Further, keystrings for user and reset code
63 are removed after key imports.  Because of this, replacing keys are
64 not possible without password information.  (Thus, replacing existing
65 keys are not supported.)
66
67 Therefore, there is "no clear password" and "no keystrings" on flash
68 ROM when Gnuk is used by admin-less mode.  When it is used with admin,
69 the keystring of admin is on flash ROM.
70
71
72 How a private key is stored
73 ===========================
74
75 KEYPTR
76          ----> [   P   ][   Q   ][       N        ]
77                <---encrypted----><---  plain  ---->
78
79 key_addr                       4-byte
80 initial_vector (random)        16-byte
81 checksum_encrypted             16-byte
82 dek_encrypted_by_keystring_pw1 16-byte
83 dek_encrypted_by_keystring_rc  16-byte
84 dek_encrypted_by_keystring_pw3 16-byte
85
86 ... decrypted to
87
88 [   P   ][   Q   ]
89 checksum 16-byte