TeaSpeak/tomcrypt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

update readme

Browse Source 
[skip ci]
This commit is contained in:
Steffen Jaeckel 2017-07-13 14:30:16 +02:00
parent bfe6c4d35c
commit 4cb8936a31
1 changed files with 92 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
README.md
View File

@ -1,15 +1,16 @@
libtomcrypt # libtomcrypt
==========
See `doc/crypt.pdf` for a detailed documentation 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. Please branch off from develop if you want to submit a patch.
@ -17,28 +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. 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! 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. If you want to rely on such an _unstable_ branch, create your own fork of this repository to make sure nothing breaks for you.
Building ## Configuration options
--------
If you have `libtommath` installed on your system: By default the library builds its entire feature set (besides `katja`) in a (depending on your needs more or less) optimal way.
make CFLAGS="-DUSE_LTM -DLTM_DESC" EXTRALIBS="-ltommath" all There are numerous configuration options available if you want to trim down the functionality of the library.
For building a shared library use: Please have a look at `src/headers/tomcrypt_custom.h` for all available configuration options.
make -f makefile.shared CFLAGS="-DUSE_LTM -DLTM_DESC" EXTRALIBS="-ltommath" all 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) |
| `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: 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 make CFLAGS="-DUSE_LTM -DLTM_DESC -I/opt/devel/ltm" EXTRALIBS="/opt/devel/ltm/libtommath.a" all
On unusual UNIX platforms, or if you do not have GNU make, have a look at `makefile.unix`.
On MS Windows try `libtomcrypt_VS2008.sln` (Visual Studio) or `makefile.mingw` or `makefile.msvc`.