Add description of the FIPS FSM.
authorWerner Koch <wk@gnupg.org>
Wed, 27 Aug 2008 13:19:27 +0000 (13:19 +0000)
committerWerner Koch <wk@gnupg.org>
Wed, 27 Aug 2008 13:19:27 +0000 (13:19 +0000)
doc/Makefile.am
doc/fips-fsm.fig [new file with mode: 0644]
doc/gcrypt.texi

index d715e63..5d356a0 100644 (file)
 # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
 
 EXTRA_DIST = README.apichanges HACKING \
-            libgcrypt-modules.eps \
-            libgcrypt-modules.png \
-             libgcrypt-modules.pdf
+            libgcrypt-modules.eps fips-fsm.eps \
+            libgcrypt-modules.png fips-fsm.png \
+             libgcrypt-modules.pdf fips-fsm.pdf 
 
 DISTCLEANFILES = gcrypt.cps
 
-BUILT_SOURCES = libgcrypt-modules.eps \
-                libgcrypt-modules.png \
-                libgcrypt-modules.pdf
+BUILT_SOURCES = libgcrypt-modules.eps fips-fsm.eps \
+                libgcrypt-modules.png fips-fsm.png \
+                libgcrypt-modules.pdf fips-fsm.pdf
 
 info_TEXINFOS = gcrypt.texi
-gcrypt_TEXINFOS = lgpl.texi gpl.texi libgcrypt-modules.fig
+gcrypt_TEXINFOS = lgpl.texi gpl.texi libgcrypt-modules.fig fips-fsm.fig
 
 
 .fig.png:
diff --git a/doc/fips-fsm.fig b/doc/fips-fsm.fig
new file mode 100644 (file)
index 0000000..a916a5c
--- /dev/null
@@ -0,0 +1,182 @@
+#FIG 3.2  Produced by xfig version 3.2.5-alpha5
+Portrait
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+0 32 #9c0000
+0 33 #8c8c8c
+0 34 #8c8c8c
+0 35 #424242
+0 36 #8c8c8c
+0 37 #424242
+0 38 #8c8c8c
+0 39 #424242
+0 40 #8c8c8c
+0 41 #424242
+0 42 #8c8c8c
+0 43 #424242
+6 900 270 8775 9450
+6 900 270 8775 9450
+5 1 0 2 0 7 50 -1 -1 0.000 1 1 1 0 4837.500 16740.000 6750 6705 4725 6525 2925 6705
+       1 1 2.00 120.00 240.00
+5 1 0 2 0 7 50 -1 -1 0.000 1 1 1 0 3026.138 8399.825 4185 8370 3870 7605 2925 7245
+       1 1 2.00 120.00 240.00
+6 3600 8370 5985 9450
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+        5970 9450 3600 9450 3600 8370 5970 8370 5970 9450
+4 0 0 50 -1 0 24 0.0000 4 360 1965 3870 9000 Operational\001
+-6
+6 900 4320 2970 5445
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+        2940 5445 915 5445 915 4335 2940 4335 2940 5445
+4 0 0 50 -1 0 24 0.0000 4 270 585 1620 4995 Init\001
+-6
+6 900 6345 2970 7470
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+        2955 7455 930 7455 930 6345 2955 6345 2955 7455
+4 0 0 50 -1 0 24 0.0000 4 270 1515 1215 7020 Self-Test\001
+-6
+6 6750 6345 8775 7470
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+        8775 7470 6750 7470 6750 6360 8775 6360 8775 7470
+4 0 0 50 -1 0 24 0.0000 4 270 870 7335 7020 Error\001
+-6
+6 3825 4320 5850 5445
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+        5850 5445 3825 5445 3825 4335 5850 4335 5850 5445
+4 0 0 50 -1 0 24 0.0000 4 270 1830 3915 4995 Fatal-Error\001
+-6
+6 6750 2295 8775 3420
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+        8775 3420 6750 3420 6750 2310 8775 2310 8775 3420
+4 0 0 50 -1 0 24 0.0000 4 270 1695 6930 2970 Shutdown\001
+-6
+6 2475 2295 4500 3420
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+        4500 3405 2475 3405 2475 2295 4500 2295 4500 3405
+4 0 0 50 -1 0 24 0.0000 4 270 1695 2655 2970 Power-On\001
+-6
+6 2475 270 4500 1395
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+        4500 1395 2475 1395 2475 285 4500 285 4500 1395
+4 0 0 50 -1 0 24 0.0000 4 270 1755 2565 945 Power-Off\001
+-6
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        3420 1395 3420 2295
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        3465 3420 4815 4320
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        1890 5445 1890 6345
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        2835 7380 3735 8415
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        4725 8370 4725 5490
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        4950 8370 7335 3420
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        2925 6930 6750 6930
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        2880 6480 3915 5355
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        4500 2835 6750 2835
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        7740 6345 7740 3420
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        3375 3420 1890 4320
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        5760 4410 6840 3330
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        7740 2295 4500 855
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        6840 6435 5760 5355
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+       1 1 2.00 120.00 240.00
+        5895 8460 6840 7380
+-6
+6 3096 1593 3380 1877
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 3238 1735 142 142 3238 1735 3103 1690
+4 0 0 50 -1 13 12 0.0000 4 105 120 3157 1805 1\001
+-6
+6 2266 3607 2550 3891
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 2408 3749 142 142 2408 3749 2273 3704
+4 0 0 50 -1 13 12 0.0000 4 105 120 2327 3819 2\001
+-6
+6 1566 5667 1850 5951
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 1708 5809 142 142 1708 5809 1573 5764
+4 0 0 50 -1 13 12 0.0000 4 105 120 1627 5879 3\001
+-6
+6 5706 1543 5990 1827
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 5848 1685 142 142 5848 1685 5713 1640
+4 0 0 50 -1 13 12 0.0000 4 105 120 5767 1755 6\001
+-6
+6 5986 7757 6270 8041
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 6128 7899 142 142 6128 7899 5993 7854
+4 0 0 50 -1 13 12 0.0000 4 105 120 6047 7969 7\001
+-6
+6 7426 4747 7710 5031
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 7568 4889 142 142 7568 4889 7433 4844
+4 0 0 50 -1 13 12 0.0000 4 105 120 7487 4959 8\001
+-6
+6 5866 3737 6150 4021
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 6008 3879 142 142 6008 3879 5873 3834
+4 0 0 50 -1 13 12 0.0000 4 105 240 5882 3940 10\001
+-6
+6 5276 2517 5560 2801
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 5418 2659 142 142 5418 2659 5283 2614
+4 0 0 50 -1 13 12 0.0000 4 105 240 5292 2720 11\001
+-6
+6 4126 3573 4410 3857
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 4268 3715 142 142 4268 3715 4133 3670
+4 0 0 50 -1 13 12 0.0000 4 105 240 4142 3776 12\001
+-6
+6 3066 5723 3350 6007
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 3208 5865 142 142 3208 5865 3073 5820
+4 0 0 50 -1 13 12 0.0000 4 105 240 3082 5926 13\001
+-6
+6 4036 6623 4320 6907
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 4178 6765 142 142 4178 6765 4043 6720
+4 0 0 50 -1 13 12 0.0000 4 105 240 4052 6826 14\001
+-6
+6 4416 7213 4700 7497
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 4558 7355 142 142 4558 7355 4423 7310
+4 0 0 50 -1 13 12 0.0000 4 105 240 4432 7416 15\001
+-6
+6 5066 7223 5350 7507
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 5208 7365 142 142 5208 7365 5073 7320
+4 0 0 50 -1 13 12 0.0000 4 105 120 5127 7435 5\001
+-6
+6 3566 7573 3850 7857
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 3708 7715 142 142 3708 7715 3573 7670
+4 0 0 50 -1 13 12 0.0000 4 105 240 3582 7776 16\001
+-6
+6 4996 6193 5280 6477
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 5138 6335 142 142 5138 6335 5003 6290
+4 0 0 50 -1 13 12 0.0000 4 105 240 5012 6396 17\001
+-6
+6 2896 7783 3180 8067
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 3038 7925 142 142 3038 7925 2903 7880
+4 0 0 50 -1 13 12 0.0000 4 105 120 2957 7995 4\001
+-6
+6 6426 5753 6710 6037
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 6568 5895 142 142 6568 5895 6433 5850
+4 0 0 50 -1 13 12 0.0000 4 105 120 6487 5965 9\001
+-6
+-6
index ab1a704..11cb51e 100644 (file)
@@ -78,6 +78,7 @@ section entitled ``Copying''.
 Appendices
 
 * FIPS Restrictions::           Restrictions in FIPS mode.
+* FIPS Finite State Machine::   Description of the FIPS FSM.
 * Library Copying::             The GNU Lesser General Public License
                                 says how you can copy and share Libgcrypt.
 * Copying::                     The GNU General Public License says how you
@@ -85,6 +86,7 @@ Appendices
 
 Indices
 
+* Figures and Tables::          Index of figures and tables.
 * Concept Index::               Index of concepts and programs.
 * Function and Data Index::     Index of functions, variables and data types.
 
@@ -4520,17 +4522,19 @@ Announcements of new releases are posted to the
 @url{http://www.gnupg.org/documentation/mailing-lists.en.html} for
 details.}.
 
-@noindent
-Libgcrypt consists of several subsystems as shown by this diagram:
 
-@center @image{libgcrypt-modules, 10cm,,Module Overview}
+@float Figure,fig:subsystems
+@caption{Libgcrypt subsystems}
+@center @image{libgcrypt-modules, 150mm,,Libgcrypt subsystems}
+@end float
 
-All of these subsystems provide a public API including the helper
-systesm like S-expression.  The API style depends on the subsystem; in
-general an open, use, close approach is implemented.  The open returns a
-handle to a context used for all futher operations on this handle,
-several functions may then be used on this handle and a final close
-function releases all resources associated with the handle.
+Libgcrypt consists of several subsystems (@pxref{fig:subsystems}) and
+all these subsystems provide a public API; this includes the helper
+subsystems like the one for S-expression.  The API style depends on the
+subsystem; in general an open, use, close approach is implemented.  The
+open returns a handle to a context used for all futher operations on
+this handle, several functions may then be used on this handle and a
+final close function releases all resources associated with the handle.
 
 @menu
 * Public-Key Subsystem Architecture::              All about public keys.
@@ -4613,6 +4617,7 @@ TBD.
 @c *******************  Appendices  *************************
 @c **********************************************************
 
+@c ********************************************
 @node FIPS Restrictions
 @appendix Restrictions in FIPS mode
 
@@ -4629,7 +4634,142 @@ into FIPS mode on other systems will fail at runtime.
 @end itemize
 
 
+@c ********************************************
+@node FIPS Finite State Machine
+@appendix FIPS Finite State Machine
+
+The FIPS mode of libgcrypt implements a finite state machine (FSM) using
+8 states (@pxref{tbl:fips-states}) and checks at runtime that only valid
+transitions (@pxref{tbl:fips-state-transitions}) may happen.
+
+@float Figure,fig:fips-fsm
+@caption{FIPS mode state diagram}
+@center @image{fips-fsm,150mm,,FIPS FSM Diagram}
+@end float
+
+@float Table,tbl:fips-states
+@caption{FIPS mode states}
+@noindent
+States used by the FIPS FSM:
+@table @asis
+
+@item Power-Off 
+Libgcrypt is not runtime linked to another application.  This usually
+means that the library is not loaded into main memory.  This state is
+documentation only.
+
+@item Power-On
+Libgcrypt is loaded into memory and API calls may be made.  Compiler
+introducted constructor functions may be run.  Note that Libgcrypt does
+not implement any arbitrary constructor functions to be called by the
+operating system
+
+@item Init
+The Libgcrypt initialization functions are performed and the library has
+not yet run any self-test.
+
+@item Self-Test
+Libgcrypt is performing self-tests.               
+
+@item Operational
+Libgcrypt is in the operational state and all interfaces may be used.
+
+@item Error
+Libgrypt is in the error state.  When calling any FIPS relevant
+interfaces they either return an error (@code{GPG_ERR_NOT_OPERATIONAL})
+or put Libgcrypt into the Fatal-Error state and won't return.  
+
+@item Fatal-Error
+Libgcrypt is in a non-recoverable error state and 
+will automatically transit into the  Shutdown state.        
+
+@item Shutdown
+Libgcrypt is about to be terminated and removed from the memory. The
+application may at this point still runing cleanup handlers.
+
+@end table
+@end float
+
+
+@float Table,tbl:fips-state-transitions
+@caption{FIPS mode state transitions}
+@noindent
+The valid state transitions (@pxref{fig:fips-fsm}) are:
+@table @code
+@item 1 
+Power-Off to Power-On is implicitly done by the OS loading Libgcrypt as
+a shared library and having it linked to an application.
+
+@item 2
+Power-On to Init is triggered by the application calling the
+Libgcrypt intialization function @code{gcry_check_version}.
 
+@item 3
+Init to Self-Test is either triggred by a dedicated API call or implicit
+by invoking a libgrypt service conrolled by the FSM.
+
+@item 4 
+Self-Test to Operational is triggered after all self-tests passed
+successfully.  
+
+@item 5
+Operational to Shutdown is an artifical state without any direct action
+in Libgcrypt.  When reaching the Shutdown state the library is
+deinitialized and can't return to any other state again.
+
+@item 6
+Shutdown to Power-off is the process of removing Libgcrypt from the
+computer's memory.  For obvious reasons the Power-Off state can't be
+represented within Libgcrypt and thus this transition is for
+documentation only.
+
+@item 7
+Operational to Error is triggered if Libgcrypt detected an application
+error which can't be returned to the caller but still allows Libgcrypt
+to properly run.  In the Error state all FIPS relevant interfaces return
+an error code.
+
+@item 8
+Error to Shutdown is similar to the Operational to Shutdown transition
+(5).
+
+@item 9
+Error to Fatal-Error is triggred if Libgrypt detects an fatal error
+while already being in Error state.
+
+@item 10
+Fatal-Error to Shutdown is automatically entered by Libgcrypt 
+after having reported the error.
+
+@item 11
+Power-On to Shutdown is an artifical state to document that Libgcrypt
+has not ye been initializaed but the process is about to terminate.
+
+@item 12
+Power-On to Fatal-Error will be triggerd if certain Libgcrypt functions
+are used without having reached the Init state.
+
+@item 13
+Self-Test to Fatal-Error is triggred by severe errors in Libgcrypt while
+running self-tests.
+
+@item 14
+Self-Test to Error is triggred by a failed self-test.
+
+@item 15
+Operational to Fatal-Error is triggred if Libcrypt encountered a
+non-recoverable error.
+
+@item 16
+Operational to Self-Test is triggred if the application requested to run
+the self-tests again.
+
+@item 17
+Error to Self-Test is triggered if the application has requested to run
+self-tests to get to get back into operational state after an error.
+
+@end table
+@end float
 
 @c **********************************************************
 @c *************  Appendices (license etc.)  ****************
@@ -4638,6 +4778,13 @@ into FIPS mode on other systems will fail at runtime.
 
 @include gpl.texi
 
+@node Figures and Tables
+@unnumbered List of Figures and Tables
+
+@listoffloats Figure
+
+@listoffloats Table
+
 @node Concept Index
 @unnumbered Concept Index
 
@@ -4648,6 +4795,8 @@ into FIPS mode on other systems will fail at runtime.
 
 @printindex fn
 
+
+
 @bye