From aa82708a6ee2ff26c093dbd3e25fea8ceed349aa Mon Sep 17 00:00:00 2001 From: James Crayne Date: Wed, 24 Jun 2015 03:37:09 -0400 Subject: Improving documentation... --- kiki.hs | 157 +++++++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 91 insertions(+), 66 deletions(-) (limited to 'kiki.hs') diff --git a/kiki.hs b/kiki.hs index 55fe37b..000dfa2 100644 --- a/kiki.hs +++ b/kiki.hs @@ -513,7 +513,11 @@ kiki_usage bExport bImport bSecret cmd = putStr $ ," [--wallets FILE ...]" ,"" ," sync-secret syncs the information inside your OpenGPG keyring with information" - ," in other files. Information flows both in and out of your keyring." + ," in other files. Information flows both in and out of your keyring. This one command" + ," is powerful enough to impliment all the functionality of kiki commands in the import-*," + ," export-*, and sync-* families. Those other commands are mainly added to facilitate" + ," a redundant safe gaurd which restricts the flow of information in such a way that is" + ," theoretically less error prone." ,"" ," sync-secret works by first creating a combined database containing all information" ," and then updating all files (including OpenGPG files, as well as files specified as" @@ -531,10 +535,10 @@ kiki_usage bExport bImport bSecret cmd = putStr $ ," specified, they will all have the same keys after the the operation completes." ,"" ," The --hosts option is experimental and may be removed in the future. Any files given" - ," as arguments to this option will be assumed to be in the format /etc/hosts, and will" + ," as arguments to this option will be assumed to be in the format of /etc/hosts, and will" ," be updated with any hostname information currently stored within your OpenGPG keyring." ," Additionally, if the file has hostnames for the ip corresponding to a master key, then" - ," then the mastekey is updated with unsigned annotations recording the additional hostnames." + ," then the masterkey is updated with unsigned annotations recording the additional hostnames." ," Warning: this effects all master keys, regardless of whether they have secret key" ," information, hence the annotations being unsigned." ,"" @@ -545,33 +549,7 @@ kiki_usage bExport bImport bSecret cmd = putStr $ ," If KEYSPEC arguments appear prior to any of --keyrings, --wallets, or --hosts," ," then they are interpretted as if arguments to --keypairs." ,"" - ,"FLAGS" - ," --help Gives usage information" - ,"" - ," --homedir PATH Specifies the path where pubring.gpg and secring.gpg are located." - ," Typically this would be your ~/.gnupg or the contents of the" - ," GNUPGHOME environment variable." - ,"" - ," --passphrase-fd FD The file descriptor from which to read a passphrase." - ,"" - ," --import Update home keyring files (pubring.gpg and secring.gpg) with" - ," new master keys found in the input files specified by the" - ," --keyrings option. Note that new subkeys for known master-key" - ," identities will be imported regardless." - ,"" - ," --import-if-authentic" - ," Like --import except that it requires a signature from the" - ," working key on any new identities that are imported into the" - ," home keyring files." - ,"" - ," --autosign Create or sign a self-authenticating UID based on tor key." - ," Combine this with --import-if-authentic to import self-authenticating" - ," identities that may not have previously been signed." - ,"" - ," --show-wk After the operation completes, output the possibly modified working" - ," key identity information." - ,"" - ] ++ syncflags + ] ++ syncflags ++ specifyingFiles "sync-public" -> unlines $ ["kiki sync-public [options...]" ,"" @@ -592,7 +570,7 @@ kiki_usage bExport bImport bSecret cmd = putStr $ ," specifying a substring of an associated UID." ,"" ," (See 'kiki help spec' for more information.)" - ] ++ syncflags + ] ++ syncflags ++ specifyingFiles "import-secret" -> unlines $ ["kiki import-secret [options...]" ,"" @@ -600,7 +578,9 @@ kiki_usage bExport bImport bSecret cmd = putStr $ ," alter any files outside of the home directory (see --homedir)." ,"" ," The files pubring.gpg and secring.gpg in the directory specified by the " - ," --homedir option are implicitly included in the keyring set." + ," --homedir option are implicitly included in the keyring set. Unlike the" + ," sync-secret command, information will flow into these files, but not out" + ," of them." ,"" ," Subkeys that are imported with kiki are given an annotation \"usage@\" which" ," indicates what the key is for. This tag can be used as a SPEC to select a" @@ -608,7 +588,7 @@ kiki_usage bExport bImport bSecret cmd = putStr $ ," specifying a substring of an associated UID." ,"" ," (See 'kiki help spec' for more information.)" - ] ++ syncflags + ] ++ syncflags ++ specifyingFiles "import-public" -> unlines $ ["kiki import-public [options...]" ,"" @@ -629,18 +609,21 @@ kiki_usage bExport bImport bSecret cmd = putStr $ ," specifying a substring of an associated UID." ,"" ," (See 'kiki help spec' for more information.)" - ] ++ syncflags + ] ++ syncflags ++ specifyingFiles "export-secret" -> unlines $ ["kiki export-secret [options...]" ,"" ," export-secret updates a set of key files using information from your keyring." ,"" - ," The files pubring.gpg and secring.gpg in the directory specified by the " - ," --homedir option are implicitly included in the keyring set." + ," The files pubring.gpg and secring.gpg in the directory specified by the" + ," --homedir option are implicitly included in the keyring set. Unlike with the" + ," sync-secret command, information only flows out of these files and not in to" + ," them. Barring this however, the usage and behavior of export-secret is similar" + ," to that of sync-secret." ,"" ," (See 'kiki help spec' for more information.)" ,"" - ] ++ syncflags + ] ++ syncflags ++ specifyingFiles "export-public" -> unlines $ ["kiki export-public [options...]" ,"" @@ -653,39 +636,43 @@ kiki_usage bExport bImport bSecret cmd = putStr $ ,"" ," (See 'kiki help spec' for more information.)" ,"" - ] ++ syncflags + ] ++ specifyingFiles "spec" -> unlines keyspec where commonOptions :: [String] commonOptions = - [" --homedir DIR" - ," Where to find the the files secring.gpg and pubring.gpg. The " - ," default location is taken from the environment variable " - ," GNUPGHOME." + [" --help" + ," Gives usage information" ,"" - ," --passphrase-fd N" - ," Read passphrase from the given file descriptor." + ," --homedir DIR" + ," Where to find the files secring.gpg and pubring.gpg. The" + ," default location is taken from the environment variable" + ," GNUPGHOME. If this environment variable is not set and no" + ," directory is specified using this option then a hardcoded" + ," default of ~/.gnupg is assumed. " + ,"" + ," WARNING: Confusingly, this is *not* your home directory as" + ," given by the HOME environment variable. The option is named" + ," or rather misnamed in a fashion similar to the gpg option with" + ," exactly the same functionality." + ,""] ++ documentPassphraseFDFlag bExport bImport bSecret ++ showwk + showwk :: [String] + showwk = + [" --show-wk" + ," After the operation completes, output the possibly modified" + ," working key identity information." ,"" ] syncflags :: [String] syncflags = ["" - ,"Flags:"] ++ commonOptions ++ - [" --import Add master keys to pubring.gpg. Without this option, only UID" - ," and subkey data is updated. " - ,"" - ," --import-if-authentic" - ," Add signed master keys to pubring.gpg. Like --import except that" - ," only keys with signatures from the working key (--show-wk) are" - ," imported." - ,"" - ," --autosign Sign all cross-certified tor-style UIDs." - ," A tor-style UID is of the form:" - ," Anonymous " - ," It is considered cross certified if there exists a cross-certified" - ," 'tor' subkey corresponding to the address HOSTNAME.onion." - ,"" - ,"SPECIFYING FILES:" + ,"Flags:"] ++ commonOptions + ++ documentImportFlag bExport bImport bSecret + ++ documentImportIfAuthenticFlag bExport bImport bSecret + ++ documentAutoSignFlag bExport bImport bSecret + specifyingFiles :: [String] + specifyingFiles = + ["SPECIFYING FILES:" ] ++ documentKeyPairsOption bExport bImport bSecret ++ documentKeyRingsOption bExport bImport bSecret ++ documentWalletsOption bExport bImport bSecret @@ -728,6 +715,37 @@ kiki_usage bExport bImport bSecret cmd = putStr $ ," 5E24CD442AA6965D2012E62A905C24185D5379C2" ] +documentPassphraseFDFlag bExport bImport bSecret = + [" --passphrase-fd FD" + ," The file descripter from which to read a passphrase. If FD is" + ," 0, then the passphrase is inputted via stdin. Note that this" + ," requires the user to issue CTRL-D to send EOF, so that kiki" + ," knows to continue." + ,""] + +documentImportFlag bExport bImport bSecret = + if bImport then + [" --import Add master keys to pubring.gpg. Without this option, only UID" + ," and subkey data is updated. " + ,""] + else [] + +documentImportIfAuthenticFlag bExport bImport bSecret = + if bImport then + [" --import-if-authentic" + ," Add signed master keys to pubring.gpg. Like --import except that" + ," only keys with signatures from the working key (--show-wk) are" + ," imported." + ,""] + else [] + +documentAutoSignFlag bExport bImport bSecret = + [" --autosign Sign all cross-certified tor-style UIDs." + ," A tor-style UID is of the form:" + ," Anonymous " + ," It is considered cross certified if there exists a cross-certified" + ," 'tor' subkey corresponding to the address HOSTNAME.onion." + ,""] documentKeyPairsOption :: Bool -> Bool -> Bool -> [String] documentKeyPairsOption bExport bImport bSecret = [" --keypairs [KEYSPEC ...]" @@ -759,6 +777,7 @@ documentKeyPairsOption bExport bImport bSecret = ," file for import. Unlike the sync-secret command, this command" ," leaves no possibility of secret key information leaking from" ," your OpenGPG keyring into specified files." + ,"" ] ++ afterSecond (False,True,True) -> -- import-secret [" This option specifies the paths of such private PEM files which" @@ -768,6 +787,7 @@ documentKeyPairsOption bExport bImport bSecret = ," command will be executed in a modified environment with the" ," expectation of creating the PEM file for import. Files external" ," to your OpenGPG keyring will not be modified by this command." + ,"" ] ++ afterSecond (False,True,False) -> -- import-public [" This option specifies the paths of PEM files, of both the" @@ -781,6 +801,7 @@ documentKeyPairsOption bExport bImport bSecret = ," Unlike the import-secret command, this command leaves no" ," possibility of secret key information leaking from your OpenGPG" ," keyring. " + ,"" ] ++ afterSecond (True,False,True) -> -- export-secret [" This option specifies the paths of such private PEM files, of" @@ -790,6 +811,7 @@ documentKeyPairsOption bExport bImport bSecret = ," command. Unlike the export-secret comamnd, this command leaves" ," no possibility that secret key information will leak from your" ," OpenGPG keyring." + ,"" ] ++ afterSecond (True,False,False) -> -- export-public [" This option specifies the paths of PEM files, of the private or" @@ -797,6 +819,7 @@ documentKeyPairsOption bExport bImport bSecret = ," the export-secret command, this command leaves no possibility" ," of secret key information leaking from your OpenGPG keyring" ," into the specified files." + ,"" ] ++ afterSecond _ -> afterSecond where afterSecond = @@ -844,6 +867,7 @@ documentKeyPairsOption bExport bImport bSecret = ," information." ,"" ," (See 'kiki help spec' for more information.)" + ,"" ] documentKeyRingsOption :: Bool -> Bool -> Bool -> [String] @@ -858,7 +882,7 @@ documentKeyRingsOption bExport bImport bSecret = documentWalletsOption :: Bool -> Bool -> Bool -> [String] documentWalletsOption bExport bImport bSecret = - [" --wallets FILE FILE..." + [" --wallets [FILE ...]" ," Provide wallet files with secret crypto-coin keys in Wallet" ," Import Format. The keys will be treated as subkeys of your" ," current working key (the one shown by --show-wk)." @@ -867,11 +891,12 @@ documentWalletsOption bExport bImport bSecret = documentHostsOption :: Bool -> Bool -> Bool -> [String] documentHostsOption bExport bImport bSecret = [" --hosts [FILE ...]" - ," EXPERIMENTAL! May be removed in the future. This option specifies files" - ," from which to read or write hostname aliases. The format is the same as" - ," /etc/hosts on unix systems. WARNING: hostname aliases may be imported into" - ," the gpg keyring files, but they are currently NOT signed and may be altered" - ," in transit." + ," EXPERIMENTAL! May be removed in the future. This option" + ," specifies files from which to read or write hostname aliases." + ," The format is the same as /etc/hosts on unix systems. WARNING:" + ," hostname aliases may be imported into the gpg keyring files," + ," but they are currently NOT signed and may be altered in" + ," transit." ,""] -- cgit v1.2.3