| userspace-if.rst (0ea8a56de21be24cb79abb03dee79aabcd60a316) | userspace-if.rst (77ebdabe8de7c02f43c6de3357f79ff96f9f0579) |
|---|---|
| 1User Space Interface 2==================== 3 4Introduction 5------------ 6 7The concepts of the kernel crypto API visible to kernel space is fully 8applicable to the user space interface as well. Therefore, the kernel --- 282 unchanged lines hidden (view full) --- 291Again, the operation is very similar to the other APIs. During 292initialization, the struct sockaddr data structure must be filled as 293follows: 294 295:: 296 297 struct sockaddr_alg sa = { 298 .salg_family = AF_ALG, | 1User Space Interface 2==================== 3 4Introduction 5------------ 6 7The concepts of the kernel crypto API visible to kernel space is fully 8applicable to the user space interface as well. Therefore, the kernel --- 282 unchanged lines hidden (view full) --- 291Again, the operation is very similar to the other APIs. During 292initialization, the struct sockaddr data structure must be filled as 293follows: 294 295:: 296 297 struct sockaddr_alg sa = { 298 .salg_family = AF_ALG, |
| 299 .salg_type = "rng", /* this selects the symmetric cipher */ 300 .salg_name = "drbg_nopr_sha256" /* this is the cipher name */ | 299 .salg_type = "rng", /* this selects the random number generator */ 300 .salg_name = "drbg_nopr_sha256" /* this is the RNG name */ |
| 301 }; 302 303 304Depending on the RNG type, the RNG must be seeded. The seed is provided 305using the setsockopt interface to set the key. For example, the 306ansi_cprng requires a seed. The DRBGs do not require a seed, but may be | 301 }; 302 303 304Depending on the RNG type, the RNG must be seeded. The seed is provided 305using the setsockopt interface to set the key. For example, the 306ansi_cprng requires a seed. The DRBGs do not require a seed, but may be |
| 307seeded. | 307seeded. The seed is also known as a *Personalization String* in NIST SP 800-90A 308standard. |
| 308 309Using the read()/recvmsg() system calls, random numbers can be obtained. 310The kernel generates at most 128 bytes in one call. If user space 311requires more data, multiple calls to read()/recvmsg() must be made. 312 313WARNING: The user space caller may invoke the initially mentioned accept 314system call multiple times. In this case, the returned file descriptors 315have the same state. 316 | 309 310Using the read()/recvmsg() system calls, random numbers can be obtained. 311The kernel generates at most 128 bytes in one call. If user space 312requires more data, multiple calls to read()/recvmsg() must be made. 313 314WARNING: The user space caller may invoke the initially mentioned accept 315system call multiple times. In this case, the returned file descriptors 316have the same state. 317 |
| 318Following CAVP testing interfaces are enabled when kernel is built with 319CRYPTO_USER_API_RNG_CAVP option: 320 321- the concatenation of *Entropy* and *Nonce* can be provided to the RNG via 322 ALG_SET_DRBG_ENTROPY setsockopt interface. Setting the entropy requires 323 CAP_SYS_ADMIN permission. 324 325- *Additional Data* can be provided using the send()/sendmsg() system calls, 326 but only after the entropy has been set. 327 |
|
| 317Zero-Copy Interface 318------------------- 319 320In addition to the send/write/read/recv system call family, the AF_ALG 321interface can be accessed with the zero-copy interface of 322splice/vmsplice. As the name indicates, the kernel tries to avoid a copy 323operation into kernel space. 324 --- 47 unchanged lines hidden (view full) --- 372 - the RNG cipher type to provide the seed 373 374- ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size for 375 AEAD ciphers. For a encryption operation, the authentication tag of 376 the given size will be generated. For a decryption operation, the 377 provided ciphertext is assumed to contain an authentication tag of 378 the given size (see section about AEAD memory layout below). 379 | 328Zero-Copy Interface 329------------------- 330 331In addition to the send/write/read/recv system call family, the AF_ALG 332interface can be accessed with the zero-copy interface of 333splice/vmsplice. As the name indicates, the kernel tries to avoid a copy 334operation into kernel space. 335 --- 47 unchanged lines hidden (view full) --- 383 - the RNG cipher type to provide the seed 384 385- ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size for 386 AEAD ciphers. For a encryption operation, the authentication tag of 387 the given size will be generated. For a decryption operation, the 388 provided ciphertext is assumed to contain an authentication tag of 389 the given size (see section about AEAD memory layout below). 390 |
| 391- ALG_SET_DRBG_ENTROPY -- Setting the entropy of the random number generator. 392 This option is applicable to RNG cipher type only. 393 |
|
| 380User space API example 381---------------------- 382 383Please see [1] for libkcapi which provides an easy-to-use wrapper around 384the aforementioned Netlink kernel interface. [1] also contains a test 385application that invokes all libkcapi API calls. 386 387[1] https://www.chronox.de/libkcapi.html | 394User space API example 395---------------------- 396 397Please see [1] for libkcapi which provides an easy-to-use wrapper around 398the aforementioned Netlink kernel interface. [1] also contains a test 399application that invokes all libkcapi API calls. 400 401[1] https://www.chronox.de/libkcapi.html |