[svn] gcry - r1308 - trunk/doc
svn author wk
cvs at cvs.gnupg.org
Wed Aug 27 15:19:28 CEST 2008
Author: wk
Date: 2008-08-27 15:19:27 +0200 (Wed, 27 Aug 2008)
New Revision: 1308
Added:
trunk/doc/fips-fsm.fig
Modified:
trunk/doc/Makefile.am
trunk/doc/gcrypt.texi
Log:
Add description of the FIPS FSM.
Modified: trunk/doc/Makefile.am
===================================================================
--- trunk/doc/Makefile.am 2008-08-27 10:10:47 UTC (rev 1307)
+++ trunk/doc/Makefile.am 2008-08-27 13:19:27 UTC (rev 1308)
@@ -18,18 +18,18 @@
# 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:
Added: trunk/doc/fips-fsm.fig
===================================================================
--- trunk/doc/fips-fsm.fig 2008-08-27 10:10:47 UTC (rev 1307)
+++ trunk/doc/fips-fsm.fig 2008-08-27 13:19:27 UTC (rev 1308)
@@ -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
Modified: trunk/doc/gcrypt.texi
===================================================================
--- trunk/doc/gcrypt.texi 2008-08-27 10:10:47 UTC (rev 1307)
+++ trunk/doc/gcrypt.texi 2008-08-27 13:19:27 UTC (rev 1308)
@@ -78,6 +78,7 @@
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 @@
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 @@
@url{http://www.gnupg.org/documentation/mailing-lists.en.html} for
details.}.
- at noindent
-Libgcrypt consists of several subsystems as shown by this diagram:
- at center @image{libgcrypt-modules, 10cm,,Module Overview}
+ at float Figure,fig:subsystems
+ at caption{Libgcrypt subsystems}
+ at center @image{libgcrypt-modules, 150mm,,Libgcrypt subsystems}
+ at 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 @@
@c ******************* Appendices *************************
@c **********************************************************
+ at c ********************************************
@node FIPS Restrictions
@appendix Restrictions in FIPS mode
@@ -4629,8 +4634,143 @@
@end itemize
+ at c ********************************************
+ at node FIPS Finite State Machine
+ at 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.
+ at float Figure,fig:fips-fsm
+ at caption{FIPS mode state diagram}
+ at center @image{fips-fsm,150mm,,FIPS FSM Diagram}
+ at end float
+
+ at float Table,tbl:fips-states
+ at caption{FIPS mode states}
+ at noindent
+States used by the FIPS FSM:
+ at table @asis
+
+ at 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.
+
+ at 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
+
+ at item Init
+The Libgcrypt initialization functions are performed and the library has
+not yet run any self-test.
+
+ at item Self-Test
+Libgcrypt is performing self-tests.
+
+ at item Operational
+Libgcrypt is in the operational state and all interfaces may be used.
+
+ at 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.
+
+ at item Fatal-Error
+Libgcrypt is in a non-recoverable error state and
+will automatically transit into the Shutdown state.
+
+ at item Shutdown
+Libgcrypt is about to be terminated and removed from the memory. The
+application may at this point still runing cleanup handlers.
+
+ at end table
+ at end float
+
+
+ at float Table,tbl:fips-state-transitions
+ at caption{FIPS mode state transitions}
+ at noindent
+The valid state transitions (@pxref{fig:fips-fsm}) are:
+ at table @code
+ at 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.
+
+ at item 2
+Power-On to Init is triggered by the application calling the
+Libgcrypt intialization function @code{gcry_check_version}.
+
+ at 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.
+
+ at item 4
+Self-Test to Operational is triggered after all self-tests passed
+successfully.
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at item 8
+Error to Shutdown is similar to the Operational to Shutdown transition
+(5).
+
+ at item 9
+Error to Fatal-Error is triggred if Libgrypt detects an fatal error
+while already being in Error state.
+
+ at item 10
+Fatal-Error to Shutdown is automatically entered by Libgcrypt
+after having reported the error.
+
+ at 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.
+
+ at item 12
+Power-On to Fatal-Error will be triggerd if certain Libgcrypt functions
+are used without having reached the Init state.
+
+ at item 13
+Self-Test to Fatal-Error is triggred by severe errors in Libgcrypt while
+running self-tests.
+
+ at item 14
+Self-Test to Error is triggred by a failed self-test.
+
+ at item 15
+Operational to Fatal-Error is triggred if Libcrypt encountered a
+non-recoverable error.
+
+ at item 16
+Operational to Self-Test is triggred if the application requested to run
+the self-tests again.
+
+ at 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.
+
+ at end table
+ at end float
+
@c **********************************************************
@c ************* Appendices (license etc.) ****************
@c **********************************************************
@@ -4638,6 +4778,13 @@
@include gpl.texi
+ at node Figures and Tables
+ at unnumbered List of Figures and Tables
+
+ at listoffloats Figure
+
+ at listoffloats Table
+
@node Concept Index
@unnumbered Concept Index
@@ -4648,6 +4795,8 @@
@printindex fn
+
+
@bye
More information about the Gnupg-commits
mailing list