Debian Codegraph @

README

raw
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