/ STATUS.org
STATUS.org
1 # SPDX-FileCopyrightText: 2024-2025 Le'Sec Core collective 2 # 3 # SPDX-License-Identifier: LGPL-3.0-or-later 4 5 #+TITLE: Le'Sec Core - Development Status 6 #+LANGUAGE: en 7 8 The implementation language is mainly C, version C99 at a minimum. 9 See [[file:CODING.org][CODING.org]] for coding style information. 10 11 Development happens in spurts, and quite a few important bases pieces are 12 ready and usable. There is still a ways to go before this can be pronounced 13 fully Ready, though, so I have a readiness status on each piece, which is 14 one or more of: 15 16 - Planned :: 17 18 To be designed and implemented. So far, it is only an idea. 19 20 - Deferred :: 21 22 The component is pushed to the future, i.e. it doesn't stop the 23 encompasing component from being deemed Ready. 24 25 - Rejected :: 26 27 There was a plan, but the component was deemed unnecessary, or was 28 replaced with something else. 29 30 Items marked this way will disappear entirely in a future commit. 31 32 - Design in progress :: 33 34 A first rough design is being written, describing the ideas that are to be 35 implemented. 36 37 - Implementation in progress :: 38 39 A first implementation is in the works. 40 41 - On hold :: 42 43 A design or implementation exist, but there are serious doubts about 44 them. 45 46 - Testing in progress :: 47 48 Implementation is pretty much done, but is undergoing feasibility tests 49 50 - Ready :: 51 52 This first rough design is pretty much done, and there's a working 53 implementation. 54 55 - Documented :: 56 57 This has proper documentation 58 59 At some point, this status marker will not be necessary any more. 60 61 Ideally, all components should reach a state of Ready + Documented. 62 63 * Designs 64 65 Designs are made in the form of stories, which are maintained in a separate 66 repository, Le'Sec stories[fn:Le'Sec-stories]. 67 68 [fn:Le'Sec-stories] https://seed.le-pri.me/rad:zQ8psYPsgeSGJQrsUqXCP5oWdrPM, 69 or =rad:zQ8psYPsgeSGJQrsUqXCP5oWdrPM= on the [[https://radicle.xyz][Radicle]] network. 70 71 * Le'Sec Core (or LSCore for short) 72 73 This contains core types, code and services, that is used by all other 74 libraries and components. 75 76 ** Intended library names: 77 78 - On Unix: ~liblscore_s.a~, ~liblscore.so.{major}~ 79 - On Windows: ~liblscore_s.lib~, ~liblscore.lib+liblscore{major}.dll~ 80 - On VMS: ~LIBLSCORE_S.LIB~, ~LIBLSCORE{major}.EXE~ 81 82 ** Intended public header directory: 83 84 =${PREFIX}/include/lscore/= 85 86 ** Directories and files 87 88 - Documentation: =doc/core/= 89 - Code source: =src/core/= 90 - Public header source: =include/lscore= 91 92 ** Components 93 94 *** Data Set factory 95 96 Status: Ready 97 98 This is a foundational C type factory, implemented as macros. 99 100 *** Environment 101 102 Status: Ready 103 104 This is a generic data store, and the root of all other data that concerns 105 Le'Sec libraries. Applications must create at least one environment to be 106 able to used anything else. 107 108 *** Plugins 109 110 Status: Ready 111 112 This is functionality to start and stop plugins. The plugins can be built 113 into the applications, provided by libraries, or provided as dynamically 114 loadable modules. It's entirely up to the application to decide how to get 115 them; all this commponent does is give support to get them started an 116 stopped. 117 118 *** Parameters and Parameter Descriptors 119 120 Status: Ready 121 122 This is functionality to pass diverse parameters between applications and 123 plugins, or even between plugins. The idea is that parameters are key:value 124 tuples, defined by the "owner" of the parameter with the help of parameter 125 descriptors. The "other end" is responsible for formatting the value to be 126 passed according to that descriptor. 127 128 *** Object and Data Object factories, and Registration 129 130 Status: Ready 131 132 These are C type factories, implemented as macros, that support all sorts of 133 object classes. 134 135 Data objects are an extension of Objects, specifically made to handle a 136 payload with which diverse operations can be performed, as well as support 137 for complex data operations: 138 139 - Generator: Ready 140 141 This is an associated operation that generates an object payload, given 142 some input Parameters. 143 144 The input Parameters may be anything that can be used to generate a 145 payload, including some of the payload facts, but the main function of a 146 Generator is still to generate a whole payload internally. If the caller 147 has all the payload facts, then it's better to use the Constructor. 148 149 - Constructor: Ready 150 151 This is an associated operation that constructs an object payload, given 152 payload Parameters. 153 154 This is almost like the Generator, except that this takes input from the 155 caller to construct the payload, 156 157 - Extractor: Ready 158 159 This is an associated operation that is used to extract the object payload 160 in form of Parameters. 161 162 *** Operation factory, and Registration 163 164 Status: Ready 165 166 This is C type factory support all sorts of operation classes, implemented 167 as macros. Extended support to create operation classes with an associated 168 Object class and type is supported as well. 169 170 *** Identifiers and Properties 171 172 Status: Deferred 173 174 This is a component to support identifiers and properties for object and 175 operation implementations, to allow naming consistency. 176 177 This will affect registration of Objects and Operations. 178 179 * Le'Sec Crypto (or LSCrypto for short): 180 181 This contains diverse Object and Operation classes. 182 183 ** Intended library names: 184 185 - On Unix: ~liblscrypto_s.a~, ~liblscrypto.so.{major}~ 186 - On Windows: ~liblscrypto_s.lib~, ~liblscrypto.lib+liblscrypto{major}.dll~ 187 - On VMS: ~LIBLSCRYPTO_S.LIB~, ~LIBLSCRYPTO{major}.EXE~ 188 189 ** Intended public header directory: 190 191 =${PREFIX}/include/lscrypto/= 192 193 ** Directories and files 194 195 - Documentation: =doc/crypto/= 196 - Code source: =src/crypto/= 197 - Public header source: =include/lscrypto= 198 199 ** Components 200 201 (this is not at all complete) 202 203 *** Cryptographic operations 204 205 Status: Ready 206 207 Cryptographic operations are defined as a collection of functions that work 208 together to process some input and produce some output, given a processing 209 algorithm. 210 211 These functions support different patterns to perform the process, the exact 212 patterns depend on the class of operations. 213 214 Common functions they may or may not support: 215 216 - Use a Key :: 217 218 This is really a set of three common operation functions, for operations 219 that use an Object: 220 221 - Can a given Key be used with this operation :: 222 223 This is a simple check to see if an existing key can be used with a 224 given operation. 225 226 - Get expected key identity :: 227 228 This gives back the identity for a key that a given operation supports 229 230 - Use a given Key :: 231 232 This associates an existing key with a given operation. 233 234 - Getting operation sizes :: 235 236 Operations often have to deal with sizes, and the users need to be able to 237 find out the sizes that an operation has to deal with. A few of them are: 238 239 - Unit size :: 240 241 The unit size is the smallest "block" size that the cryptographic 242 operation supports, and may be anything from 1 and up. All inputs and 243 outputs are expected to be treated as arrays of such units internally, 244 and in some cases, the input and output sizes are expected to be exact 245 multiples of the unit size. In case the caller can't know, it's safer 246 to assume the latter. 247 248 This size is typically relevant for symmetric encryption and decryption. 249 250 - Input size :: 251 252 The input size may be undefined or zero, meaning that the input size is 253 unlimited. Otherwise, it's taken to be the exact size that the input for 254 the given operation implementation must have, and it may be assumed that 255 the operation implementation only supports the oneshot function (see the 256 description of the "Perform Operation Once" function below). 257 258 - Output size :: 259 260 The output size may be undefined or zero, meaning that the output size is 261 unlimited. Otherwise, it's taken to be the exact size for the output that 262 the operation implementation will produce. 263 264 - ... other sizes :: 265 266 While the three sizes above are the most common ones, some operations may 267 offer other sizes which are relevant to them. 268 269 - Perform Operation Once :: 270 271 This performs the operation once. 272 273 If the input size of the operation is undefined (unlimited), this function 274 is expected to accept any input size as long as it's a multiple of the 275 unit size. If the operation input size is defined, this function is 276 expected to accept that input size only. 277 278 If the output size of the operation is undefined (unlimited), this 279 function is expected to produce as much output as it got input, plus an 280 extra unit of output in some cases (typically symmetric ciphers that add 281 padding to fill the last unit). 282 283 Algorithms that expect to get the input or output lengths from the 284 beginning are expected to only implement this function, i.e. none of the 285 other Start, Stop, Perform, Accumlate, Extract, or Finalize functions 286 should be implemented. 287 For example, block ciphers in CCM mode are expected to work this way. 288 289 This is otherwise suitable for most operations, as a quick performer. 290 For some operations, such as key derivation, this is the only possible 291 function to perform the operation. 292 293 - Start and Stop Operations :: 294 295 These functions are used to start and stop an operation where multiple 296 calls to diverse processing functions are expected to be made. The Stop 297 function is expected to also work as a reset function, and therefore to be 298 possible to call without having called the Start function first. 299 300 - Perform Operation :: 301 302 This performs the operation on the given input, and may produce output in 303 response. The input may be of any size, and the output size is expected 304 to be a multiple of the unit size, and equal to or less than the input 305 size. 306 307 This is usually suitable for symmetric cipher operations. 308 309 - Accumulate Input :: 310 311 This lets the operation accumulate the given input and process it for the 312 operation's internal state. It produces no output. 313 314 This is usually suitable for any operation that only produces an output 315 once all the input has been accumulated, such as hash operations, 316 signature operations, MAC operations... 317 318 - Extract Output :: 319 320 This lets the caller extract some output from the operation, and is 321 typically used together with the Accumulate Input function. 322 323 Some algorithms allow output extraction to be interleaved with input 324 accumulation. Typically, sponge construction algorithms such as SHAKE 325 allow this. 326 327 With other algorithms, extracting output changes the state of the 328 operation so that no more input may be accumulated, thereby essentially 329 finalizing it. 330 331 This is mostly suitable for hash operations, but may become useful for 332 other operations as well. 333 334 - Finalize Operation :: 335 336 This is expected to put the operation in finalized mode, i.e. it's 337 excepted to refuse further input. 338 339 This is also expected to produce final or residual output, if there is 340 any. 341 342 This may take some final input (for example, that's expected by verifiers). 343 344 If the Perform Operation function was used and the operation's output size 345 is undefined, the total output size produced by the Perform Operation and 346 Finalize Operation calls is expected to be a multiple of units that could 347 hold the total input, plus an extra unit in the case where padding is 348 used. 349 350 This suitable for any operation that implements Start and Stop Operation, 351 but isn't mandatory. 352 Typically, implementations of algorithms that do not have an internal 353 processing state or that aren't expected to produce any final / residual 354 output would be expected to leave this function undefined. For example, 355 this could be a choice for symmetric ciphers in ECB mode. 356 357 **** Random Bit Generator (RBG) 358 359 Status: Ready 360 361 Header: ~<lscrypto/rand.h>~ 362 363 Supported common operation functions: 364 365 - Start, Stop, Extract Output 366 367 Supported special operation functions: 368 369 - Set Entropy Source :: 370 371 Sets the [[*Entropy Source][Entropy Source]] that the RBG gets to use as seed. Implementations 372 that don't implement this function are assumed to have their entropy sources 373 built in. 374 375 - Reseed :: 376 377 Reset the RBG state using the [[*Entropy Source][Entropy Source]] that was given with the Set 378 Entropy Source function. 379 380 **** Encrypt / decrypt Operations 381 382 Status: Ready 383 384 Header: ~<lscrypto/encrypt.h>~ 385 386 Supported operation functions: 387 388 - Use a Key 389 - Getting the unit, input and output sizes. 390 - Perform Operation Once 391 - Start, Stop, Perform, Finalize 392 393 **** Sign / verify Operations 394 395 Status: Ready 396 397 Header: ~<lscrypto/sign.h>~ 398 399 Supported operation functions: 400 401 - Use a Key 402 - Getting the unit, input and output sizes. 403 - Perform Operation Once 404 - Start, Stop, Accumulate, Finalize 405 406 **** Derive Operations 407 408 Status: Ready 409 410 Header: ~<lscrypto/derive.h>~ 411 412 Supported operation functions: 413 414 - Use a Key 415 - Getting the unit and output sizes. 416 - Perform Operation Once 417 418 This operation class is a bit special, because its input is the peer public 419 key, for which an input size isn't directly relevant. 420 421 **** Hash Operations 422 423 Status: Ready 424 425 Header: ~<lscrypto/digest.h>~ 426 427 Supported operation functions: 428 429 - Getting the unit and output sizes. 430 - Perform Operation Once 431 - Start, Stop, Accumulate, Extract, Finalize 432 433 These don't depend on a key. The algorithm specification may say they do, 434 but in that case, they're considered to be MAC operations (which follow). 435 436 **** MAC Operations 437 438 Status: Ready 439 440 Header: ~<lscrypto/mac.h>~ 441 442 Supported operation functions: 443 444 - Use a Key 445 - Getting the unit and output sizes. 446 - Perform Operation Once 447 - Start, Stop, Accumulate, Extract, Finalize 448 449 These are like Hash Operations, except that they depend on an associated 450 key. 451 452 **** Encapsulate / Decapsulate Operations (KEM) 453 454 Status: Ready 455 456 Header: ~<lscrypto/kem.h>~ 457 458 Supported operation functions: 459 460 - Use a Key 461 - Getting sizes: 462 - encapsulation: the shared secret and output sizes 463 - decapsulation: the input and shared secret sizes 464 - Perform Operation Once 465 466 *** Entropy Source 467 468 Status: Ready 469 470 Header: ~<lscrypto/rand.h>~ 471 472 This is a C type (not a factory) that supports entropy sources, to be used 473 with the [[*Random Bit Generator (RBG)][Random Bit Generator]]. 474 475 Supported common cryptographic operation functions: 476 477 - Start, Stop, Extract Output 478 479 Supported special operation functions: 480 481 - Add Entropy Source :: 482 483 An entropy source may be a composite of several other entropy sources. Use 484 this function to add another such entropy source. 485 486 *** Key Object 487 488 Status: Ready 489 490 Header: ~<lscrypto/key.h>~ 491 492 This is a C type (not a factory) that support symmetric as and asymmetric 493 keys. They have or will have a number of associated operations, that 494 implementations can choose to, or not, to support. This extends the set of 495 associated operations that is included in the Data Object factory: 496 497 - Data operations: 498 499 - Generator: Ready 500 - Constructor: Ready 501 - Extractor: Ready 502 503 - Basic operations: 504 505 These are diverse basic or primitive operations using the key, performed on 506 some input and generating some output. They all have the same basic 507 properties: 508 509 - They perform the most basic operation that the specification of the 510 algorithms for the key allows. This is to allow implementations of more 511 complex algorithms, or even something as simple as padding to be built 512 on top of these simple associated operations. 513 - They don't take any extra initialization Parameters. 514 515 The basic operations are: 516 517 - Encryption: Ready 518 - Decryption: Ready 519 - Signing: Ready 520 - Verifying: Ready 521 - Derivation: Ready 522 523 * Le'Sec Store (or LSStore for short): 524 525 Status: Planned 526 527 This is going to be an object store, exact organisation to be determined. 528 529 ** Intended library names: 530 531 - On Unix: ~liblsstore_s.a~, ~liblsstore.so.{major}~ 532 - On Windows: ~liblsstore_s.lib~, ~liblsstore.lib+liblsstore{major}.dll~ 533 - On VMS: ~LIBLSSTORE_S.LIB~, ~LIBLSSTORE{major}.EXE~ 534 535 ** Intended public header directory: 536 537 =${PREFIX}/include/lsstore/= 538 539 ** Directories and files 540 541 - Documentation: =doc/store/= 542 - Code source: =src/store/= 543 - Public header source: =include/lsstore= 544