From cdcf38baa587a7d44d200dd4fa33a5b20a8765c9 Mon Sep 17 00:00:00 2001 From: James Crayne Date: Wed, 24 Jun 2015 00:02:22 -0400 Subject: Documentation update, WIP --- kiki.hs | 242 ++++++++++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 161 insertions(+), 81 deletions(-) (limited to 'kiki.hs') diff --git a/kiki.hs b/kiki.hs index 8d13f6b..55fe37b 100644 --- a/kiki.hs +++ b/kiki.hs @@ -452,7 +452,8 @@ whoseKey rsakey db = filter matchkey (Map.elems db) -kiki_usage bSecret cmd = putStr $ +kiki_usage :: Bool -> Bool -> Bool -> String -> IO () +kiki_usage bExport bImport bSecret cmd = putStr $ case cmd of "show" -> unlines $ ["kiki show [options...]" @@ -570,46 +571,6 @@ kiki_usage bSecret cmd = putStr $ ," --show-wk After the operation completes, output the possibly modified working" ," key identity information." ,"" - ,"INPUT FILES" - ," --keypairs [KEYSPEC ...]" - ," KEYSPEC := tag '=' file '{' '}'" - ," | tag '=' file" - - ," Specify the paths of private PEM files which either currently contain" - ," keys to be imported, or lack keys to be exported. If your working key" - ," has no subkey with the given tag, and the file is empty or does not exist," - ," and a shell command is specified in braces, then the shell command will be " - ," executed in a modified environment with the expectation of creating the PEM" - ," file for import." - ,"" - ," 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" - ," particular key. If a specifed PEM file contains a novel key for an existing" - ," tag, it will import the new key and you will have multiple keys with the same" - ," tag." - ,"" - ," Your OpenGPG keyring contains time stamps for each subkey. Timestamps of newly" - ," imported keys will reflect the mtimes of the files from which they were imported." - ," In the case that the key already exists in your OpenGPG keyring as well as in one" - ," of the specified files, the timestamp in your OpenGPG keyring is not updated." - ,"" - ," Note that this option is implicit if no options documented in this section" - ," were specified. See 'kiki help spec' for more information." - ,"" - ," --keyrings [FILE ...]" - ," These files are PGP keyring files. The format is similar to that of the" - ," GNU GPG state files: pubring.gpg and secring.gpg. Those files needn't be" - ," specified here as they are included implicitly." - ,"" - ," --wallets [FILE ...]" - ," Bitcoin wallet files. TODO: document format." - ,"" - ," --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." ] ++ syncflags "sync-public" -> unlines $ ["kiki sync-public [options...]" @@ -724,42 +685,12 @@ kiki_usage bSecret cmd = putStr $ ," It is considered cross certified if there exists a cross-certified" ," 'tor' subkey corresponding to the address HOSTNAME.onion." ,"" - ,"Merging:" - ," --keyrings FILE FILE..." - ," Provide keyring files other than the implicit secring.gpg and" - ," pubring.gpg in the --homedir. This option is implicit unless" - ," --keypairs or --wallets is used." - ,""] - ++ do - guard bSecret - return $ unlines - [" --wallets FILE 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)." - ,"" - ," --keypairs KEYSPEC KEYSPEC..." - ," A keypair is a secret key coupled with it's corresponding public" - ," key, both of which are ordinarily stored in a single file in pem" - ," format. Users incognisant of the fact that the public key (which" - ," is also stored separately) is in this file, often think of it as" - ," their secret key file." - ,"" - ," Each KEYSPEC specifies that a key should match the content and" - ," timestamp of an external PKCS #1 private RSA key file." - ," " - ," KEYSPEC ::= SPEC=FILE{CMD} " - ,"" - ," The form of SPEC is documented elsewhere. If there is only one master" - ," key in your keyring and only one key is used for each purpose, then" - ," it is possible for SPEC in this case to merely be a tag which offers" - ," information about what this key is used for, for example, any of" - ," `tor', `ssh-client', `ssh-host', or `strongswan' will do." - ,"" - ," If neither SPEC or FILE match any keys, then the CMD will be " - ," executed in order to create the FILE." - ," (See 'kiki help spec' for more information.)" - ,""] + ,"SPECIFYING FILES:" + ] ++ documentKeyPairsOption bExport bImport bSecret + ++ documentKeyRingsOption bExport bImport bSecret + ++ documentWalletsOption bExport bImport bSecret + ++ documentHostsOption bExport bImport bSecret + keyspec :: [String] keyspec = -- unlines $ ["Specifying keys on the kiki command line:" ,"" @@ -797,6 +728,154 @@ kiki_usage bSecret cmd = putStr $ ," 5E24CD442AA6965D2012E62A905C24185D5379C2" ] +documentKeyPairsOption :: Bool -> Bool -> Bool -> [String] +documentKeyPairsOption bExport bImport bSecret = + [" --keypairs [KEYSPEC ...]" + ," A keypair is a secret key coupled with it's corresponding public" + ," key, both of which are ordinarily stored in a single file in PEM" + ," format. Users incognisant of the fact that the public key (which" + ," is also stored separately) is in this file, often think of it as" + ," their secret key file." + ,"" + ] ++ case (bExport,bImport,bSecret) of + (True,True,True) -> -- sync-secret + [" This option specifies the paths of such private PEM files which" + ," either currently contain keys to be imported, or lack keys to" + ," be exported. If your working key has no subkey with the given" + ," tag, and the file is empty or does not exist, and a shell" + ," command is specified in braces, then the shell command will be" + ," executed in a modified environment with the expectation of" + ," creating the PEM file for import." + ,"" + ] ++ afterSecond + (True,True,False) -> -- sync-public + [" This option specifies the paths of PEM files, of both the" + ," public and private variety, which either currently contain" + ," public keys to be imported, or lack public keys to be exported." + ," If your working key has no subkey with the given tag, and the" + ," file is empty or does not exist, and a shell command is" + ," specified in braces, then the shell command will be executed in" + ," a modified environment with the expectation of creating the PEM" + ," 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" + ," contain keys to be imported. If your working key has no subkey" + ," with the given tag, and the file is empty or does not exist," + ," and a shell command is specified in braces, then the shell" + ," 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" + ," public and private variety, which either currently contain" + ," contain keys to be imported. If your working key has no subkey" + ," with the given tag, and the file is empty or does not exist," + ," and a shell command is specified in braces, then the shell" + ," 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." + ," 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" + ," both the public variety, to which kiki will export keys. These" + ," files will be updated with information from your OpenGPG" + ," keyring, but your OpenGPG keyring will not be modified by this" + ," 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" + ," public variety, which lack public keys to be exported. Unlike" + ," 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 = + [" 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 particular key. If a specifed PEM" + ," file contains a novel key for an existing tag, it will imported," + ," and you will have multiple keys with the same tag." + ,"" + ," Each KEYSPEC specifies that a key should match the content and" + ," timestamp of an external PKCS #1 private RSA key file." + ," " + ," KEYSPEC ::= tag '=' file" + ] ++ if bImport then " | tag '=' file '{' '}'":next + else next + next = + ["" + ," Or in more complicated cases," + ,"" + ," KEYSPEC ::= SPEC '=' file" + ] ++ if bImport then " | SPEC '=' file '{' '}'":next' + else next' + next' = + ["" + ," where the format of SPEC is documented in 'kiki help spec'." + ,"" + ," If there is only one master key in your keyring and only one" + ," key is used for each purpose, then it is possible for SPEC in" + ," this case to merely be a tag which offers information about" + ," what this key is used for, for example, any of `tor'," + ," `ssh-client', `ssh-host', or `strongswan' will do."] ++ next'' + next'' = if bImport then timeStamps ++ next''' else next''' + timeStamps = + ["" + ," Your OpenGPG keyring contains time stamps for each subkey." + ," Timestamps of newly imported keys will reflect the mtimes of" + ," the files from which they were imported. In the case that the" + ," key already exists in your OpenGPG keyring as well as in one of" + ," the specified files, the timestamp in your OpenGPG keyring is" + ," not updated."] + next'''= + ["" + ," Note that this option is implicit if no options documented in" + ," this section were specified. See 'kiki help spec' for more" + ," information." + ,"" + ," (See 'kiki help spec' for more information.)" + ] + +documentKeyRingsOption :: Bool -> Bool -> Bool -> [String] +documentKeyRingsOption bExport bImport bSecret = + [" --keyrings [FILE ...]" + ," These files are PGP keyring files. The format is similar to" + ," that of the GNU GPG state files: pubring.gpg and secring.gpg." + ," Those files needn't be specified here as they are included" + ," implicitly." + ,"" + ] + +documentWalletsOption :: Bool -> Bool -> Bool -> [String] +documentWalletsOption bExport bImport bSecret = + [" --wallets FILE 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)." + ,""] + +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." + ,""] + + + processArgs sargspec polyVariadicArgs defaultPoly args_raw = (sargs,margs) where (args,trail1) = break (=="--") args_raw @@ -854,6 +933,7 @@ buildStreamInfo rtyp ftyp = StreamInfo { typ = ftyp , initializer = Nothing , transforms = [] } + sync :: Bool -> Bool -> Bool -> String -> [String] -> IO () sync bExport bImport bSecret cmdarg args_raw = do let (sargs,margs) = processArgs sargspec polyVariadicArgs "--keyrings" args_raw @@ -943,7 +1023,7 @@ sync bExport bImport bSecret cmdarg args_raw = do , opHome = homespec } - (\f -> maybe f (const $ kiki_usage bSecret cmdarg) $ Map.lookup "--help" margs) $ do + (\f -> maybe f (const $ kiki_usage bExport bImport bSecret cmdarg) $ Map.lookup "--help" margs) $ do KikiResult rt report <- runKeyRing kikiOp case rt of @@ -1008,8 +1088,8 @@ kiki "help" [] = do return () kiki "help" args = forM_ args $ \arg -> case lookup arg commands of - Nothing | arg == "spec" -> kiki_usage False arg - Nothing | arg == "SPEC" -> kiki_usage False arg + Nothing | arg == "spec" -> kiki_usage False False False arg + Nothing | arg == "SPEC" -> kiki_usage False False False arg Nothing -> putStrLn $ "No help available for commmand '" ++ arg ++ "'." _ -> kiki arg ["--help"] @@ -1055,7 +1135,7 @@ kiki "show" args = do , opHome = homespec } - (\f -> maybe f (const $ kiki_usage False "show") $ Map.lookup "--help" margs) $ do + (\f -> maybe f (const $ kiki_usage False False False "show") $ Map.lookup "--help" margs) $ do KikiResult rt report <- runKeyRing kikiOp input_key <- maybe (return Nothing) -- cgit v1.2.3