diff --git a/README.md b/README.md index 1cf505b..8814a10 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,16 @@ -libtomcrypt -========== +# libtomcrypt See `doc/crypt.pdf` for a detailed documentation -Project Status --------------- +## Project Status -develop: [![Build Status](https://api.travis-ci.org/libtom/libtomcrypt.png?branch=develop)](https://travis-ci.org/libtom/libtomcrypt) [![Coverage Status](https://coveralls.io/repos/libtom/libtomcrypt/badge.png?branch=develop)](https://coveralls.io/r/libtom/libtomcrypt) [![Coverity Scan Build Status](https://scan.coverity.com/projects/487/badge.svg)](https://scan.coverity.com/projects/487) +master: [![Build Status](https://api.travis-ci.org/libtom/libtomcrypt.png?branch=master)](https://travis-ci.org/libtom/libtomcrypt) [![Coverage Status](https://coveralls.io/repos/libtom/libtomcrypt/badge.png?branch=master)](https://coveralls.io/r/libtom/libtomcrypt) -Submitting patches ------------------- +develop: [![Build Status](https://api.travis-ci.org/libtom/libtomcrypt.png?branch=develop)](https://travis-ci.org/libtom/libtomcrypt) [![Coverage Status](https://coveralls.io/repos/libtom/libtomcrypt/badge.png?branch=develop)](https://coveralls.io/r/libtom/libtomcrypt) + +[![Coverity Scan Build Status](https://scan.coverity.com/projects/487/badge.svg)](https://scan.coverity.com/projects/487) + +## Submitting patches Please branch off from develop if you want to submit a patch. @@ -17,10 +18,100 @@ Patch integration will be faster if tests and documentation are included. Please update the makefiles in a separate commit. To update them simply run the `updatemakes.sh` script. -Branches --------- +## Branches Please be aware, that all branches besides _master_ and _develop_ __can__ and __will be__ force-pushed, rebased and/or removed! If you want to rely on such an _unstable_ branch, create your own fork of this repository to make sure nothing breaks for you. +## Configuration options + +By default the library builds its entire feature set (besides `katja`) in a (depending on your needs more or less) optimal way. + +There are numerous configuration options available if you want to trim down the functionality of the library. + +Please have a look at `src/headers/tomcrypt_custom.h` for all available configuration options. + +The following list is a small part of the available, but the most often required, configuration switches. + +| Flag | Behavior | +| ---- | -------- | +| `LTC_NO_TEST` | Remove all algorithm self-tests from the library | +| `LTC_NO_FILE` | Remove all API functions requiring a pre-defined `FILE` data-type (mostly useful for embedded targets) | +| `MAX_RSA_SIZE` | Per default set to `4096`, if you need support for importing or generating bigger RSA keys, change this at compile-time. | +| `GMP_DESC` | enable [gmp](https://gmplib.org/) as MPI provider *\*1* | +| `LTM_DESC` | enable [libtommath](http://www.libtom.net/) as MPI provider *\*1* | +| `TFM_DESC` | enable [tomsfastmath](http://www.libtom.net/) as MPI provider *\*1* *\*2* | +| `USE_GMP` | use `gmp` as MPI provider when building the binaries *\*3* | +| `USE_LTM` | use `libtommath` as MPI provider when building the binaries *\*3* | +| `USE_TFM` | use `tomsfastmath` as MPI provider when building the binaries *\*3* | + +*\*1* It is possible to build the library against all MPI providers in parallel and choose at startup-time which math library should be used. + +*\*2* Please be aware that `tomsfastmath` has the limitation of a fixed max size of MPI's. + +*\*3* Only one is supported at the time & this is only required when building the binaries, not when building the library itself. + +## Building the library + +There are several `makefile`s provided. Please choose the one that fits best for you. + +| makefile | use-case | +| -------- | -------- | +| `makefile` | builds a static library (GNU Make required, broken on Mac OSX - use `makefile.unix` instead) | +| `makefile.shared` | builds a shared (and static) library (GNU Make required) | +| `makefile.unix` | for unusual UNIX platforms, or if you do not have GNU Make | +| `makefile.mingw` | for usage with the mingw compiler on MS Windows | +| `makefile.msvc` | for usage with the MSVC compiler on MS Windows | +| `libtomcrypt_VS2008.sln` | A VisualStudio 2008 project for MS Windows | + +### Make targets + +The `makefile`s provide several targets to build (VS project excluded). +The following list does not claim to be complete resp. to be available across all `makefile` variants. + +| target | application | +| ------ | ----------- | +| *empty target*/none given | c.f. `library` +| `library` | builds only the library | +| `hashsum` | builds the `hashsum` binary, similar to [`shasum`](https://linux.die.net/man/1/shasum), but with support for all hash-algorithms included in the library *\*4* | +| `ltcrypt` | builds the `ltcrypt` binary, implementing something similar to [`crypt`](https://linux.die.net/man/3/crypt) *\*4* | +| `sizes` | builds the `sizes` binary, printing all internal data sizes on invocation *\*4* | +| `constants` | builds the `constants` binary, printing all internal constants on invocation *\*4* | +| `openssl-enc` | builds the `openssl-enc` binary, which is more or less compatible to [`openssl enc`](https://linux.die.net/man/1/enc) *\*4* *\*5* | +| `test` | builds the `test` binary, which runs all algorithm self-tests + some extended tests *\*4* *\*6* | +| `timing` | builds the `timing` binary, which can be used to measure timings for algorithms and modes *\*4* *\*6* | +| `bins` | builds `hashsum` *\*4* | +| `all_test` | builds `test`, `hashsum`, `ltcrypt`, `small`, `tv_gen`, `sizes` & `constants` *\*4* | + +*\*4* also builds `library` + +*\*5* broken build in some configurations, therefore not built by default + +*\*6* requires define of one of `USE_GMP`, `USE_LTM` or `USE_TFM` (+ the appropriate MPI provider) + +### Examples + +You want to build the library as static library + + make + +You want to build the library as shared library + + make -f makefile.shared + +You have `libtommath` installed on your system and want to build a static library and the `test` binary to run the self-tests. + + make CFLAGS="-DUSE_LTM -DLTM_DESC" EXTRALIBS="-ltommath" test + +You have `tomsfastmath` installed on your system and want to build a shared library and all binaries + + make -f makefile.shared CFLAGS="-DUSE_TFM -DTFM_DESC" EXTRALIBS="-ltfm" all demos + +You have `gmp`, `libtommath` and `tomsfastmath` installed on your system and want to build a static library and the `timing` binary to measure timings against `gmp`. + + make CFLAGS="-DUSE_GMP -DGMP_DESC -DLTM_DESC -DTFM_DESC" EXTRALIBS="-lgmp" timing + +If you have `libtommath` in a non-standard location: + + make CFLAGS="-DUSE_LTM -DLTM_DESC -I/opt/devel/ltm" EXTRALIBS="/opt/devel/ltm/libtommath.a" all diff --git a/doc/makefile b/doc/makefile index 1222eb9..30a76c1 100644 --- a/doc/makefile +++ b/doc/makefile @@ -14,7 +14,10 @@ LEFTOVERS=*.dvi *.log *.aux *.toc *.idx *.ilg *.ind *.out *.lof doxygen: doxygen $(silent_stdout) -doxy: doxygen +patched_doxygen: + (cat Doxyfile && echo "HAVE_DOT=no") | doxygen - $(silent_stdout) + +doxy: patched_doxygen ${MAKE} -C doxygen/latex $(silent_stdout) && mv -f doxygen/latex/refman.pdf . @echo The huge doxygen PDF should be available as doc/refman.pdf diff --git a/makefile b/makefile index 827722b..1f7b201 100644 --- a/makefile +++ b/makefile @@ -17,7 +17,7 @@ PLATFORM := $(shell uname | sed -e 's/_.*//') ifneq ($(MAKECMDGOALS),clean) ifeq ($(PLATFORM), Darwin) -$(error Can't build static library on Mac, please use makefile.shared) +$(error Known to not work on Mac, please use makefile.unix for static libraries or makefile.shared for shared libraries) endif endif @@ -63,13 +63,7 @@ ifneq ($V,1) endif ${silent} $(RANLIB) $@ -timing: $(LIBNAME) $(TIMINGS) -ifneq ($V,1) - @echo " * ${CC} $@" -endif - ${silent} $(CC) $(LTC_LDFLAGS) $(TIMINGS) $(LIB_PRE) $(LIBNAME) $(LIB_POST) $(EXTRALIBS) -o $(TIMING) - -test: $(LIBNAME) $(TOBJECTS) +test: $(call print-help,test,Builds the library and the 'test' application to run all self-tests) $(LIBNAME) $(TOBJECTS) ifneq ($V,1) @echo " * ${CC} $@" endif @@ -77,7 +71,7 @@ endif # build the demos from a template define DEMO_template -$(1): demos/$(1).o $$(LIBNAME) +$(1): $(call print-help,$(1),Builds the library and the '$(1)' demo) demos/$(1).o $$(LIBNAME) ifneq ($V,1) @echo " * $${CC} $$@" endif @@ -90,11 +84,11 @@ $(foreach demo, $(strip $(DEMOS)), $(eval $(call DEMO_template,$(demo)))) #This rule installs the library and the header files. This must be run #as root in order to have a high enough permission to write to the correct #directories and to set the owner and group to root. -install: .common_install +install: $(call print-help,install,Installs the library and headers)) .common_install -install_bins: .common_install_bins +install_bins: $(call print-help,install_bins,Installs the useful demos ($(USEFUL_DEMOS))) .common_install_bins -uninstall: .common_uninstall +uninstall: $(call print-help,uninstall,Uninstalls the library and headers)) .common_uninstall profile: LTC_CFLAGS="$(LTC_CFLAGS) -fprofile-generate" $(MAKE) timing EXTRALIBS="$(EXTRALIBS) -lgcov" @@ -133,7 +127,7 @@ coverage: EXTRALIBS += -lgcov coverage: LIB_PRE = -Wl,--whole-archive coverage: LIB_POST = -Wl,--no-whole-archive -coverage: test +coverage: $(call print-help,coverage,Create code-coverage of the library - but better use coverage.sh) test ./test # cleans everything - coverage output and standard 'clean' diff --git a/makefile.shared b/makefile.shared index 95829af..a0164c0 100644 --- a/makefile.shared +++ b/makefile.shared @@ -48,33 +48,27 @@ LOBJECTS = $(OBJECTS:.o=.lo) $(LIBNAME): $(OBJECTS) $(LT) --mode=link --tag=CC $(CC) $(LTC_CFLAGS) $(CPPFLAGS) $(LTC_LDFLAGS) $(LOBJECTS) $(EXTRALIBS) -o $@ -rpath $(LIBPATH) -version-info $(VERSION_LT) -install: .common_install - sed -e 's,^prefix=.*,prefix=$(PREFIX),' -e 's,^Version:.*,Version: $(VERSION_PC),' libtomcrypt.pc.in > libtomcrypt.pc - install -d $(DESTDIR)$(LIBPATH)/pkgconfig - install -m 644 libtomcrypt.pc $(DESTDIR)$(LIBPATH)/pkgconfig/ - -install_bins: .common_install_bins - -uninstall: .common_uninstall - rm $(DESTDIR)$(LIBPATH)/pkgconfig/libtomcrypt.pc - -test: $(LIBNAME) $(TOBJECTS) +test: $(call print-help,test,Builds the library and the 'test' application to run all self-tests) $(LIBNAME) $(TOBJECTS) $(LT) --mode=link --tag=CC $(CC) $(LTC_CFLAGS) $(CPPFLAGS) $(LTC_LDFLAGS) -o $(TEST) $(TOBJECTS) $(LIBNAME) $(EXTRALIBS) -timing: $(TIMINGS) $(LIBNAME) - $(LT) --mode=link --tag=CC $(CC) $(LTC_CFLAGS) $(CPPFLAGS) $(LTC_LDFLAGS) -o $(TIMING) $^ $(EXTRALIBS) - # build the demos from a template define DEMO_template -$(1): demos/$(1).o $$(LIBNAME) -ifneq ($V,1) - @echo " * $${CC} $$@" -endif +$(1): $(call print-help,$(1),Builds the library and the '$(1)' demo) demos/$(1).o $$(LIBNAME) $$(LT) --mode=link --tag=CC $$(CC) $$(LTC_CFLAGS) $$(CPPFLAGS) $$(LTC_LDFLAGS) $$^ $$(EXTRALIBS) -o $(1) endef $(foreach demo, $(strip $(DEMOS)), $(eval $(call DEMO_template,$(demo)))) +install: $(call print-help,install,Installs the library, headers and pkd-config file)) .common_install + sed -e 's,^prefix=.*,prefix=$(PREFIX),' -e 's,^Version:.*,Version: $(VERSION_PC),' libtomcrypt.pc.in > libtomcrypt.pc + install -d $(DESTDIR)$(LIBPATH)/pkgconfig + install -m 644 libtomcrypt.pc $(DESTDIR)$(LIBPATH)/pkgconfig/ + +install_bins: $(call print-help,install_bins,Installs the useful demos ($(USEFUL_DEMOS))) .common_install_bins + +uninstall: $(call print-help,uninstall,Uninstalls the library, headers and pkd-config file)) .common_uninstall + rm $(DESTDIR)$(LIBPATH)/pkgconfig/libtomcrypt.pc + # ref: $Format:%D$ # git commit: $Format:%H$ # commit time: $Format:%ai$ diff --git a/makefile_include.mk b/makefile_include.mk index 24076d6..e2d2a33 100644 --- a/makefile_include.mk +++ b/makefile_include.mk @@ -44,6 +44,11 @@ endif endif endif +need-help := $(filter help,$(MAKECMDGOALS)) +define print-help +$(if $(need-help),$(info $1 -- $2)) +endef + # # Compilation flags. Note the += does not write over the user's CFLAGS! # @@ -124,14 +129,25 @@ DOBJECTS = $(DSOURCES:.c=.o) #List of tests headers THEADERS = $(wildcard tests/*.h) -TIMING=timing TEST=test -USEFUL_DEMOS=hashsum -UNBROKEN_DEMOS=$(USEFUL_DEMOS) ltcrypt small tv_gen sizes constants -DEMOS=$(UNBROKEN_DEMOS) openssl-enc +# Demos that are even somehow useful and could be installed as a system-tool +USEFUL_DEMOS = hashsum -TIMINGS=demos/timing.o +# Demos that are usable but only rarely make sense to be installed +USEABLE_DEMOS = ltcrypt sizes constants + +# Demos that are used for testing or measuring +TEST_DEMOS = small tv_gen + +# Demos that are in one config broken +# openssl-enc - can't be build with LTC_EASY +# timing - not really broken, but older gcc builds spit warnings +BROKEN_DEMOS = openssl-enc timing + +# Combine demos in groups +UNBROKEN_DEMOS = $(TEST_DEMOS) $(USEABLE_DEMOS) $(USEFUL_DEMOS) +DEMOS = $(UNBROKEN_DEMOS) $(BROKEN_DEMOS) #LIBPATH The directory for libtomcrypt to be installed to. #INCPATH The directory to install the header files for libtomcrypt. @@ -158,8 +174,8 @@ GROUP=wheel endif -#The default rule for make builds the libtomcrypt library. -default: library +#The first rule is also the default rule and builds the libtomcrypt library. +library: $(call print-help,library,Builds the library) $(LIBNAME) # List of objects to compile (all goes to libtomcrypt.a) @@ -346,29 +362,30 @@ src/hashes/sha2/sha256.o: src/hashes/sha2/sha256.c src/hashes/sha2/sha224.c $(DOBJECTS): LTC_CFLAGS := -Itests $(LTC_CFLAGS) $(TOBJECTS): LTC_CFLAGS := -Itests $(LTC_CFLAGS) -#This rule makes the libtomcrypt library. -library: $(LIBNAME) - #Dependencies on *.h $(OBJECTS): $(HEADERS) $(DOBJECTS): $(HEADERS) $(THEADERS) $(TOBJECTS): $(HEADERS) $(THEADERS) -bins: $(USEFUL_DEMOS) +all: $(call print-help,all,Builds the library and all demos and test utils (test $(UNBROKEN_DEMOS) $(BROKEN_DEMOS))) all_test $(BROKEN_DEMOS) -all: all_test +all_test: $(call print-help,all_test,Builds the library and all unbroken demos and test utils (test $(UNBROKEN_DEMOS))) test $(UNBROKEN_DEMOS) -all_test: test $(UNBROKEN_DEMOS) +bins: $(call print-help,bins,Builds the library and all useful demos) $(USEFUL_DEMOS) #build the doxy files (requires Doxygen, tetex and patience) -doxygen doxy docs: +doxygen: $(call print-help,doxygen,Builds the doxygen html documentation) + $(MAKE) -C doc/ $@ V=$(V) +doxy: $(call print-help,doxy,Builds the complete doxygen documentation including refman.pdf (takes long to generate)) + $(MAKE) -C doc/ $@ V=$(V) +docs: $(call print-help,docs,Builds the Developer Manual) $(MAKE) -C doc/ $@ V=$(V) -doc/crypt.pdf: +doc/crypt.pdf: $(call print-help,doc/crypt.pdf,Builds the Developer Manual) $(MAKE) -C doc/ crypt.pdf V=$(V) -install_all: install install_bins install_docs install_test +install_all: $(call print-help,install_all,Install everything - library bins docs tests) install install_bins install_docs install_test INSTALL_OPTS ?= -m 644 @@ -378,17 +395,21 @@ INSTALL_OPTS ?= -m 644 $(INSTALL_CMD) $(INSTALL_OPTS) $(LIBNAME) $(DESTDIR)$(LIBPATH)/$(LIBNAME) install -m 644 $(HEADERS) $(DESTDIR)$(INCPATH) -.common_install_bins: $(USEFUL_DEMOS) +$(DESTDIR)$(BINPATH): install -d $(DESTDIR)$(BINPATH) + +.common_install_bins: $(USEFUL_DEMOS) $(DESTDIR)$(BINPATH) $(INSTALL_CMD) -m 775 $(USEFUL_DEMOS) $(DESTDIR)$(BINPATH) -install_docs: doc/crypt.pdf +install_docs: $(call print-help,install_docs,Installs the Developer Manual) doc/crypt.pdf install -d $(DESTDIR)$(DATAPATH) install -m 644 doc/crypt.pdf $(DESTDIR)$(DATAPATH) -install_hooks: - for s in `ls hooks/`; do ln -s ../../hooks/$$s .git/hooks/$$s; done +install_test: $(call print-help,install_test,Installs the self-test binary) test $(DESTDIR)$(BINPATH) + $(INSTALL_CMD) -m 775 $< $(DESTDIR)$(BINPATH) +install_hooks: $(call print-help,install_hooks,Installs the git hooks) + for s in `ls hooks/`; do ln -s ../../hooks/$$s .git/hooks/$$s; done HEADER_FILES=$(notdir $(HEADERS)) .common_uninstall: @@ -397,7 +418,7 @@ HEADER_FILES=$(notdir $(HEADERS)) #This rule cleans the source tree of all compiled code, not including the pdf #documentation. -clean: +clean: $(call print-help,clean,Clean everything besides the pdf documentation) find . -type f -name "*.o" \ -o -name "*.lo" \ -o -name "*.a" \ @@ -419,7 +440,7 @@ clean: rm -rf `find . -type d -name "*.libs" | xargs` $(MAKE) -C doc/ clean -zipup: doc/crypt.pdf +zipup: $(call print-help,zipup,Prepare the archives for a release) doc/crypt.pdf @# Update the index, so diff-index won't fail in case the pdf has been created. @# As the pdf creation modifies crypt.tex, git sometimes detects the @# modified file, but misses that it's put back to its original version. @@ -437,6 +458,8 @@ zipup: doc/crypt.pdf gpg -b -a crypt-$(VERSION).tar.xz gpg -b -a crypt-$(VERSION).zip -codecheck: +codecheck: $(call print-help,codecheck,Check the code of the library) perl helper.pl -a perlcritic *.pl + +help: $(call print-help,help,That's what you're currently looking at)