| 1 |
|
| 2 |
libcanlock |
| 3 |
========== |
| 4 |
A library for creating and verifying RFC 8315 Netnews Cancel-Locks. |
| 5 |
This implementation uses the recommended algorithm from Section 4 with HMAC |
| 6 |
based on the same hash function as <scheme>. |
| 7 |
|
| 8 |
The subdirectory "examples" contains programs with demonstration code. |
| 9 |
|
| 10 |
|
| 11 |
1) General |
| 12 |
libcanlock is a standalone implementation without external dependencies. |
| 13 |
|
| 14 |
|
| 15 |
2) System requirements |
| 16 |
- POSIX.1-2001 compliant operating system |
| 17 |
- C99 compiler with 'int' data type of at least 32 bit width |
| 18 |
|
| 19 |
Note: |
| 20 |
A POSIX style operating system is required only for the build system, the test |
| 21 |
suite and the header parsers (see "canlock-hp" section below). |
| 22 |
The code of the library and canlock utility is intended to be portable C99 (with |
| 23 |
the exception that 16 bit platforms are not supported). |
| 24 |
|
| 25 |
For reliable overwriting of secret data in memory, libcanlock needs explicit |
| 26 |
memory access. The following functions are currently supported (automatically |
| 27 |
detected by configure script, if available): |
| 28 |
- memset_s() [available as option in C11 Annex K] |
| 29 |
- explicit_memset() [available e.g. since NetBSD 7] |
| 30 |
- explicit_bzero() [available e.g. since GNU libc 2.25] |
| 31 |
If none of them can be used, memset() is used as fallback. But a "too smart" |
| 32 |
compiler may optimize this call to NOP. |
| 33 |
|
| 34 |
|
| 35 |
3) API |
| 36 |
Since version 3 there is a new API available (hash algorithm independent). |
| 37 |
Man pages for this API are installed together with the library. |
| 38 |
|
| 39 |
Anything that is not documented should be considered as internal and not |
| 40 |
part of the API. There is no portable way to hide all the internal stuff |
| 41 |
completely, but expect that a future version may no longer export it without |
| 42 |
notice. |
| 43 |
|
| 44 |
|
| 45 |
4) Backward compatibility |
| 46 |
The version 2 legacy API is still present by default, but it is now deprecated |
| 47 |
and undocumented. |
| 48 |
Including the header file from the new location, recompile and relink should |
| 49 |
be sufficient to port an existing application to version 3 of the library. |
| 50 |
|
| 51 |
The version 2 legacy API can be removed from the library with the configure |
| 52 |
option "--disable-legacy-api". |
| 53 |
|
| 54 |
Note: It is possible to install both, version 2 and version 3 of the library in |
| 55 |
parallel. |
| 56 |
|
| 57 |
|
| 58 |
5) Versioning scheme |
| 59 |
With version 3 the release version scheme has changed. |
| 60 |
Now the release version contains 3 numbers "x.y.z": |
| 61 |
|
| 62 |
- Major (x) |
| 63 |
The major number is incremented for every API/ABI change that is not backward |
| 64 |
compatible. |
| 65 |
- Minor (y) |
| 66 |
The minor number is incremented for API/ABI extensions that are backward |
| 67 |
compatible. |
| 68 |
- Patch (z) |
| 69 |
The patch number is incremented for changes that don't change the API/ABI. |
| 70 |
|
| 71 |
In other words: |
| 72 |
Releases with the same major and minor numbers are drop-in replacements. |
| 73 |
Up- and downgrades between such versions are possible without touching |
| 74 |
programs that use the library. |
| 75 |
Releases with the same major, but different minor numbers are backward, |
| 76 |
but not forward compatible. Upgrades are possible, downgrades can break |
| 77 |
programs that use the library. |
| 78 |
Releases with different major numbers require changes in all programs that |
| 79 |
use the library. |
| 80 |
|
| 81 |
Note: Compatibility is not guaranteed if different configure options are used! |
| 82 |
|
| 83 |
|
| 84 |
6) pkg-config |
| 85 |
Since version 3.2.0 pkg-config is supported with the configure option |
| 86 |
"--enable-pc-files". With this option the data file "libcanlock-3.pc" is |
| 87 |
installed. |
| 88 |
|
| 89 |
The configure option "--with-pkgconfigdir" can be used to install this file |
| 90 |
into a nonstandard location. |
| 91 |
|
| 92 |
|
| 93 |
canlock |
| 94 |
======= |
| 95 |
Since version 3 the command line utility "canlock" is available as frontend. |
| 96 |
The utility and a man page for it are installed together with the library. |
| 97 |
|
| 98 |
|
| 99 |
canlock-hp |
| 100 |
========== |
| 101 |
The header parsers from the formerly separate package canlock-hp were merged |
| 102 |
into version 3.1.0 (see the README file in the "hp" subdirectory). |
| 103 |
|
| 104 |
Since version 3.3.0 the library libcanlock-hp provides a C-API to the header |
| 105 |
parsers for POSIX operating systems. |
| 106 |
|
| 107 |
canlock-hp can be disabled with the configure option "--disable-hp". |
| 108 |
|
| 109 |
|
| 110 |
EOF |