Post-quantum cryptography tool
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

534 lines

  1. .TH CCR 1 2017-10-23 "ccr" "Codecrypt"
  2. .SH NAME
  3. .B ccr
  4. \- The post-quantum cryptography encryption and signing tool
  6. .B ccr
  7. .RI [OPTION]...
  9. \fBccr\fR (short of Codecrypt) is a general purpose encryption/decryption
  10. signing/verification tool that uses only quantum-computer-resistant algorithms.
  11. .SS
  12. General options:
  13. .TP
  14. \fB\-h\fR, \fB\-\-help\fR
  15. Show a simple help with option listing.
  16. .TP
  17. \fB\-V\fR, \fB\-\-version\fR
  18. Display only version information.
  19. .TP
  20. \fB\-T\fR, \fB\-\-test\fR
  21. This option exists as a convenience for hackers - in this case, \fBccr\fR
  22. initializes itself, calls a test() function from source file src/main.cpp (that
  23. is meant to be filled by testing stuff beforehand) and terminates. In
  24. distribution packages, it will probably do nothing.
  25. .TP
  26. \fB\-R\fR, \fB\-\-in\fR <\fIfile\fR>
  27. Redirect standard input to be read from \fIfile\fR instead from stdin. You can
  28. still specify "-" to force reading from stdin.
  29. .TP
  30. \fB\-o\fR, \fB\-\-out\fR <\fIfile\fR>
  31. Redirect standard output to be written to \fIfile\fR. You can specify "-" to
  32. force writing to stdout.
  33. .TP
  34. \fB\-E\fR, \fB\-\-err\fR <\fIfile\fR>
  35. Redirect the standard error output to \fIfile\fR. You can specify "-" to force
  36. writing to stderr. Error output does not carry any data, but provides useful
  37. error messages and metadata about what is happening, e.g. the identity of
  38. message signer or details about why decryption or verification fails.
  39. .TP
  40. \fB\-a\fR, \fB\-\-armor\fR
  41. Where expecting input or output of data in Codecrypt communication format, use
  42. ascii-armoring.
  43. Codecrypt otherwise usually generates raw binary data, that are very hard to
  44. pass through e-mail or similar text communication channels.
  45. .TP
  46. \fB\-y\fR, \fB\-\-yes\fR
  47. Assume the user knows what he is doing, and answer "yes" to all questions.
  48. .SS
  49. Actions:
  50. .TP
  51. \fB\-s\fR, \fB\-\-sign\fR
  52. Produce a signed message from input.
  53. .TP
  54. \fB\-v\fR, \fB\-\-verify\fR
  55. Take a signed message from input, verify whether the signature is valid, and
  56. output message content if the verification succeeded.
  57. .TP
  58. \fB\-e\fR, \fB\-\-encrypt\fR
  59. Produce an encrypted message from input.
  60. .TP
  61. \fB\-d\fR, \fB\-\-decrypt\fR
  62. Decrypt the message from input.
  63. .P
  64. Note that the actions for signature/encryption and decryption/verification can
  65. be easily combined into one command, simply by specifying both options usually
  66. as "-se" or "-dv".
  67. .SS
  68. Action options:
  69. .TP
  70. \fB\-r\fR, \fB\-\-recipient\fR <\fIkeyspec\fR>
  71. Specify that the message for encryption should be encrypted so that only the
  72. owner of a private key paired with public key specified by \fIkeyspec\fR can
  73. decrypt it.
  74. .TP
  75. \fB\-u\fR, \fB\-\-user\fR <\fIkeyspec\fR>
  76. Specify a private key to use for signing the message. If this option is empty,
  77. it is defaulted from CCR_USER environment variable.
  78. .TP
  79. \fB\-C\fR, \fB\-\-cleartext\fR
  80. When working with signatures, produce/expect a cleartext signature. The basic
  81. property of cleartext signature is that the message it contains is easily
  82. readable by users, therefore it is a very popular method to e.g. sign e-mails.
  83. .TP
  84. \fB\-b\fR, \fB\-\-detach\-sign\fR <\fIfile\fR>
  85. On signing, produce a detached signature and save it to \fIfile\fR. When
  86. verifying, read the detached signature from \fIfile\fR. Note that files that is
  87. being signed or verified must be put into program's input (potentially using
  88. "-R" option.
  89. .TP
  90. \fB\-S\fR, \fB\-\-symmetric\fR <\fIfile\fR>
  91. Use symmetric cryptography.
  92. When doing "sign" or "verify" operation, do not sign asymmetrically, but
  93. instead generate \fIfile\fR with cryptographic hashes that can later be used to
  94. verify if the contents of input was changed.
  95. When doing "generate", "encrypt" or "decrypt" operation, do not encrypt
  96. asymmetrically, but instead generate or use a file with a key for specified
  97. symmetric cipher. Use "-g help" to see available symmetric primitives. For
  98. symmetric encryption to work, at least one stream cipher (marked with C) and at
  99. least one hash function (marked with H, used to protect against malleability)
  100. separated by comma need to be selected. Additionally, user can specify
  101. "longblock" or "shortblock" keyword to manipulate size of internal encryption
  102. block structure (longer blocks consume more RAM, but the ciphertext doesn't
  103. grow very much); or the "longkey" flag which creates larger symmetric key to
  104. provide more key material to the ciphers (which can help to protect against
  105. low-quality random numbers, but is generally unnecessary and even considered to
  106. be a bad practice). It is also possible to combine more stream ciphers and hash
  107. functions.
  108. Purpose of the \fB\-\-symmetric\fR option is that symmetric cryptography is a
  109. lot faster than asymmetric, and symmetric primitives usually work also on very
  110. large files and data streams, as they don't need to be fully copied into
  111. allocated memory for this purpose. Thus, if working with a large file, process
  112. it symmetrically first, then sign/encrypt the (tiny) symmetric \fIfile\fR
  113. asymmetrically and send it along with the (possibly encrypted) large file.
  114. .SS
  115. Key management:
  116. In Codecrypt, each public key has a KeyID, which is basically a hash of its
  117. representation that is used to identify the key globally. Each public key is
  118. stored along with a key name, which is a convenience tool for users who can
  119. store arbitrary information about e.g. what is the key meant for or who it
  120. belongs to. Public keys also have an algorithm identifier to specify how to
  121. work with them, and sometimes also attached a private key to form a secret
  122. "keypair".
  123. Keys can be specified using several methods:
  124. Using KeyID -- the key specification starts with @ and continues with several
  125. first characters of the KeyID that identify a single key with that prefix.
  126. Using a name -- key specification consists of a string, a key is then matched
  127. if its name contains the specified string. Matching is case-insensitive.
  128. .TP
  129. \fB\-g\fR, \fB\-\-gen\-key\fR <\fIalgorithm\fR>
  130. Generate a keypair for usage with specified algorithm. Use "-g help" to get
  131. list of all algorithms available. Listing also contains flags "S" and "E",
  132. meaning that algorithm can be used for signatures or encryption, or "H" and "C"
  133. for usage with symmetric hashes and ciphers. In asymmetric case (where the
  134. algorithm names are long) the supplied algorithm name does not need to be a
  135. full name, but must match only one available algorithm.
  136. .TP
  137. \fB\-N\fR, \fB\-\-name\fR <\fIkeyname\fR>
  138. Specify that affected keys (those being imported, generated, exported or
  139. renamed) should be newly renamed to \fIkeyname\fR.
  140. .TP
  141. \fB\-F\fR, \fB\-\-filter\fR <\fIkeyspec\fR>
  142. When listing, importing or exporting keys, only process keys that match
  143. \fIkeyspec\fR.
  144. .TP
  145. \fB\-k\fR, \fB\-\-list\fR
  146. List available public keys.
  147. .TP
  148. \fB\-K\fR, \fB\-\-list\-secret\fR
  149. List available private keys (in keypairs).
  150. .TP
  151. \fB\-i\fR, \fB\-\-import\fR
  152. Import public keys.
  153. .TP
  154. \fB\-I\fR, \fB\-\-import\-secret\fR
  155. Import private keypairs.
  156. .TP
  157. \fB\-n\fR, \fB\-\-no\-action\fR
  158. On import, do not really import the keys, but only print what keys and names
  159. will be imported. This is useful for preventing accepting unwanted private or
  160. public keys.
  161. .TP
  162. \fB\-f\fR, \fB\-\-fingerprint\fR
  163. When printing keys, format full KeyIDs. Note that full KeyIDs can be used in
  164. similar way as fingerprints known from other crypto tools.
  165. .TP
  166. \fB\-p\fR, \fB\-\-export\fR
  167. Export public keys in keyring format.
  168. .TP
  169. \fB\-P\fR, \fB\-\-export\-secret\fR
  170. Export private keys. (Do this carefully!)
  171. .TP
  172. \fB\-x\fR, \fB\-\-delete\fR <\fIkeyspec\fR>
  173. Remove matching keys from public keyring.
  174. .TP
  175. \fB\-X\fR, \fB\-\-delete\-secret\fR <\fIkeyspec\fR>
  176. Remove matching keys from private keypairs.
  177. .TP
  178. \fB\-m\fR, \fB\-\-rename\fR <\fIkeyspec\fR>
  179. Rename matching public keys. Use "-N" to specify a new name.
  180. .TP
  181. \fB\-M\fR, \fB\-\-rename\-secret\fR <\fIkeyspec\fR>
  182. Rename matching private keys.
  183. .TP
  184. \fB\-w\fR, \fB\-\-with-lock\fR <\fIfile\fR>
  185. When loading the secret part of the keyring, decrypt the file using the
  186. specified shared key. If that file looks encrypted and \fB-w\fR is not
  187. specified, asking for the password interactively (i.e. "-w @") will be assumed.
  188. .SH FILES
  189. Codecrypt stores user data in a directory specified by environment variable
  190. CCR_DIR, which defaults to "$HOME/.ccr". It contains the files "pubkeys" and
  191. "secrets" which are sencode keyring representations of user's public and
  192. private keyring.
  193. Backups of user data (i.e. for each file the last state that was loaded
  194. successfully) are, on each change, written to files "pubkeys~" and "secrets~".
  195. When Codecrypt is running, it locks the ".ccr" directory using a lockfile "lock"
  196. and applying flock(2) to it.
  197. For seeding the random number generator, Codecrypt uses data from "/dev/random"
  198. for generating keys and "/dev/urandom" for everything else, e.g. nonces or
  199. envelopes. Both cases can be overridden at once by specifying some other
  200. filename in environment variable CCR_RANDOM_SEED.
  202. \fBccr\fR returns exit status 0 if there was no error and all cryptography went
  203. fine, or 1 on generic errors. If the error was that a missing hash algorithm or
  204. a public or private key was needed to complete the operation, 2 is returned. If
  205. signature or hash verification fails (e.g. the signature is bad or likely
  206. forged), the program returns 3.
  208. Program offers several "algorithms" that can be used for signatures and
  209. encryption. Use "ccr -g help" to get a list of supported algorithms.
  210. FMTSeq-named schemes are the Merkle-tree signature algorithms. The name
  211. FMTSEQxxx-HASH1-HASH2 means, that the scheme provides attack complexity ("bit
  212. security") around 2^xxx, HASH1 is used as a message digest algorithm, and HASH2
  213. is used for construction of Merkle tree.
  214. McEliece-based encryption schemes are formed from McEliece trapdoor running on
  215. quasi-dyadic Goppa codes (the MCEQD- algorithms) and on quasi-cyclis
  216. medium-density parity-check (QCMDPC- ones) with Fujisaki-Okamoto encryption
  217. padding for CCA2. Algorithm name MCEQDxxxFO-HASH-CIPHER means that the trapdoor
  218. is designed to provide attack complexity around 2^xxx, and HASH and CIPHER are
  219. the hash and symmetric cipher functions that are used in Fujisaki-Okamoto
  220. padding scheme.
  221. As of November 2015, users are advised to deploy the 2^128-secure variants of the
  222. algorithms -- running 2^128 operations would require around 10^22 years of CPU
  223. time (of a pretty fast CPU), which is considered more than sufficient for any
  224. reasonable setup and using stronger algorithms seems just completely
  225. unnecessary.
  226. Note that using stronger algorithm variants does not come with any serious
  227. performance drawback and protects the user from non-fatal attacks that decrease
  228. the security of the scheme only by a small amount -- compare getting an attack
  229. speedup of 2^20 on a scheme with 2^80 bit security (which is fatal) with
  230. getting the same speedup on a scheme with 2^128 security (where the resulting
  231. 2^108 is still strong).
  232. For comparison with existing schemes, 2^128 security level is very roughly
  233. equivalent to that of classical RSA with 3072bit modulus (which is, accordingly
  234. to the best results available in June 2013 for general public, reported to
  235. provide roughly 2^112 attack complexity).
  236. For another comparison, a very good idea about the unbelievably insane amount
  237. of energy that is actually needed for brute-forcing 2^256 operations can be
  238. obtained from Wikipedia, which estimates the size of whole observable universe
  239. (!) to around 2^270 atoms.
  240. All algorithms are believed to be resistant to quantum-computer-specific
  241. attacks, except for the generic case of Grover search which (in a very
  242. idealized case and very roughly) halves the bit security (although the attack
  243. remains exponential). Users who are aware of large quantum computers being
  244. built are advised to use 2^192 or 2^256 bit security keys.
  246. Symmetric keys can be specified using a filename, or expanded from a password
  247. (which is convenient e.g. for protecting private keys): If the filename for
  248. \fB-S\fR starts with "@", program will first check the rest of the filename to
  249. find a symmetric cipher algorithm specification, as in \fB-g\fR. If nothing is
  250. specified, it will check CCR_SYMMETRIC_ALGORITHM environment variable, and if
  251. that is still unspecified, it will default to "SYM,SHORTBLOCK". The reason for
  252. defaulting the short blocks is that the functionality focuses on tiny keys.
  253. After the symmetric algorithm is chosen, program will try to get the password
  254. from environment variable CCR_SYMMETRIC_PASSWORD. If that variable is not set,
  255. it will ask the user for the password interactively.
  256. The password will be expanded to internally form a symmetric key for the
  257. specified algorithm, which will in turn be used for the requested action.
  258. Symmetric and private keys may be encrypted by a password or a symmetric key.
  259. Parameter \fB-w\fR accepts the same arguments as \fB-S\fR, with the exception
  260. that the resulting loaded or internally generated symmetric key will be used to
  261. encrypt or decrypt symmetric and private keys when required:
  262. Actions \fB-L\fR and \fB-U\fR can be used to lock, resp. unlock private keys
  263. (specific keys to be modified can be selected using \fB--filter\fR) or
  264. symmetric keys (if used together with \fB-S\fR). Action \fB-g\fR can be
  265. modified by \fB-L\fR in the same way.
  266. The environment variables used for automatically-specifying the password in
  267. this case are separate from the previous ones: CCR_KEYRING_PASSWORD and
  268. CCR_KEYRING_ALGORITHM for locking/unlocking private keys, respectively
  269. CCR_SYMKEY_PASSWORD and CCR_SYMKEY_ALGORITHM for specifying symmetric key used
  270. to unlock other symmetric keys (even the ones that are themselves used for
  271. locking other keys).
  273. .SS General advice
  274. Codecrypt does not do much to prevent damage from mistakes of the user. Be
  275. especially careful when managing your keyring, be aware that some operations
  276. can rename or delete more keys at once. Used cryptography is relatively new,
  277. therefore be sure to verify current state of cryptanalysis before you put your
  278. data at risk.
  279. .SS On-line use and side channels
  280. Codecrypt does not do much to prevent attacks that rely on side channels that
  281. are common on the internet. IF YOU DESPERATELY NEED TO PUT CODECRYPT TO E.G.
  283. CHANNELS: Never execute Codecrypt directly from the server software. Sanitize
  284. BOTH the input and output of Codecrypt. Make any way to gather usable
  285. statistics about the running time of Codecrypt impossible. Make it hard for
  286. anyone to collect side-channel information, and, in particular, ensure that
  287. your application does not allow to repeatedly run Codecrypt in a way that makes
  288. it fail on invalid or damaged outputs, or produces any statistical
  289. information about timings and failures of the runs.
  290. .SS Current state of cryptanalysis
  291. In a fashion similar to aforementioned `new cryptography', the original
  292. algebraic variant of quasi-dyadic McEliece that was in Codecrypt has been
  293. broken by an algebraic attack. Security was greatly reduced. Use the QC-MDPC
  294. variant which dodges similar attacks.
  295. .SS Large files
  296. Codecrypt is not very good for working directly with large files. Because of
  297. the message format and code clarity, whole input files and messages are usually
  298. loaded into memory before getting signed/encrypted. Fixing the problem requires
  299. some deep structural changes in Codecrypt that would break most of the achieved
  300. internal simplicity, therefore the fix is probably not going to happen. You can
  301. easily workaround the whole problem using symmetric ciphers (for encryption of
  302. large files) or hashfiles (for signatures of large files). See the
  303. \fB\-\-symmetric\fR option.
  304. .SS FMTSeq signatures
  305. FMTSeq signatures are constructed from one-time signature scheme, for this
  306. reason the private key changes after each signature, basically by increasing
  309. DAMAGED. Never use the same key on two places at once. If you backup the
  310. private keys, be sure to backup it everytime after a signature is made.
  311. If something goes wrong and you really need to use the key that has been, for
  312. example, recovered from a backup, you can still "skip" the counter by producing
  313. and \fBdiscarding\fR some dummy signatures (ccr -s </dev/null >/dev/null). If
  314. you plan to do that for some real purpose, for your own safety be sure to
  315. understand inner workings of FMTSeq, especially how the Diffie-Lamport
  316. signature scheme degrades after publishing more than one signature.
  317. FMTSeq can only produce a limited amount of signatures (but still a pretty
  318. large number). When the remaining signature count starts to get low, Codecrypt
  319. will print warning messages. In that case, users are advised to generate and
  320. certify new keys.
  321. .SS Working with keys
  322. Try to always use the "-n" option before you actually import keys -- blind
  323. import of keys can bring serious inconsistencies into your key naming scheme.
  324. In a distant universe after much computation, KeyIDs can collide. If you find
  325. someone who has a colliding KeyID, kiss him and generate another key.
  326. .SS Own sources of random seed
  327. Using CCR_RANDOM_SEED is slightly counterintuitive and dangerous, use it only
  328. for debugging.
  329. If your system does not have /dev/(u)random, make a port by choosing a safe
  330. value in the source code instead of specifying the seed each time you invoke
  331. Codecrypt.
  332. If the seed source of your system can not be trusted, fix the system instead.
  333. .SH Password-derived symmetric keys
  334. Passwords are weak and, if times did not change and humanoids are still
  335. humanoids, you are prone to $5 wrench attacks.
  336. Combination of \fB-L\fR and \fB-S\fR options can be exploited to output a
  337. password-expanded key to a file. Doing that for any real purpose is a bad idea.
  338. .SH Troubleshooting/FAQ
  339. Q: I can't read/verify messages from versions 1.3.1 and older!
  340. A: KeyID algorithm changed after that version. If you want, you can manually
  341. rewrite the message sencode envelopes to contain new recipient/signer KeyIDs
  342. and new message identificators, things should work perfectly after that.
  343. Q: I can't read/verify messages from versions 1.7.4 and older!
  344. A: There was a mistake with no security implications in Cubehash
  345. implementation. Same advice as in previous case applies.
  346. Q: Some signatures from version 1.5 and older fail to verify!
  347. A: There was a slight mistake in padding of messages shorter than signature
  348. hash function size (64 bytes in the 256-bit-secure signature types) with no
  349. security implications. It was decided not to provide backward compatibility for
  350. this minor use-case. If you really need to verify such signatures, edit the
  351. msg_pad function in src/algos_sig.h so that the `load_key()' function is called
  352. on empty vector instead of `out'.
  353. Q: My Cubehash-based FMTSeq key produces invalid signatures after version
  354. 1.7.5!
  355. A: Cubehash was corrected to obey standards in 1.7.5. It is possible to
  356. generate a new public key that would work with your private key, but the
  357. general advice is just to generate a new key.
  358. Q: I want to sign/encrypt a large file but it took all my RAM and takes ages!
  359. A: Use \fB--symmetric\fR option. See the `CAVEATS' section for more details.
  360. Q: How much `broken' is the original quasi-dyadic McEliece?
  361. A: The private key of proposed dyadic variant by Misoczki and Barreto can be
  362. derived from the public key with standard computer equipment pretty quickly.
  363. .SH EXAMPLE
  364. Following commands roughly demonstrate command line usage of \fBccr\fR:
  365. .nf
  366. .sp
  367. ccr -g help
  368. ccr -g sig --name "John Doe" # your signature key
  369. ccr -g enc --name "John Doe" # your encryption key
  370. ccr -K #watch the generated keys
  371. ccr -k
  372. ccr -p -a -o my_pubkeys.asc -F Doe # export your pubkeys for friends
  373. #see what people sent us
  374. ccr -ina < friends_pubkeys.asc
  375. #import Frank's key and rename it
  376. ccr -ia -R friends_pubkeys.asc --name "Friendly Frank"
  377. #send a nice message to Frank (you can also specify him by @12345 keyid)
  378. ccr -se -r Frank < Document.doc > Message_to_frank.ccr
  379. #receive a reply
  380. ccr -dv -o Decrypted_verified_reply.doc <Reply_from_frank.ccr
  381. #rename other's keys
  382. ccr -m Frank -N "Unfriendly Frank"
  383. #and delete pukeys of everyone who's Unfriendly
  384. ccr -x Unfri
  385. #create hashfile from a large file
  386. ccr -sS hashfile.ccr < big_data.iso
  387. #verify the hashfile
  388. ccr -vS hashfile.ccr < the_same_big_data.iso
  389. #create (ascii-armored) symmetric key and encrypt a large file
  390. ccr -g sha256,chacha20 -aS symkey.asc
  391. ccr -eaS symkey.asc -R big_data.iso -o big_data_encrypted.iso
  392. #decrypt a large file
  393. ccr -daS symkey.asc <big_data_encrypted.iso >big_data.iso
  394. #password-protect all your private keys
  395. ccr -L
  396. #protect a symmetric key using another symmetric key
  397. ccr -L -S symkey1 -w symkey2
  398. #password-protect symkey2 with a custom cipher
  399. ccr -L -S symkey2 -w @xsynd,cube512
  400. .fi
  402. Used cryptography is relatively new. For this reason, Codecrypt eats data. Use
  403. it with caution.
  404. .SH AUTHORS
  405. Codecrypt was written by Mirek Kratochvil in 2013-2017.