diff options
author | James Crayne <jim.crayne@gmail.com> | 2015-06-24 00:02:22 -0400 |
---|---|---|
committer | James Crayne <jim.crayne@gmail.com> | 2015-06-24 00:02:22 -0400 |
commit | cdcf38baa587a7d44d200dd4fa33a5b20a8765c9 (patch) | |
tree | c148f07d558cbdb70b722b0b6adf333ac19097bb /kiki.hs | |
parent | 317fd83c64e207974a0b8a0d2943b3b49800d6bb (diff) |
Documentation update, WIP
Diffstat (limited to 'kiki.hs')
-rw-r--r-- | kiki.hs | 242 |
1 files changed, 161 insertions, 81 deletions
@@ -452,7 +452,8 @@ whoseKey rsakey db = filter matchkey (Map.elems db) | |||
452 | 452 | ||
453 | 453 | ||
454 | 454 | ||
455 | kiki_usage bSecret cmd = putStr $ | 455 | kiki_usage :: Bool -> Bool -> Bool -> String -> IO () |
456 | kiki_usage bExport bImport bSecret cmd = putStr $ | ||
456 | case cmd of | 457 | case cmd of |
457 | "show" -> unlines $ | 458 | "show" -> unlines $ |
458 | ["kiki show [options...]" | 459 | ["kiki show [options...]" |
@@ -570,46 +571,6 @@ kiki_usage bSecret cmd = putStr $ | |||
570 | ," --show-wk After the operation completes, output the possibly modified working" | 571 | ," --show-wk After the operation completes, output the possibly modified working" |
571 | ," key identity information." | 572 | ," key identity information." |
572 | ,"" | 573 | ,"" |
573 | ,"INPUT FILES" | ||
574 | ," --keypairs [KEYSPEC ...]" | ||
575 | ," KEYSPEC := tag '=' file '{' <shell command to create key file> '}'" | ||
576 | ," | tag '=' file" | ||
577 | |||
578 | ," Specify the paths of private PEM files which either currently contain" | ||
579 | ," keys to be imported, or lack keys to be exported. If your working key" | ||
580 | ," has no subkey with the given tag, and the file is empty or does not exist," | ||
581 | ," and a shell command is specified in braces, then the shell command will be " | ||
582 | ," executed in a modified environment with the expectation of creating the PEM" | ||
583 | ," file for import." | ||
584 | ,"" | ||
585 | ," Subkeys that are imported with kiki are given an annotation \"usage@\" which" | ||
586 | ," indicates what the key is for. This tag can be used as a SPEC to select a" | ||
587 | ," particular key. If a specifed PEM file contains a novel key for an existing" | ||
588 | ," tag, it will import the new key and you will have multiple keys with the same" | ||
589 | ," tag." | ||
590 | ,"" | ||
591 | ," Your OpenGPG keyring contains time stamps for each subkey. Timestamps of newly" | ||
592 | ," imported keys will reflect the mtimes of the files from which they were imported." | ||
593 | ," In the case that the key already exists in your OpenGPG keyring as well as in one" | ||
594 | ," of the specified files, the timestamp in your OpenGPG keyring is not updated." | ||
595 | ,"" | ||
596 | ," Note that this option is implicit if no options documented in this section" | ||
597 | ," were specified. See 'kiki help spec' for more information." | ||
598 | ,"" | ||
599 | ," --keyrings [FILE ...]" | ||
600 | ," These files are PGP keyring files. The format is similar to that of the" | ||
601 | ," GNU GPG state files: pubring.gpg and secring.gpg. Those files needn't be" | ||
602 | ," specified here as they are included implicitly." | ||
603 | ,"" | ||
604 | ," --wallets [FILE ...]" | ||
605 | ," Bitcoin wallet files. TODO: document format." | ||
606 | ,"" | ||
607 | ," --hosts [FILE ...]" | ||
608 | ," EXPERIMENTAL! May be removed in the future. This option specifies files" | ||
609 | ," from which to read or write hostname aliases. The format is the same as" | ||
610 | ," /etc/hosts on unix systems. WARNING: hostname aliases may be imported into" | ||
611 | ," the gpg keyring files, but they are currently NOT signed and may be altered" | ||
612 | ," in transit." | ||
613 | ] ++ syncflags | 574 | ] ++ syncflags |
614 | "sync-public" -> unlines $ | 575 | "sync-public" -> unlines $ |
615 | ["kiki sync-public [options...]" | 576 | ["kiki sync-public [options...]" |
@@ -724,42 +685,12 @@ kiki_usage bSecret cmd = putStr $ | |||
724 | ," It is considered cross certified if there exists a cross-certified" | 685 | ," It is considered cross certified if there exists a cross-certified" |
725 | ," 'tor' subkey corresponding to the address HOSTNAME.onion." | 686 | ," 'tor' subkey corresponding to the address HOSTNAME.onion." |
726 | ,"" | 687 | ,"" |
727 | ,"Merging:" | 688 | ,"SPECIFYING FILES:" |
728 | ," --keyrings FILE FILE..." | 689 | ] ++ documentKeyPairsOption bExport bImport bSecret |
729 | ," Provide keyring files other than the implicit secring.gpg and" | 690 | ++ documentKeyRingsOption bExport bImport bSecret |
730 | ," pubring.gpg in the --homedir. This option is implicit unless" | 691 | ++ documentWalletsOption bExport bImport bSecret |
731 | ," --keypairs or --wallets is used." | 692 | ++ documentHostsOption bExport bImport bSecret |
732 | ,""] | 693 | keyspec :: [String] |
733 | ++ do | ||
734 | guard bSecret | ||
735 | return $ unlines | ||
736 | [" --wallets FILE FILE..." | ||
737 | ," Provide wallet files with secret crypto-coin keys in Wallet" | ||
738 | ," Import Format. The keys will be treated as subkeys of your" | ||
739 | ," current working key (the one shown by --show-wk)." | ||
740 | ,"" | ||
741 | ," --keypairs KEYSPEC KEYSPEC..." | ||
742 | ," A keypair is a secret key coupled with it's corresponding public" | ||
743 | ," key, both of which are ordinarily stored in a single file in pem" | ||
744 | ," format. Users incognisant of the fact that the public key (which" | ||
745 | ," is also stored separately) is in this file, often think of it as" | ||
746 | ," their secret key file." | ||
747 | ,"" | ||
748 | ," Each KEYSPEC specifies that a key should match the content and" | ||
749 | ," timestamp of an external PKCS #1 private RSA key file." | ||
750 | ," " | ||
751 | ," KEYSPEC ::= SPEC=FILE{CMD} " | ||
752 | ,"" | ||
753 | ," The form of SPEC is documented elsewhere. If there is only one master" | ||
754 | ," key in your keyring and only one key is used for each purpose, then" | ||
755 | ," it is possible for SPEC in this case to merely be a tag which offers" | ||
756 | ," information about what this key is used for, for example, any of" | ||
757 | ," `tor', `ssh-client', `ssh-host', or `strongswan' will do." | ||
758 | ,"" | ||
759 | ," If neither SPEC or FILE match any keys, then the CMD will be " | ||
760 | ," executed in order to create the FILE." | ||
761 | ," (See 'kiki help spec' for more information.)" | ||
762 | ,""] | ||
763 | keyspec = -- unlines $ | 694 | keyspec = -- unlines $ |
764 | ["Specifying keys on the kiki command line:" | 695 | ["Specifying keys on the kiki command line:" |
765 | ,"" | 696 | ,"" |
@@ -797,6 +728,154 @@ kiki_usage bSecret cmd = putStr $ | |||
797 | ," 5E24CD442AA6965D2012E62A905C24185D5379C2" | 728 | ," 5E24CD442AA6965D2012E62A905C24185D5379C2" |
798 | ] | 729 | ] |
799 | 730 | ||
731 | documentKeyPairsOption :: Bool -> Bool -> Bool -> [String] | ||
732 | documentKeyPairsOption bExport bImport bSecret = | ||
733 | [" --keypairs [KEYSPEC ...]" | ||
734 | ," A keypair is a secret key coupled with it's corresponding public" | ||
735 | ," key, both of which are ordinarily stored in a single file in PEM" | ||
736 | ," format. Users incognisant of the fact that the public key (which" | ||
737 | ," is also stored separately) is in this file, often think of it as" | ||
738 | ," their secret key file." | ||
739 | ,"" | ||
740 | ] ++ case (bExport,bImport,bSecret) of | ||
741 | (True,True,True) -> -- sync-secret | ||
742 | [" This option specifies the paths of such private PEM files which" | ||
743 | ," either currently contain keys to be imported, or lack keys to" | ||
744 | ," be exported. If your working key has no subkey with the given" | ||
745 | ," tag, and the file is empty or does not exist, and a shell" | ||
746 | ," command is specified in braces, then the shell command will be" | ||
747 | ," executed in a modified environment with the expectation of" | ||
748 | ," creating the PEM file for import." | ||
749 | ,"" | ||
750 | ] ++ afterSecond | ||
751 | (True,True,False) -> -- sync-public | ||
752 | [" This option specifies the paths of PEM files, of both the" | ||
753 | ," public and private variety, which either currently contain" | ||
754 | ," public keys to be imported, or lack public keys to be exported." | ||
755 | ," If your working key has no subkey with the given tag, and the" | ||
756 | ," file is empty or does not exist, and a shell command is" | ||
757 | ," specified in braces, then the shell command will be executed in" | ||
758 | ," a modified environment with the expectation of creating the PEM" | ||
759 | ," file for import. Unlike the sync-secret command, this command" | ||
760 | ," leaves no possibility of secret key information leaking from" | ||
761 | ," your OpenGPG keyring into specified files." | ||
762 | ] ++ afterSecond | ||
763 | (False,True,True) -> -- import-secret | ||
764 | [" This option specifies the paths of such private PEM files which" | ||
765 | ," contain keys to be imported. If your working key has no subkey" | ||
766 | ," with the given tag, and the file is empty or does not exist," | ||
767 | ," and a shell command is specified in braces, then the shell" | ||
768 | ," command will be executed in a modified environment with the" | ||
769 | ," expectation of creating the PEM file for import. Files external" | ||
770 | ," to your OpenGPG keyring will not be modified by this command." | ||
771 | ] ++ afterSecond | ||
772 | (False,True,False) -> -- import-public | ||
773 | [" This option specifies the paths of PEM files, of both the" | ||
774 | ," public and private variety, which either currently contain" | ||
775 | ," contain keys to be imported. If your working key has no subkey" | ||
776 | ," with the given tag, and the file is empty or does not exist," | ||
777 | ," and a shell command is specified in braces, then the shell" | ||
778 | ," command will be executed in a modified environment with the" | ||
779 | ," expectation of creating the PEM file for import. Files external" | ||
780 | ," to your OpenGPG keyring will not be modified by this command." | ||
781 | ," Unlike the import-secret command, this command leaves no" | ||
782 | ," possibility of secret key information leaking from your OpenGPG" | ||
783 | ," keyring. " | ||
784 | ] ++ afterSecond | ||
785 | (True,False,True) -> -- export-secret | ||
786 | [" This option specifies the paths of such private PEM files, of" | ||
787 | ," both the public variety, to which kiki will export keys. These" | ||
788 | ," files will be updated with information from your OpenGPG" | ||
789 | ," keyring, but your OpenGPG keyring will not be modified by this" | ||
790 | ," command. Unlike the export-secret comamnd, this command leaves" | ||
791 | ," no possibility that secret key information will leak from your" | ||
792 | ," OpenGPG keyring." | ||
793 | ] ++ afterSecond | ||
794 | (True,False,False) -> -- export-public | ||
795 | [" This option specifies the paths of PEM files, of the private or" | ||
796 | ," public variety, which lack public keys to be exported. Unlike" | ||
797 | ," the export-secret command, this command leaves no possibility" | ||
798 | ," of secret key information leaking from your OpenGPG keyring" | ||
799 | ," into the specified files." | ||
800 | ] ++ afterSecond | ||
801 | _ -> afterSecond | ||
802 | where afterSecond = | ||
803 | [" Subkeys that are imported with kiki are given an annotation" | ||
804 | ," \"usage@\" which indicates what the key is for. This tag can" | ||
805 | ," be used as a SPEC to select a particular key. If a specifed PEM" | ||
806 | ," file contains a novel key for an existing tag, it will imported," | ||
807 | ," and you will have multiple keys with the same tag." | ||
808 | ,"" | ||
809 | ," Each KEYSPEC specifies that a key should match the content and" | ||
810 | ," timestamp of an external PKCS #1 private RSA key file." | ||
811 | ," " | ||
812 | ," KEYSPEC ::= tag '=' file" | ||
813 | ] ++ if bImport then " | tag '=' file '{' <shell command to create key file> '}'":next | ||
814 | else next | ||
815 | next = | ||
816 | ["" | ||
817 | ," Or in more complicated cases," | ||
818 | ,"" | ||
819 | ," KEYSPEC ::= SPEC '=' file" | ||
820 | ] ++ if bImport then " | SPEC '=' file '{' <shell command to create key file> '}'":next' | ||
821 | else next' | ||
822 | next' = | ||
823 | ["" | ||
824 | ," where the format of SPEC is documented in 'kiki help spec'." | ||
825 | ,"" | ||
826 | ," If there is only one master key in your keyring and only one" | ||
827 | ," key is used for each purpose, then it is possible for SPEC in" | ||
828 | ," this case to merely be a tag which offers information about" | ||
829 | ," what this key is used for, for example, any of `tor'," | ||
830 | ," `ssh-client', `ssh-host', or `strongswan' will do."] ++ next'' | ||
831 | next'' = if bImport then timeStamps ++ next''' else next''' | ||
832 | timeStamps = | ||
833 | ["" | ||
834 | ," Your OpenGPG keyring contains time stamps for each subkey." | ||
835 | ," Timestamps of newly imported keys will reflect the mtimes of" | ||
836 | ," the files from which they were imported. In the case that the" | ||
837 | ," key already exists in your OpenGPG keyring as well as in one of" | ||
838 | ," the specified files, the timestamp in your OpenGPG keyring is" | ||
839 | ," not updated."] | ||
840 | next'''= | ||
841 | ["" | ||
842 | ," Note that this option is implicit if no options documented in" | ||
843 | ," this section were specified. See 'kiki help spec' for more" | ||
844 | ," information." | ||
845 | ,"" | ||
846 | ," (See 'kiki help spec' for more information.)" | ||
847 | ] | ||
848 | |||
849 | documentKeyRingsOption :: Bool -> Bool -> Bool -> [String] | ||
850 | documentKeyRingsOption bExport bImport bSecret = | ||
851 | [" --keyrings [FILE ...]" | ||
852 | ," These files are PGP keyring files. The format is similar to" | ||
853 | ," that of the GNU GPG state files: pubring.gpg and secring.gpg." | ||
854 | ," Those files needn't be specified here as they are included" | ||
855 | ," implicitly." | ||
856 | ,"" | ||
857 | ] | ||
858 | |||
859 | documentWalletsOption :: Bool -> Bool -> Bool -> [String] | ||
860 | documentWalletsOption bExport bImport bSecret = | ||
861 | [" --wallets FILE FILE..." | ||
862 | ," Provide wallet files with secret crypto-coin keys in Wallet" | ||
863 | ," Import Format. The keys will be treated as subkeys of your" | ||
864 | ," current working key (the one shown by --show-wk)." | ||
865 | ,""] | ||
866 | |||
867 | documentHostsOption :: Bool -> Bool -> Bool -> [String] | ||
868 | documentHostsOption bExport bImport bSecret = | ||
869 | [" --hosts [FILE ...]" | ||
870 | ," EXPERIMENTAL! May be removed in the future. This option specifies files" | ||
871 | ," from which to read or write hostname aliases. The format is the same as" | ||
872 | ," /etc/hosts on unix systems. WARNING: hostname aliases may be imported into" | ||
873 | ," the gpg keyring files, but they are currently NOT signed and may be altered" | ||
874 | ," in transit." | ||
875 | ,""] | ||
876 | |||
877 | |||
878 | |||
800 | processArgs sargspec polyVariadicArgs defaultPoly args_raw = (sargs,margs) | 879 | processArgs sargspec polyVariadicArgs defaultPoly args_raw = (sargs,margs) |
801 | where | 880 | where |
802 | (args,trail1) = break (=="--") args_raw | 881 | (args,trail1) = break (=="--") args_raw |
@@ -854,6 +933,7 @@ buildStreamInfo rtyp ftyp = StreamInfo { typ = ftyp | |||
854 | , initializer = Nothing | 933 | , initializer = Nothing |
855 | , transforms = [] } | 934 | , transforms = [] } |
856 | 935 | ||
936 | |||
857 | sync :: Bool -> Bool -> Bool -> String -> [String] -> IO () | 937 | sync :: Bool -> Bool -> Bool -> String -> [String] -> IO () |
858 | sync bExport bImport bSecret cmdarg args_raw = do | 938 | sync bExport bImport bSecret cmdarg args_raw = do |
859 | let (sargs,margs) = processArgs sargspec polyVariadicArgs "--keyrings" args_raw | 939 | let (sargs,margs) = processArgs sargspec polyVariadicArgs "--keyrings" args_raw |
@@ -943,7 +1023,7 @@ sync bExport bImport bSecret cmdarg args_raw = do | |||
943 | , opHome = homespec | 1023 | , opHome = homespec |
944 | } | 1024 | } |
945 | 1025 | ||
946 | (\f -> maybe f (const $ kiki_usage bSecret cmdarg) $ Map.lookup "--help" margs) $ do | 1026 | (\f -> maybe f (const $ kiki_usage bExport bImport bSecret cmdarg) $ Map.lookup "--help" margs) $ do |
947 | KikiResult rt report <- runKeyRing kikiOp | 1027 | KikiResult rt report <- runKeyRing kikiOp |
948 | 1028 | ||
949 | case rt of | 1029 | case rt of |
@@ -1008,8 +1088,8 @@ kiki "help" [] = do | |||
1008 | return () | 1088 | return () |
1009 | 1089 | ||
1010 | kiki "help" args = forM_ args $ \arg -> case lookup arg commands of | 1090 | kiki "help" args = forM_ args $ \arg -> case lookup arg commands of |
1011 | Nothing | arg == "spec" -> kiki_usage False arg | 1091 | Nothing | arg == "spec" -> kiki_usage False False False arg |
1012 | Nothing | arg == "SPEC" -> kiki_usage False arg | 1092 | Nothing | arg == "SPEC" -> kiki_usage False False False arg |
1013 | Nothing -> putStrLn $ "No help available for commmand '" ++ arg ++ "'." | 1093 | Nothing -> putStrLn $ "No help available for commmand '" ++ arg ++ "'." |
1014 | _ -> kiki arg ["--help"] | 1094 | _ -> kiki arg ["--help"] |
1015 | 1095 | ||
@@ -1055,7 +1135,7 @@ kiki "show" args = do | |||
1055 | , opHome = homespec | 1135 | , opHome = homespec |
1056 | } | 1136 | } |
1057 | 1137 | ||
1058 | (\f -> maybe f (const $ kiki_usage False "show") $ Map.lookup "--help" margs) $ do | 1138 | (\f -> maybe f (const $ kiki_usage False False False "show") $ Map.lookup "--help" margs) $ do |
1059 | KikiResult rt report <- runKeyRing kikiOp | 1139 | KikiResult rt report <- runKeyRing kikiOp |
1060 | 1140 | ||
1061 | input_key <- maybe (return Nothing) | 1141 | input_key <- maybe (return Nothing) |