From 253e67c8b3a72b3a4757fdbc5845297628db0a4a Mon Sep 17 00:00:00 2001 From: Jacob McDonnell Date: Sat, 25 Apr 2026 19:55:15 -0400 Subject: docs: Added All NetBSD Manuals --- static/netbsd/man7/EVP_ASYM_CIPHER-RSA.7 | 171 + static/netbsd/man7/EVP_ASYM_CIPHER-SM2.7 | 97 + static/netbsd/man7/EVP_CIPHER-AES.7 | 141 + static/netbsd/man7/EVP_CIPHER-ARIA.7 | 108 + static/netbsd/man7/EVP_CIPHER-BLOWFISH.7 | 100 + static/netbsd/man7/EVP_CIPHER-CAMELLIA.7 | 104 + static/netbsd/man7/EVP_CIPHER-CAST.7 | 100 + static/netbsd/man7/EVP_CIPHER-CHACHA.7 | 96 + static/netbsd/man7/EVP_CIPHER-DES.7 | 129 + static/netbsd/man7/EVP_CIPHER-IDEA.7 | 100 + static/netbsd/man7/EVP_CIPHER-NULL.7 | 121 + static/netbsd/man7/EVP_CIPHER-RC2.7 | 104 + static/netbsd/man7/EVP_CIPHER-RC4.7 | 98 + static/netbsd/man7/EVP_CIPHER-RC5.7 | 102 + static/netbsd/man7/EVP_CIPHER-SEED.7 | 100 + static/netbsd/man7/EVP_CIPHER-SM4.7 | 116 + static/netbsd/man7/EVP_KDF-ARGON2.7 | 241 ++ static/netbsd/man7/EVP_KDF-HKDF.7 | 223 ++ static/netbsd/man7/EVP_KDF-HMAC-DRBG.7 | 122 + static/netbsd/man7/EVP_KDF-KB.7 | 250 ++ static/netbsd/man7/EVP_KDF-KRB5KDF.7 | 167 + static/netbsd/man7/EVP_KDF-PBKDF1.7 | 137 + static/netbsd/man7/EVP_KDF-PBKDF2.7 | 167 + static/netbsd/man7/EVP_KDF-PKCS12KDF.7 | 140 + static/netbsd/man7/EVP_KDF-PVKKDF.7 | 123 + static/netbsd/man7/EVP_KDF-SCRYPT.7 | 204 ++ static/netbsd/man7/EVP_KDF-SS.7 | 260 ++ static/netbsd/man7/EVP_KDF-SSHKDF.7 | 236 ++ static/netbsd/man7/EVP_KDF-TLS13_KDF.7 | 208 ++ static/netbsd/man7/EVP_KDF-TLS1_PRF.7 | 202 ++ static/netbsd/man7/EVP_KDF-X942-ASN1.7 | 214 ++ static/netbsd/man7/EVP_KDF-X942-CONCAT.7 | 93 + static/netbsd/man7/EVP_KDF-X963.7 | 190 ++ static/netbsd/man7/EVP_KEM-EC.7 | 133 + static/netbsd/man7/EVP_KEM-ML-KEM.7 | 113 + static/netbsd/man7/EVP_KEM-RSA.7 | 127 + static/netbsd/man7/EVP_KEM-X25519.7 | 132 + static/netbsd/man7/EVP_KEYEXCH-DH.7 | 194 ++ static/netbsd/man7/EVP_KEYEXCH-ECDH.7 | 186 ++ static/netbsd/man7/EVP_KEYEXCH-X25519.7 | 110 + static/netbsd/man7/EVP_MAC-BLAKE2.7 | 136 + static/netbsd/man7/EVP_MAC-CMAC.7 | 141 + static/netbsd/man7/EVP_MAC-GMAC.7 | 123 + static/netbsd/man7/EVP_MAC-HMAC.7 | 144 + static/netbsd/man7/EVP_MAC-KMAC.7 | 213 ++ static/netbsd/man7/EVP_MAC-Poly1305.7 | 115 + static/netbsd/man7/EVP_MAC-Siphash.7 | 112 + static/netbsd/man7/EVP_MD-BLAKE2.7 | 123 + static/netbsd/man7/EVP_MD-KECCAK.7 | 101 + static/netbsd/man7/EVP_MD-MD2.7 | 91 + static/netbsd/man7/EVP_MD-MD4.7 | 91 + static/netbsd/man7/EVP_MD-MD5-SHA1.7 | 107 + static/netbsd/man7/EVP_MD-MD5.7 | 91 + static/netbsd/man7/EVP_MD-MDC2.7 | 101 + static/netbsd/man7/EVP_MD-NULL.7 | 95 + static/netbsd/man7/EVP_MD-RIPEMD160.7 | 95 + static/netbsd/man7/EVP_MD-SHA1.7 | 106 + static/netbsd/man7/EVP_MD-SHA2.7 | 123 + static/netbsd/man7/EVP_MD-SHA3.7 | 101 + static/netbsd/man7/EVP_MD-SHAKE.7 | 142 + static/netbsd/man7/EVP_MD-SM3.7 | 91 + static/netbsd/man7/EVP_MD-WHIRLPOOL.7 | 91 + static/netbsd/man7/EVP_MD-common.7 | 107 + static/netbsd/man7/EVP_PKEY-DH.7 | 374 +++ static/netbsd/man7/EVP_PKEY-DSA.7 | 196 ++ static/netbsd/man7/EVP_PKEY-EC.7 | 344 +++ static/netbsd/man7/EVP_PKEY-FFC.7 | 248 ++ static/netbsd/man7/EVP_PKEY-HMAC.7 | 128 + static/netbsd/man7/EVP_PKEY-ML-DSA.7 | 354 +++ static/netbsd/man7/EVP_PKEY-ML-KEM.7 | 372 +++ static/netbsd/man7/EVP_PKEY-RSA.7 | 319 ++ static/netbsd/man7/EVP_PKEY-SLH-DSA.7 | 201 ++ static/netbsd/man7/EVP_PKEY-SM2.7 | 153 + static/netbsd/man7/EVP_PKEY-X25519.7 | 166 + static/netbsd/man7/EVP_RAND-CRNG-TEST.7 | 125 + static/netbsd/man7/EVP_RAND-CTR-DRBG.7 | 167 + static/netbsd/man7/EVP_RAND-HASH-DRBG.7 | 191 ++ static/netbsd/man7/EVP_RAND-HMAC-DRBG.7 | 193 ++ static/netbsd/man7/EVP_RAND-JITTER.7 | 158 + static/netbsd/man7/EVP_RAND-SEED-SRC.7 | 144 + static/netbsd/man7/EVP_RAND-TEST-RAND.7 | 178 ++ static/netbsd/man7/EVP_RAND.7 | 334 ++ static/netbsd/man7/EVP_SIGNATURE-DSA.7 | 173 ++ static/netbsd/man7/EVP_SIGNATURE-ECDSA.7 | 162 + static/netbsd/man7/EVP_SIGNATURE-ED25519.7 | 234 ++ static/netbsd/man7/EVP_SIGNATURE-HMAC.7 | 110 + static/netbsd/man7/EVP_SIGNATURE-ML-DSA.7 | 185 ++ static/netbsd/man7/EVP_SIGNATURE-RSA.7 | 239 ++ static/netbsd/man7/EVP_SIGNATURE-SLH-DSA.7 | 181 ++ static/netbsd/man7/Ed25519.7 | 225 ++ static/netbsd/man7/OSSL_PROVIDER-FIPS.7 | 608 ++++ static/netbsd/man7/OSSL_PROVIDER-base.7 | 284 ++ static/netbsd/man7/OSSL_PROVIDER-default.7 | 564 ++++ static/netbsd/man7/OSSL_PROVIDER-legacy.7 | 160 + static/netbsd/man7/OSSL_PROVIDER-null.7 | 95 + static/netbsd/man7/OSSL_STORE-winstore.7 | 128 + static/netbsd/man7/RAND.7 | 148 + static/netbsd/man7/RAND_DRBG.7 | 400 +++ static/netbsd/man7/RELEASE_NOTES-2.7 | 175 ++ static/netbsd/man7/RELEASE_NOTES-3.7 | 179 ++ static/netbsd/man7/RSA-PSS.7 | 116 + static/netbsd/man7/SM2.7 | 219 ++ static/netbsd/man7/X25519.7 | 137 + static/netbsd/man7/bad.include-toplevel.7 | 11 + static/netbsd/man7/bio.7 | 168 + static/netbsd/man7/crypto.7 | 613 ++++ static/netbsd/man7/ct.7 | 112 + static/netbsd/man7/des_modes.7 | 222 ++ static/netbsd/man7/editline.7 | 941 ++++++ static/netbsd/man7/eqn.7 | 507 +++ static/netbsd/man7/evp.7 | 164 + static/netbsd/man7/example.7 | 13 + static/netbsd/man7/fips_module.7 | 646 ++++ static/netbsd/man7/fsf-funding.7 | 189 ++ static/netbsd/man7/gfdl.7 | 647 ++++ static/netbsd/man7/gpl.7 | 846 +++++ static/netbsd/man7/krb5-plugin.7 | 247 ++ static/netbsd/man7/kyua-atf-interface.7 | 405 +++ static/netbsd/man7/kyua-plain-interface.7 | 63 + static/netbsd/man7/life_cycle-cipher.7 | 210 ++ static/netbsd/man7/life_cycle-digest.7 | 189 ++ static/netbsd/man7/life_cycle-kdf.7 | 146 + static/netbsd/man7/life_cycle-mac.7 | 165 + static/netbsd/man7/life_cycle-pkey.7 | 249 ++ static/netbsd/man7/life_cycle-rand.7 | 158 + static/netbsd/man7/man.7 | 643 ++++ static/netbsd/man7/mandoc_char.7 | 829 +++++ static/netbsd/man7/mdoc.7 | 3261 ++++++++++++++++++++ static/netbsd/man7/me.7 | 315 ++ static/netbsd/man7/migration_guide.7 | 2092 +++++++++++++ static/netbsd/man7/npf-params.7 | 178 ++ static/netbsd/man7/npf.7 | 99 + static/netbsd/man7/openssl-core.h.7 | 111 + static/netbsd/man7/openssl-core_dispatch.h.7 | 109 + static/netbsd/man7/openssl-core_names.h.7 | 107 + static/netbsd/man7/openssl-env.7 | 242 ++ static/netbsd/man7/openssl-glossary.7 | 264 ++ static/netbsd/man7/openssl-qlog.7 | 279 ++ static/netbsd/man7/openssl-quic-concurrency.7 | 321 ++ static/netbsd/man7/openssl-quic.7 | 795 +++++ static/netbsd/man7/openssl-threads.7 | 163 + static/netbsd/man7/openssl_user_macros.7 | 160 + static/netbsd/man7/ossl-guide-introduction.7 | 165 + .../man7/ossl-guide-libcrypto-introduction.7 | 448 +++ .../man7/ossl-guide-libraries-introduction.7 | 377 +++ .../netbsd/man7/ossl-guide-libssl-introduction.7 | 165 + static/netbsd/man7/ossl-guide-migration.7 | 2123 +++++++++++++ static/netbsd/man7/ossl-guide-quic-client-block.7 | 466 +++ .../netbsd/man7/ossl-guide-quic-client-non-block.7 | 533 ++++ static/netbsd/man7/ossl-guide-quic-introduction.7 | 237 ++ static/netbsd/man7/ossl-guide-quic-multi-stream.7 | 458 +++ static/netbsd/man7/ossl-guide-quic-server-block.7 | 360 +++ .../netbsd/man7/ossl-guide-quic-server-non-block.7 | 452 +++ static/netbsd/man7/ossl-guide-tls-client-block.7 | 657 ++++ .../netbsd/man7/ossl-guide-tls-client-non-block.7 | 440 +++ static/netbsd/man7/ossl-guide-tls-introduction.7 | 381 +++ static/netbsd/man7/ossl-guide-tls-server-block.7 | 410 +++ static/netbsd/man7/ossl_store-file.7 | 118 + static/netbsd/man7/ossl_store.7 | 147 + static/netbsd/man7/p.7 | 1 + static/netbsd/man7/passphrase-encoding.7 | 215 ++ static/netbsd/man7/property.7 | 241 ++ static/netbsd/man7/provider-asym_cipher.7 | 335 ++ static/netbsd/man7/provider-base.7 | 1035 +++++++ static/netbsd/man7/provider-cipher.7 | 361 +++ static/netbsd/man7/provider-decoder.7 | 346 +++ static/netbsd/man7/provider-digest.7 | 341 ++ static/netbsd/man7/provider-encoder.7 | 355 +++ static/netbsd/man7/provider-kdf.7 | 381 +++ static/netbsd/man7/provider-kem.7 | 309 ++ static/netbsd/man7/provider-keyexch.7 | 310 ++ static/netbsd/man7/provider-keymgmt.7 | 557 ++++ static/netbsd/man7/provider-mac.7 | 320 ++ static/netbsd/man7/provider-object.7 | 213 ++ static/netbsd/man7/provider-rand.7 | 362 +++ static/netbsd/man7/provider-signature.7 | 718 +++++ static/netbsd/man7/provider-skeymgmt.7 | 237 ++ static/netbsd/man7/provider-storemgmt.7 | 274 ++ static/netbsd/man7/provider.7 | 327 ++ static/netbsd/man7/proxy-certificates.7 | 403 +++ static/netbsd/man7/re_format.7 | 756 +++++ static/netbsd/man7/roff.7 | 2342 ++++++++++++++ static/netbsd/man7/rump_sp.7 | 117 + static/netbsd/man7/rumpkernel.7 | 148 + static/netbsd/man7/scrypt.7 | 250 ++ static/netbsd/man7/smp.7 | 23 + static/netbsd/man7/ssl.7 | 153 + static/netbsd/man7/tbl.7 | 455 +++ static/netbsd/man7/test_packets.7 | 37 + static/netbsd/man7/test_signatures.7 | 32 + static/netbsd/man7/text-dump-0.7 | 9 + static/netbsd/man7/x509.7 | 133 + static/netbsd/man7/zpool-features.7 | 566 ++++ 193 files changed, 55144 insertions(+) create mode 100644 static/netbsd/man7/EVP_ASYM_CIPHER-RSA.7 create mode 100644 static/netbsd/man7/EVP_ASYM_CIPHER-SM2.7 create mode 100644 static/netbsd/man7/EVP_CIPHER-AES.7 create mode 100644 static/netbsd/man7/EVP_CIPHER-ARIA.7 create mode 100644 static/netbsd/man7/EVP_CIPHER-BLOWFISH.7 create mode 100644 static/netbsd/man7/EVP_CIPHER-CAMELLIA.7 create mode 100644 static/netbsd/man7/EVP_CIPHER-CAST.7 create mode 100644 static/netbsd/man7/EVP_CIPHER-CHACHA.7 create mode 100644 static/netbsd/man7/EVP_CIPHER-DES.7 create mode 100644 static/netbsd/man7/EVP_CIPHER-IDEA.7 create mode 100644 static/netbsd/man7/EVP_CIPHER-NULL.7 create mode 100644 static/netbsd/man7/EVP_CIPHER-RC2.7 create mode 100644 static/netbsd/man7/EVP_CIPHER-RC4.7 create mode 100644 static/netbsd/man7/EVP_CIPHER-RC5.7 create mode 100644 static/netbsd/man7/EVP_CIPHER-SEED.7 create mode 100644 static/netbsd/man7/EVP_CIPHER-SM4.7 create mode 100644 static/netbsd/man7/EVP_KDF-ARGON2.7 create mode 100644 static/netbsd/man7/EVP_KDF-HKDF.7 create mode 100644 static/netbsd/man7/EVP_KDF-HMAC-DRBG.7 create mode 100644 static/netbsd/man7/EVP_KDF-KB.7 create mode 100644 static/netbsd/man7/EVP_KDF-KRB5KDF.7 create mode 100644 static/netbsd/man7/EVP_KDF-PBKDF1.7 create mode 100644 static/netbsd/man7/EVP_KDF-PBKDF2.7 create mode 100644 static/netbsd/man7/EVP_KDF-PKCS12KDF.7 create mode 100644 static/netbsd/man7/EVP_KDF-PVKKDF.7 create mode 100644 static/netbsd/man7/EVP_KDF-SCRYPT.7 create mode 100644 static/netbsd/man7/EVP_KDF-SS.7 create mode 100644 static/netbsd/man7/EVP_KDF-SSHKDF.7 create mode 100644 static/netbsd/man7/EVP_KDF-TLS13_KDF.7 create mode 100644 static/netbsd/man7/EVP_KDF-TLS1_PRF.7 create mode 100644 static/netbsd/man7/EVP_KDF-X942-ASN1.7 create mode 100644 static/netbsd/man7/EVP_KDF-X942-CONCAT.7 create mode 100644 static/netbsd/man7/EVP_KDF-X963.7 create mode 100644 static/netbsd/man7/EVP_KEM-EC.7 create mode 100644 static/netbsd/man7/EVP_KEM-ML-KEM.7 create mode 100644 static/netbsd/man7/EVP_KEM-RSA.7 create mode 100644 static/netbsd/man7/EVP_KEM-X25519.7 create mode 100644 static/netbsd/man7/EVP_KEYEXCH-DH.7 create mode 100644 static/netbsd/man7/EVP_KEYEXCH-ECDH.7 create mode 100644 static/netbsd/man7/EVP_KEYEXCH-X25519.7 create mode 100644 static/netbsd/man7/EVP_MAC-BLAKE2.7 create mode 100644 static/netbsd/man7/EVP_MAC-CMAC.7 create mode 100644 static/netbsd/man7/EVP_MAC-GMAC.7 create mode 100644 static/netbsd/man7/EVP_MAC-HMAC.7 create mode 100644 static/netbsd/man7/EVP_MAC-KMAC.7 create mode 100644 static/netbsd/man7/EVP_MAC-Poly1305.7 create mode 100644 static/netbsd/man7/EVP_MAC-Siphash.7 create mode 100644 static/netbsd/man7/EVP_MD-BLAKE2.7 create mode 100644 static/netbsd/man7/EVP_MD-KECCAK.7 create mode 100644 static/netbsd/man7/EVP_MD-MD2.7 create mode 100644 static/netbsd/man7/EVP_MD-MD4.7 create mode 100644 static/netbsd/man7/EVP_MD-MD5-SHA1.7 create mode 100644 static/netbsd/man7/EVP_MD-MD5.7 create mode 100644 static/netbsd/man7/EVP_MD-MDC2.7 create mode 100644 static/netbsd/man7/EVP_MD-NULL.7 create mode 100644 static/netbsd/man7/EVP_MD-RIPEMD160.7 create mode 100644 static/netbsd/man7/EVP_MD-SHA1.7 create mode 100644 static/netbsd/man7/EVP_MD-SHA2.7 create mode 100644 static/netbsd/man7/EVP_MD-SHA3.7 create mode 100644 static/netbsd/man7/EVP_MD-SHAKE.7 create mode 100644 static/netbsd/man7/EVP_MD-SM3.7 create mode 100644 static/netbsd/man7/EVP_MD-WHIRLPOOL.7 create mode 100644 static/netbsd/man7/EVP_MD-common.7 create mode 100644 static/netbsd/man7/EVP_PKEY-DH.7 create mode 100644 static/netbsd/man7/EVP_PKEY-DSA.7 create mode 100644 static/netbsd/man7/EVP_PKEY-EC.7 create mode 100644 static/netbsd/man7/EVP_PKEY-FFC.7 create mode 100644 static/netbsd/man7/EVP_PKEY-HMAC.7 create mode 100644 static/netbsd/man7/EVP_PKEY-ML-DSA.7 create mode 100644 static/netbsd/man7/EVP_PKEY-ML-KEM.7 create mode 100644 static/netbsd/man7/EVP_PKEY-RSA.7 create mode 100644 static/netbsd/man7/EVP_PKEY-SLH-DSA.7 create mode 100644 static/netbsd/man7/EVP_PKEY-SM2.7 create mode 100644 static/netbsd/man7/EVP_PKEY-X25519.7 create mode 100644 static/netbsd/man7/EVP_RAND-CRNG-TEST.7 create mode 100644 static/netbsd/man7/EVP_RAND-CTR-DRBG.7 create mode 100644 static/netbsd/man7/EVP_RAND-HASH-DRBG.7 create mode 100644 static/netbsd/man7/EVP_RAND-HMAC-DRBG.7 create mode 100644 static/netbsd/man7/EVP_RAND-JITTER.7 create mode 100644 static/netbsd/man7/EVP_RAND-SEED-SRC.7 create mode 100644 static/netbsd/man7/EVP_RAND-TEST-RAND.7 create mode 100644 static/netbsd/man7/EVP_RAND.7 create mode 100644 static/netbsd/man7/EVP_SIGNATURE-DSA.7 create mode 100644 static/netbsd/man7/EVP_SIGNATURE-ECDSA.7 create mode 100644 static/netbsd/man7/EVP_SIGNATURE-ED25519.7 create mode 100644 static/netbsd/man7/EVP_SIGNATURE-HMAC.7 create mode 100644 static/netbsd/man7/EVP_SIGNATURE-ML-DSA.7 create mode 100644 static/netbsd/man7/EVP_SIGNATURE-RSA.7 create mode 100644 static/netbsd/man7/EVP_SIGNATURE-SLH-DSA.7 create mode 100644 static/netbsd/man7/Ed25519.7 create mode 100644 static/netbsd/man7/OSSL_PROVIDER-FIPS.7 create mode 100644 static/netbsd/man7/OSSL_PROVIDER-base.7 create mode 100644 static/netbsd/man7/OSSL_PROVIDER-default.7 create mode 100644 static/netbsd/man7/OSSL_PROVIDER-legacy.7 create mode 100644 static/netbsd/man7/OSSL_PROVIDER-null.7 create mode 100644 static/netbsd/man7/OSSL_STORE-winstore.7 create mode 100644 static/netbsd/man7/RAND.7 create mode 100644 static/netbsd/man7/RAND_DRBG.7 create mode 100644 static/netbsd/man7/RELEASE_NOTES-2.7 create mode 100644 static/netbsd/man7/RELEASE_NOTES-3.7 create mode 100644 static/netbsd/man7/RSA-PSS.7 create mode 100644 static/netbsd/man7/SM2.7 create mode 100644 static/netbsd/man7/X25519.7 create mode 100644 static/netbsd/man7/bad.include-toplevel.7 create mode 100644 static/netbsd/man7/bio.7 create mode 100644 static/netbsd/man7/crypto.7 create mode 100644 static/netbsd/man7/ct.7 create mode 100644 static/netbsd/man7/des_modes.7 create mode 100644 static/netbsd/man7/editline.7 create mode 100644 static/netbsd/man7/eqn.7 create mode 100644 static/netbsd/man7/evp.7 create mode 100644 static/netbsd/man7/example.7 create mode 100644 static/netbsd/man7/fips_module.7 create mode 100644 static/netbsd/man7/fsf-funding.7 create mode 100644 static/netbsd/man7/gfdl.7 create mode 100644 static/netbsd/man7/gpl.7 create mode 100644 static/netbsd/man7/krb5-plugin.7 create mode 100644 static/netbsd/man7/kyua-atf-interface.7 create mode 100644 static/netbsd/man7/kyua-plain-interface.7 create mode 100644 static/netbsd/man7/life_cycle-cipher.7 create mode 100644 static/netbsd/man7/life_cycle-digest.7 create mode 100644 static/netbsd/man7/life_cycle-kdf.7 create mode 100644 static/netbsd/man7/life_cycle-mac.7 create mode 100644 static/netbsd/man7/life_cycle-pkey.7 create mode 100644 static/netbsd/man7/life_cycle-rand.7 create mode 100644 static/netbsd/man7/man.7 create mode 100644 static/netbsd/man7/mandoc_char.7 create mode 100644 static/netbsd/man7/mdoc.7 create mode 100644 static/netbsd/man7/me.7 create mode 100644 static/netbsd/man7/migration_guide.7 create mode 100644 static/netbsd/man7/npf-params.7 create mode 100644 static/netbsd/man7/npf.7 create mode 100644 static/netbsd/man7/openssl-core.h.7 create mode 100644 static/netbsd/man7/openssl-core_dispatch.h.7 create mode 100644 static/netbsd/man7/openssl-core_names.h.7 create mode 100644 static/netbsd/man7/openssl-env.7 create mode 100644 static/netbsd/man7/openssl-glossary.7 create mode 100644 static/netbsd/man7/openssl-qlog.7 create mode 100644 static/netbsd/man7/openssl-quic-concurrency.7 create mode 100644 static/netbsd/man7/openssl-quic.7 create mode 100644 static/netbsd/man7/openssl-threads.7 create mode 100644 static/netbsd/man7/openssl_user_macros.7 create mode 100644 static/netbsd/man7/ossl-guide-introduction.7 create mode 100644 static/netbsd/man7/ossl-guide-libcrypto-introduction.7 create mode 100644 static/netbsd/man7/ossl-guide-libraries-introduction.7 create mode 100644 static/netbsd/man7/ossl-guide-libssl-introduction.7 create mode 100644 static/netbsd/man7/ossl-guide-migration.7 create mode 100644 static/netbsd/man7/ossl-guide-quic-client-block.7 create mode 100644 static/netbsd/man7/ossl-guide-quic-client-non-block.7 create mode 100644 static/netbsd/man7/ossl-guide-quic-introduction.7 create mode 100644 static/netbsd/man7/ossl-guide-quic-multi-stream.7 create mode 100644 static/netbsd/man7/ossl-guide-quic-server-block.7 create mode 100644 static/netbsd/man7/ossl-guide-quic-server-non-block.7 create mode 100644 static/netbsd/man7/ossl-guide-tls-client-block.7 create mode 100644 static/netbsd/man7/ossl-guide-tls-client-non-block.7 create mode 100644 static/netbsd/man7/ossl-guide-tls-introduction.7 create mode 100644 static/netbsd/man7/ossl-guide-tls-server-block.7 create mode 100644 static/netbsd/man7/ossl_store-file.7 create mode 100644 static/netbsd/man7/ossl_store.7 create mode 100644 static/netbsd/man7/p.7 create mode 100644 static/netbsd/man7/passphrase-encoding.7 create mode 100644 static/netbsd/man7/property.7 create mode 100644 static/netbsd/man7/provider-asym_cipher.7 create mode 100644 static/netbsd/man7/provider-base.7 create mode 100644 static/netbsd/man7/provider-cipher.7 create mode 100644 static/netbsd/man7/provider-decoder.7 create mode 100644 static/netbsd/man7/provider-digest.7 create mode 100644 static/netbsd/man7/provider-encoder.7 create mode 100644 static/netbsd/man7/provider-kdf.7 create mode 100644 static/netbsd/man7/provider-kem.7 create mode 100644 static/netbsd/man7/provider-keyexch.7 create mode 100644 static/netbsd/man7/provider-keymgmt.7 create mode 100644 static/netbsd/man7/provider-mac.7 create mode 100644 static/netbsd/man7/provider-object.7 create mode 100644 static/netbsd/man7/provider-rand.7 create mode 100644 static/netbsd/man7/provider-signature.7 create mode 100644 static/netbsd/man7/provider-skeymgmt.7 create mode 100644 static/netbsd/man7/provider-storemgmt.7 create mode 100644 static/netbsd/man7/provider.7 create mode 100644 static/netbsd/man7/proxy-certificates.7 create mode 100644 static/netbsd/man7/re_format.7 create mode 100644 static/netbsd/man7/roff.7 create mode 100644 static/netbsd/man7/rump_sp.7 create mode 100644 static/netbsd/man7/rumpkernel.7 create mode 100644 static/netbsd/man7/scrypt.7 create mode 100644 static/netbsd/man7/smp.7 create mode 100644 static/netbsd/man7/ssl.7 create mode 100644 static/netbsd/man7/tbl.7 create mode 100644 static/netbsd/man7/test_packets.7 create mode 100644 static/netbsd/man7/test_signatures.7 create mode 100644 static/netbsd/man7/text-dump-0.7 create mode 100644 static/netbsd/man7/x509.7 create mode 100644 static/netbsd/man7/zpool-features.7 (limited to 'static/netbsd/man7') diff --git a/static/netbsd/man7/EVP_ASYM_CIPHER-RSA.7 b/static/netbsd/man7/EVP_ASYM_CIPHER-RSA.7 new file mode 100644 index 00000000..bace740e --- /dev/null +++ b/static/netbsd/man7/EVP_ASYM_CIPHER-RSA.7 @@ -0,0 +1,171 @@ +.\" $NetBSD: EVP_ASYM_CIPHER-RSA.7,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_ASYM_CIPHER-RSA 7" +.TH EVP_ASYM_CIPHER-RSA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_ASYM_CIPHER\-RSA +\&\- RSA Asymmetric Cipher algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Asymmetric Cipher support for the \fBRSA\fR key type. +.SS "RSA Asymmetric Cipher parameters" +.IX Subsection "RSA Asymmetric Cipher parameters" +.IP """pad\-mode"" (\fBOSSL_ASYM_CIPHER_PARAM_PAD_MODE\fR) " 4 +.IX Item """pad-mode"" (OSSL_ASYM_CIPHER_PARAM_PAD_MODE) " +The default provider understands these RSA padding modes in string form: +.RS 4 +.IP """none"" (\fBOSSL_PKEY_RSA_PAD_MODE_NONE\fR)" 4 +.IX Item """none"" (OSSL_PKEY_RSA_PAD_MODE_NONE)" +.PD 0 +.IP """oaep"" (\fBOSSL_PKEY_RSA_PAD_MODE_OAEP\fR)" 4 +.IX Item """oaep"" (OSSL_PKEY_RSA_PAD_MODE_OAEP)" +.IP """pkcs1"" (\fBOSSL_PKEY_RSA_PAD_MODE_PKCSV15\fR)" 4 +.IX Item """pkcs1"" (OSSL_PKEY_RSA_PAD_MODE_PKCSV15)" +.PD +This padding mode is no longer supported by the FIPS provider for key +agreement and key transport. +(This is a FIPS 140\-3 requirement). +See "OPTIONS" in \fBopenssl\-fipsinstall\fR\|(1) \fB\-rsa_pkcs15_pad_disabled\fR. +.IP """x931"" (\fBOSSL_PKEY_RSA_PAD_MODE_X931\fR)" 4 +.IX Item """x931"" (OSSL_PKEY_RSA_PAD_MODE_X931)" +.RE +.RS 4 +.RE +.IP """pad\-mode"" (\fBOSSL_ASYM_CIPHER_PARAM_PAD_MODE\fR) " 4 +.IX Item """pad-mode"" (OSSL_ASYM_CIPHER_PARAM_PAD_MODE) " +The default provider understands these RSA padding modes in integer form: +.RS 4 +.IP "1 (\fBRSA_PKCS1_PADDING\fR)" 4 +.IX Item "1 (RSA_PKCS1_PADDING)" +This padding mode is no longer supported by the FIPS provider for key +agreement and key transport. +(This is a FIPS 140\-3 requirement) +.IP "3 (\fBRSA_NO_PADDING\fR)" 4 +.IX Item "3 (RSA_NO_PADDING)" +.PD 0 +.IP "4 (\fBRSA_PKCS1_OAEP_PADDING\fR)" 4 +.IX Item "4 (RSA_PKCS1_OAEP_PADDING)" +.IP "5 (\fBRSA_X931_PADDING\fR)" 4 +.IX Item "5 (RSA_X931_PADDING)" +.PD +.RE +.RS 4 +.Sp +See \fBEVP_PKEY_CTX_set_rsa_padding\fR\|(3) for further details. +.RE +.IP """digest"" (\fBOSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST) " +.PD 0 +.IP """digest\-props"" (\fBOSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS\fR) " 4 +.IX Item """digest-props"" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS) " +.IP """mgf1\-digest"" (\fBOSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST\fR) " 4 +.IX Item """mgf1-digest"" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST) " +.IP """mgf1\-digest\-props"" (\fBOSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS\fR) " 4 +.IX Item """mgf1-digest-props"" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS) " +.IP """oaep\-label"" (\fBOSSL_ASYM_CIPHER_PARAM_OAEP_LABEL\fR) " 4 +.IX Item """oaep-label"" (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) " +.IP """tls\-client\-version"" (\fBOSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION\fR) " 4 +.IX Item """tls-client-version"" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) " +.PD +See \fBRSA_PKCS1_WITH_TLS_PADDING\fR on the page \fBEVP_PKEY_CTX_set_rsa_padding\fR\|(3). +.IP """tls\-negotiated\-version"" (\fBOSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION\fR) " 4 +.IX Item """tls-negotiated-version"" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) " +See \fBRSA_PKCS1_WITH_TLS_PADDING\fR on the page \fBEVP_PKEY_CTX_set_rsa_padding\fR\|(3). +.Sp +See "Asymmetric Cipher Parameters" in \fBprovider\-asym_cipher\fR\|(7) for more information. +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_ASYM_CIPHER_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_ASYM_CIPHER_PARAM_FIPS_APPROVED_INDICATOR) " +.PD 0 +.IP """key\-check"" (\fBOSSL_ASYM_CIPHER_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_ASYM_CIPHER_PARAM_FIPS_KEY_CHECK) " +.PD +See "Asymmetric Cipher Parameters" in \fBprovider\-asym_cipher\fR\|(7) for more information. +.IP """pkcs15\-pad\-disabled"" (\fBOSSL_ASYM_CIPHER_PARAM_FIPS_RSA_PKCS15_PAD_DISABLED\fR) " 4 +.IX Item """pkcs15-pad-disabled"" (OSSL_ASYM_CIPHER_PARAM_FIPS_RSA_PKCS15_PAD_DISABLED) " +The default value of 1 causes an error during encryption if the RSA padding +mode is set to "pkcs1". +Setting this to zero will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY\-RSA\fR\|(7), +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-asym_cipher\fR\|(7), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7) +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_ASYM_CIPHER-SM2.7 b/static/netbsd/man7/EVP_ASYM_CIPHER-SM2.7 new file mode 100644 index 00000000..42c40805 --- /dev/null +++ b/static/netbsd/man7/EVP_ASYM_CIPHER-SM2.7 @@ -0,0 +1,97 @@ +.\" $NetBSD: EVP_ASYM_CIPHER-SM2.7,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_ASYM_CIPHER-SM2 7" +.TH EVP_ASYM_CIPHER-SM2 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_ASYM_CIPHER\-SM2 +\&\- SM2 Asymmetric Cipher algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Asymmetric Cipher support for the \fBSM2\fR key type. +.SS "SM2 Asymmetric Cipher parameters" +.IX Subsection "SM2 Asymmetric Cipher parameters" +.IP """digest"" (\fBOSSL_ASYM_CIPHER_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_ASYM_CIPHER_PARAM_DIGEST) " +.PD 0 +.IP """digest\-props"" (\fBOSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS\fR) " 4 +.IX Item """digest-props"" (OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS) " +.PD +See "Asymmetric Cipher Parameters" in \fBprovider\-asym_cipher\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY\-SM2\fR\|(7), +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-asym_cipher\fR\|(7), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_CIPHER-AES.7 b/static/netbsd/man7/EVP_CIPHER-AES.7 new file mode 100644 index 00000000..f3938289 --- /dev/null +++ b/static/netbsd/man7/EVP_CIPHER-AES.7 @@ -0,0 +1,141 @@ +.\" $NetBSD: EVP_CIPHER-AES.7,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER-AES 7" +.TH EVP_CIPHER-AES 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER\-AES \- The AES EVP_CIPHER implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for AES symmetric encryption using the \fBEVP_CIPHER\fR API. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the FIPS provider as well as the +default provider: +.IP """AES\-128\-CBC"", ""AES\-192\-CBC"" and ""AES\-256\-CBC""" 4 +.IX Item """AES-128-CBC"", ""AES-192-CBC"" and ""AES-256-CBC""" +.PD 0 +.IP """AES\-128\-CBC\-CTS"", ""AES\-192\-CBC\-CTS"" and ""AES\-256\-CBC\-CTS""" 4 +.IX Item """AES-128-CBC-CTS"", ""AES-192-CBC-CTS"" and ""AES-256-CBC-CTS""" +.IP """AES\-128\-CFB"", ""AES\-192\-CFB"", ""AES\-256\-CFB"", ""AES\-128\-CFB1"", ""AES\-192\-CFB1"", ""AES\-256\-CFB1"", ""AES\-128\-CFB8"", ""AES\-192\-CFB8"" and ""AES\-256\-CFB8""" 4 +.IX Item """AES-128-CFB"", ""AES-192-CFB"", ""AES-256-CFB"", ""AES-128-CFB1"", ""AES-192-CFB1"", ""AES-256-CFB1"", ""AES-128-CFB8"", ""AES-192-CFB8"" and ""AES-256-CFB8""" +.IP """AES\-128\-CTR"", ""AES\-192\-CTR"" and ""AES\-256\-CTR""" 4 +.IX Item """AES-128-CTR"", ""AES-192-CTR"" and ""AES-256-CTR""" +.IP """AES\-128\-ECB"", ""AES\-192\-ECB"" and ""AES\-256\-ECB""" 4 +.IX Item """AES-128-ECB"", ""AES-192-ECB"" and ""AES-256-ECB""" +.IP """AES\-192\-OFB"", ""AES\-128\-OFB"" and ""AES\-256\-OFB""" 4 +.IX Item """AES-192-OFB"", ""AES-128-OFB"" and ""AES-256-OFB""" +.IP """AES\-128\-XTS"" and ""AES\-256\-XTS""" 4 +.IX Item """AES-128-XTS"" and ""AES-256-XTS""" +.IP """AES\-128\-CCM"", ""AES\-192\-CCM"" and ""AES\-256\-CCM""" 4 +.IX Item """AES-128-CCM"", ""AES-192-CCM"" and ""AES-256-CCM""" +.IP """AES\-128\-GCM"", ""AES\-192\-GCM"" and ""AES\-256\-GCM""" 4 +.IX Item """AES-128-GCM"", ""AES-192-GCM"" and ""AES-256-GCM""" +.IP """AES\-128\-WRAP"", ""AES\-192\-WRAP"", ""AES\-256\-WRAP"", ""AES\-128\-WRAP\-PAD"", ""AES\-192\-WRAP\-PAD"", ""AES\-256\-WRAP\-PAD"", ""AES\-128\-WRAP\-INV"", ""AES\-192\-WRAP\-INV"", ""AES\-256\-WRAP\-INV"", ""AES\-128\-WRAP\-PAD\-INV"", ""AES\-192\-WRAP\-PAD\-INV"" and ""AES\-256\-WRAP\-PAD\-INV""" 4 +.IX Item """AES-128-WRAP"", ""AES-192-WRAP"", ""AES-256-WRAP"", ""AES-128-WRAP-PAD"", ""AES-192-WRAP-PAD"", ""AES-256-WRAP-PAD"", ""AES-128-WRAP-INV"", ""AES-192-WRAP-INV"", ""AES-256-WRAP-INV"", ""AES-128-WRAP-PAD-INV"", ""AES-192-WRAP-PAD-INV"" and ""AES-256-WRAP-PAD-INV""" +.IP """AES\-128\-CBC\-HMAC\-SHA1"", ""AES\-256\-CBC\-HMAC\-SHA1"", ""AES\-128\-CBC\-HMAC\-SHA256"" and ""AES\-256\-CBC\-HMAC\-SHA256""" 4 +.IX Item """AES-128-CBC-HMAC-SHA1"", ""AES-256-CBC-HMAC-SHA1"", ""AES-128-CBC-HMAC-SHA256"" and ""AES-256-CBC-HMAC-SHA256""" +.PD +.PP +The following algorithms are available in the default provider, but not the +FIPS provider: +.IP """AES\-128\-OCB"", ""AES\-192\-OCB"" and ""AES\-256\-OCB""" 4 +.IX Item """AES-128-OCB"", ""AES-192-OCB"" and ""AES-256-OCB""" +.PD 0 +.IP """AES\-128\-SIV"", ""AES\-192\-SIV"" and ""AES\-256\-SIV""" 4 +.IX Item """AES-128-SIV"", ""AES-192-SIV"" and ""AES-256-SIV""" +.IP """AES\-128\-GCM\-SIV"", ""AES\-192\-GCM\-SIV"" and ""AES\-256\-GCM\-SIV""" 4 +.IX Item """AES-128-GCM-SIV"", ""AES-192-GCM-SIV"" and ""AES-256-GCM-SIV""" +.PD +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the parameters described in +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.SH NOTES +.IX Header "NOTES" +The AES\-SIV and AES\-WRAP mode implementations do not support streaming. That +means to obtain correct results there can be only one \fBEVP_EncryptUpdate\fR\|(3) +or \fBEVP_DecryptUpdate\fR\|(3) call after the initialization of the context. +.PP +The AES\-XTS implementations allow streaming to be performed, but each +\&\fBEVP_EncryptUpdate\fR\|(3) or \fBEVP_DecryptUpdate\fR\|(3) call requires each input +to be a multiple of the blocksize. Only the final \fBEVP_EncryptUpdate()\fR or +\&\fBEVP_DecryptUpdate()\fR call can optionally have an input that is not a multiple +of the blocksize but is larger than one block. In that case ciphertext +stealing (CTS) is used to fill the block. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The GCM\-SIV mode ciphers were added in OpenSSL version 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_CIPHER-ARIA.7 b/static/netbsd/man7/EVP_CIPHER-ARIA.7 new file mode 100644 index 00000000..f2871733 --- /dev/null +++ b/static/netbsd/man7/EVP_CIPHER-ARIA.7 @@ -0,0 +1,108 @@ +.\" $NetBSD: EVP_CIPHER-ARIA.7,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER-ARIA 7" +.TH EVP_CIPHER-ARIA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER\-ARIA \- The ARIA EVP_CIPHER implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for ARIA symmetric encryption using the \fBEVP_CIPHER\fR API. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the default provider: +.IP """ARIA\-128\-CBC"", ""ARIA\-192\-CBC"" and ""ARIA\-256\-CBC""" 4 +.IX Item """ARIA-128-CBC"", ""ARIA-192-CBC"" and ""ARIA-256-CBC""" +.PD 0 +.IP """ARIA\-128\-CFB"", ""ARIA\-192\-CFB"", ""ARIA\-256\-CFB"", ""ARIA\-128\-CFB1"", ""ARIA\-192\-CFB1"", ""ARIA\-256\-CFB1"", ""ARIA\-128\-CFB8"", ""ARIA\-192\-CFB8"" and ""ARIA\-256\-CFB8""" 4 +.IX Item """ARIA-128-CFB"", ""ARIA-192-CFB"", ""ARIA-256-CFB"", ""ARIA-128-CFB1"", ""ARIA-192-CFB1"", ""ARIA-256-CFB1"", ""ARIA-128-CFB8"", ""ARIA-192-CFB8"" and ""ARIA-256-CFB8""" +.IP """ARIA\-128\-CTR"", ""ARIA\-192\-CTR"" and ""ARIA\-256\-CTR""" 4 +.IX Item """ARIA-128-CTR"", ""ARIA-192-CTR"" and ""ARIA-256-CTR""" +.IP """ARIA\-128\-ECB"", ""ARIA\-192\-ECB"" and ""ARIA\-256\-ECB""" 4 +.IX Item """ARIA-128-ECB"", ""ARIA-192-ECB"" and ""ARIA-256-ECB""" +.IP """AES\-192\-OCB"", ""AES\-128\-OCB"" and ""AES\-256\-OCB""" 4 +.IX Item """AES-192-OCB"", ""AES-128-OCB"" and ""AES-256-OCB""" +.IP """ARIA\-128\-OFB"", ""ARIA\-192\-OFB"" and ""ARIA\-256\-OFB""" 4 +.IX Item """ARIA-128-OFB"", ""ARIA-192-OFB"" and ""ARIA-256-OFB""" +.IP """ARIA\-128\-CCM"", ""ARIA\-192\-CCM"" and ""ARIA\-256\-CCM""" 4 +.IX Item """ARIA-128-CCM"", ""ARIA-192-CCM"" and ""ARIA-256-CCM""" +.IP """ARIA\-128\-GCM"", ""ARIA\-192\-GCM"" and ""ARIA\-256\-GCM""" 4 +.IX Item """ARIA-128-GCM"", ""ARIA-192-GCM"" and ""ARIA-256-GCM""" +.PD +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the parameters described in +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_CIPHER-BLOWFISH.7 b/static/netbsd/man7/EVP_CIPHER-BLOWFISH.7 new file mode 100644 index 00000000..9556670c --- /dev/null +++ b/static/netbsd/man7/EVP_CIPHER-BLOWFISH.7 @@ -0,0 +1,100 @@ +.\" $NetBSD: EVP_CIPHER-BLOWFISH.7,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER-BLOWFISH 7" +.TH EVP_CIPHER-BLOWFISH 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER\-BLOWFISH \- The BLOBFISH EVP_CIPHER implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for BLOWFISH symmetric encryption using the \fBEVP_CIPHER\fR API. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the legacy provider: +.IP """BF\-ECB""" 4 +.IX Item """BF-ECB""" +.PD 0 +.IP """BF\-CBC""" 4 +.IX Item """BF-CBC""" +.IP """BF\-OFB""" 4 +.IX Item """BF-OFB""" +.IP """BF\-CFB""" 4 +.IX Item """BF-CFB""" +.PD +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the parameters described in +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_CIPHER-CAMELLIA.7 b/static/netbsd/man7/EVP_CIPHER-CAMELLIA.7 new file mode 100644 index 00000000..c060c7cd --- /dev/null +++ b/static/netbsd/man7/EVP_CIPHER-CAMELLIA.7 @@ -0,0 +1,104 @@ +.\" $NetBSD: EVP_CIPHER-CAMELLIA.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER-CAMELLIA 7" +.TH EVP_CIPHER-CAMELLIA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER\-CAMELLIA \- The CAMELLIA EVP_CIPHER implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for CAMELLIA symmetric encryption using the \fBEVP_CIPHER\fR API. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the default provider: +.IP """CAMELLIA\-128\-CBC"", ""CAMELLIA\-192\-CBC"" and ""CAMELLIA\-256\-CBC""" 4 +.IX Item """CAMELLIA-128-CBC"", ""CAMELLIA-192-CBC"" and ""CAMELLIA-256-CBC""" +.PD 0 +.IP """CAMELLIA\-128\-CBC\-CTS"", ""CAMELLIA\-192\-CBC\-CTS"" and ""CAMELLIA\-256\-CBC\-CTS""" 4 +.IX Item """CAMELLIA-128-CBC-CTS"", ""CAMELLIA-192-CBC-CTS"" and ""CAMELLIA-256-CBC-CTS""" +.IP """CAMELLIA\-128\-CFB"", ""CAMELLIA\-192\-CFB"", ""CAMELLIA\-256\-CFB"", ""CAMELLIA\-128\-CFB1"", ""CAMELLIA\-192\-CFB1"", ""CAMELLIA\-256\-CFB1"", ""CAMELLIA\-128\-CFB8"", ""CAMELLIA\-192\-CFB8"" and ""CAMELLIA\-256\-CFB8""" 4 +.IX Item """CAMELLIA-128-CFB"", ""CAMELLIA-192-CFB"", ""CAMELLIA-256-CFB"", ""CAMELLIA-128-CFB1"", ""CAMELLIA-192-CFB1"", ""CAMELLIA-256-CFB1"", ""CAMELLIA-128-CFB8"", ""CAMELLIA-192-CFB8"" and ""CAMELLIA-256-CFB8""" +.IP """CAMELLIA\-128\-CTR"", ""CAMELLIA\-192\-CTR"" and ""CAMELLIA\-256\-CTR""" 4 +.IX Item """CAMELLIA-128-CTR"", ""CAMELLIA-192-CTR"" and ""CAMELLIA-256-CTR""" +.IP """CAMELLIA\-128\-ECB"", ""CAMELLIA\-192\-ECB"" and ""CAMELLIA\-256\-ECB""" 4 +.IX Item """CAMELLIA-128-ECB"", ""CAMELLIA-192-ECB"" and ""CAMELLIA-256-ECB""" +.IP """CAMELLIA\-192\-OFB"", ""CAMELLIA\-128\-OFB"" and ""CAMELLIA\-256\-OFB""" 4 +.IX Item """CAMELLIA-192-OFB"", ""CAMELLIA-128-OFB"" and ""CAMELLIA-256-OFB""" +.PD +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the parameters described in +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_CIPHER-CAST.7 b/static/netbsd/man7/EVP_CIPHER-CAST.7 new file mode 100644 index 00000000..ae79cd58 --- /dev/null +++ b/static/netbsd/man7/EVP_CIPHER-CAST.7 @@ -0,0 +1,100 @@ +.\" $NetBSD: EVP_CIPHER-CAST.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER-CAST 7" +.TH EVP_CIPHER-CAST 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER\-CAST \- The CAST EVP_CIPHER implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for CAST symmetric encryption using the \fBEVP_CIPHER\fR API. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the legacy provider: +.IP """CAST\-128\-CBC"", ""CAST\-192\-CBC"" and ""CAST\-256\-CBC""" 4 +.IX Item """CAST-128-CBC"", ""CAST-192-CBC"" and ""CAST-256-CBC""" +.PD 0 +.IP """CAST\-128\-CFB"", ""CAST\-192\-CFB"", ""CAST\-256\-CFB""" 4 +.IX Item """CAST-128-CFB"", ""CAST-192-CFB"", ""CAST-256-CFB""" +.IP """CAST\-128\-ECB"", ""CAST\-192\-ECB"" and ""CAST\-256\-ECB""" 4 +.IX Item """CAST-128-ECB"", ""CAST-192-ECB"" and ""CAST-256-ECB""" +.IP """CAST\-192\-OFB"", ""CAST\-128\-OFB"" and ""CAST\-256\-OFB""" 4 +.IX Item """CAST-192-OFB"", ""CAST-128-OFB"" and ""CAST-256-OFB""" +.PD +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the parameters described in +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_CIPHER-CHACHA.7 b/static/netbsd/man7/EVP_CIPHER-CHACHA.7 new file mode 100644 index 00000000..bb353ee1 --- /dev/null +++ b/static/netbsd/man7/EVP_CIPHER-CHACHA.7 @@ -0,0 +1,96 @@ +.\" $NetBSD: EVP_CIPHER-CHACHA.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER-CHACHA 7" +.TH EVP_CIPHER-CHACHA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER\-CHACHA \- The CHACHA EVP_CIPHER implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for CHACHA symmetric encryption using the \fBEVP_CIPHER\fR API. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the default provider: +.IP """ChaCha20""" 4 +.IX Item """ChaCha20""" +.PD 0 +.IP """ChaCha20\-Poly1305""" 4 +.IX Item """ChaCha20-Poly1305""" +.PD +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the parameters described in +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_CIPHER-DES.7 b/static/netbsd/man7/EVP_CIPHER-DES.7 new file mode 100644 index 00000000..0d9d9a03 --- /dev/null +++ b/static/netbsd/man7/EVP_CIPHER-DES.7 @@ -0,0 +1,129 @@ +.\" $NetBSD: EVP_CIPHER-DES.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER-DES 7" +.TH EVP_CIPHER-DES 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER\-DES \- The DES EVP_CIPHER implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for DES symmetric encryption using the \fBEVP_CIPHER\fR API. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the FIPS provider as well as the +default provider: +.IP """DES\-EDE3\-ECB"" or ""DES\-EDE3""" 4 +.IX Item """DES-EDE3-ECB"" or ""DES-EDE3""" +.PD 0 +.IP """DES\-EDE3\-CBC"" or ""DES3""" 4 +.IX Item """DES-EDE3-CBC"" or ""DES3""" +.PD +.PP +The following algorithms are available in the default provider, but not the +FIPS provider: +.IP """DES\-EDE3\-CFB8"" and ""DES\-EDE3\-CFB1""" 4 +.IX Item """DES-EDE3-CFB8"" and ""DES-EDE3-CFB1""" +.PD 0 +.IP """DES\-EDE\-ECB"" or ""DES\-EDE""" 4 +.IX Item """DES-EDE-ECB"" or ""DES-EDE""" +.IP """DES\-EDE\-CBC""" 4 +.IX Item """DES-EDE-CBC""" +.IP """DES\-EDE\-OFB""" 4 +.IX Item """DES-EDE-OFB""" +.IP """DES\-EDE\-CFB""" 4 +.IX Item """DES-EDE-CFB""" +.IP """DES3\-WRAP""" 4 +.IX Item """DES3-WRAP""" +.PD +.PP +The following algorithms are available in the legacy provider: +.IP """DES\-ECB""" 4 +.IX Item """DES-ECB""" +.PD 0 +.IP """DES\-CBC""" 4 +.IX Item """DES-CBC""" +.IP """DES\-OFB""" 4 +.IX Item """DES-OFB""" +.IP """DES\-CFB"", ""DES\-CFB1"" and ""DES\-CFB8""" 4 +.IX Item """DES-CFB"", ""DES-CFB1"" and ""DES-CFB8""" +.IP """DESX\-CBC""" 4 +.IX Item """DESX-CBC""" +.PD +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the parameters described in +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3) including "encrypt\-check" and "fips\-indicator". +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), +\&\fBOSSL_PROVIDER\-legacy\fR\|(7), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_CIPHER-IDEA.7 b/static/netbsd/man7/EVP_CIPHER-IDEA.7 new file mode 100644 index 00000000..aed96355 --- /dev/null +++ b/static/netbsd/man7/EVP_CIPHER-IDEA.7 @@ -0,0 +1,100 @@ +.\" $NetBSD: EVP_CIPHER-IDEA.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER-IDEA 7" +.TH EVP_CIPHER-IDEA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER\-IDEA \- The IDEA EVP_CIPHER implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for IDEA symmetric encryption using the \fBEVP_CIPHER\fR API. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the legacy provider: +.IP """IDEA\-ECB""" 4 +.IX Item """IDEA-ECB""" +.PD 0 +.IP """IDEA\-CBC""" 4 +.IX Item """IDEA-CBC""" +.IP """IDEA\-OFB"" or ""IDEA\-OFB64""" 4 +.IX Item """IDEA-OFB"" or ""IDEA-OFB64""" +.IP """IDEA\-CFB"" or ""IDEA\-CFB64""" 4 +.IX Item """IDEA-CFB"" or ""IDEA-CFB64""" +.PD +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the parameters described in +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_CIPHER-NULL.7 b/static/netbsd/man7/EVP_CIPHER-NULL.7 new file mode 100644 index 00000000..9355668a --- /dev/null +++ b/static/netbsd/man7/EVP_CIPHER-NULL.7 @@ -0,0 +1,121 @@ +.\" $NetBSD: EVP_CIPHER-NULL.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER-NULL 7" +.TH EVP_CIPHER-NULL 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER\-NULL \- The NULL EVP_CIPHER implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for a NULL symmetric encryption using the \fBEVP_CIPHER\fR API. +This is used when the TLS cipher suite is TLS_NULL_WITH_NULL_NULL. +This does no encryption (just copies the data) and has a mac size of zero. +.SS "Algorithm Name" +.IX Subsection "Algorithm Name" +The following algorithm is available in the default provider: +.IP """NULL""" 4 +.IX Item """NULL""" +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the following parameters: +.PP +\fIGettable EVP_CIPHER parameters\fR +.IX Subsection "Gettable EVP_CIPHER parameters" +.PP +See "Gettable EVP_CIPHER parameters" in \fBEVP_EncryptInit\fR\|(3) +.PP +\fIGettable EVP_CIPHER_CTX parameters\fR +.IX Subsection "Gettable EVP_CIPHER_CTX parameters" +.IP """keylen"" (\fBOSSL_CIPHER_PARAM_KEYLEN\fR) " 4 +.IX Item """keylen"" (OSSL_CIPHER_PARAM_KEYLEN) " +.PD 0 +.IP """ivlen"" (\fBOSSL_CIPHER_PARAM_IVLEN\fR and <\fBOSSL_CIPHER_PARAM_AEAD_IVLEN\fR) " 4 +.IX Item """ivlen"" (OSSL_CIPHER_PARAM_IVLEN and " +.IP """tls\-mac"" (\fBOSSL_CIPHER_PARAM_TLS_MAC\fR) " 4 +.IX Item """tls-mac"" (OSSL_CIPHER_PARAM_TLS_MAC) " +.PD +.PP +See "PARAMETERS" in \fBEVP_EncryptInit\fR\|(3) for further information. +.PP +\fISettable EVP_CIPHER_CTX parameters\fR +.IX Subsection "Settable EVP_CIPHER_CTX parameters" +.IP """tls\-mac\-size"" (\fBOSSL_CIPHER_PARAM_TLS_MAC_SIZE\fR) " 4 +.IX Item """tls-mac-size"" (OSSL_CIPHER_PARAM_TLS_MAC_SIZE) " +.PP +See "PARAMETERS" in \fBEVP_EncryptInit\fR\|(3) for further information. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 5246 section\-6.2.3.1 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_CIPHER-RC2.7 b/static/netbsd/man7/EVP_CIPHER-RC2.7 new file mode 100644 index 00000000..f8bfc5b3 --- /dev/null +++ b/static/netbsd/man7/EVP_CIPHER-RC2.7 @@ -0,0 +1,104 @@ +.\" $NetBSD: EVP_CIPHER-RC2.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER-RC2 7" +.TH EVP_CIPHER-RC2 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER\-RC2 \- The RC2 EVP_CIPHER implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for RC2 symmetric encryption using the \fBEVP_CIPHER\fR API. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the legacy provider: +.IP """RC2\-CBC"", ""RC2"" or ""RC2\-128""" 4 +.IX Item """RC2-CBC"", ""RC2"" or ""RC2-128""" +.PD 0 +.IP """RC2\-40\-CBC"" or ""RC2\-40""" 4 +.IX Item """RC2-40-CBC"" or ""RC2-40""" +.IP """RC2\-64\-CBC"" or ""RC2\-64""" 4 +.IX Item """RC2-64-CBC"" or ""RC2-64""" +.IP """RC2\-ECB""" 4 +.IX Item """RC2-ECB""" +.IP """RC2\-CFB""" 4 +.IX Item """RC2-CFB""" +.IP """RC2\-OFB""" 4 +.IX Item """RC2-OFB""" +.PD +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the parameters described in +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_CIPHER-RC4.7 b/static/netbsd/man7/EVP_CIPHER-RC4.7 new file mode 100644 index 00000000..f3a0d196 --- /dev/null +++ b/static/netbsd/man7/EVP_CIPHER-RC4.7 @@ -0,0 +1,98 @@ +.\" $NetBSD: EVP_CIPHER-RC4.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER-RC4 7" +.TH EVP_CIPHER-RC4 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER\-RC4 \- The RC4 EVP_CIPHER implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for RC4 symmetric encryption using the \fBEVP_CIPHER\fR API. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the legacy provider: +.IP """RC4""" 4 +.IX Item """RC4""" +.PD 0 +.IP """RC4\-40""" 4 +.IX Item """RC4-40""" +.IP """RC4\-HMAC\-MD5""" 4 +.IX Item """RC4-HMAC-MD5""" +.PD +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the parameters described in +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_CIPHER-RC5.7 b/static/netbsd/man7/EVP_CIPHER-RC5.7 new file mode 100644 index 00000000..2a3e7314 --- /dev/null +++ b/static/netbsd/man7/EVP_CIPHER-RC5.7 @@ -0,0 +1,102 @@ +.\" $NetBSD: EVP_CIPHER-RC5.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER-RC5 7" +.TH EVP_CIPHER-RC5 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER\-RC5 \- The RC5 EVP_CIPHER implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for RC5 symmetric encryption using the \fBEVP_CIPHER\fR API. +.PP +Disabled by default. Use the \fIenable\-rc5\fR configuration option to enable. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the legacy provider: +.IP """RC5\-CBC"" or ""RC5""" 4 +.IX Item """RC5-CBC"" or ""RC5""" +.PD 0 +.IP """RC5\-ECB""" 4 +.IX Item """RC5-ECB""" +.IP """RC5\-OFB""" 4 +.IX Item """RC5-OFB""" +.IP """RC5\-CFB""" 4 +.IX Item """RC5-CFB""" +.PD +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the parameters described in +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_CIPHER-SEED.7 b/static/netbsd/man7/EVP_CIPHER-SEED.7 new file mode 100644 index 00000000..3cef1045 --- /dev/null +++ b/static/netbsd/man7/EVP_CIPHER-SEED.7 @@ -0,0 +1,100 @@ +.\" $NetBSD: EVP_CIPHER-SEED.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER-SEED 7" +.TH EVP_CIPHER-SEED 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER\-SEED \- The SEED EVP_CIPHER implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for SEED symmetric encryption using the \fBEVP_CIPHER\fR API. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the legacy provider: +.IP """SEED\-CBC"" or ""SEED""" 4 +.IX Item """SEED-CBC"" or ""SEED""" +.PD 0 +.IP """SEED\-ECB""" 4 +.IX Item """SEED-ECB""" +.IP """SEED\-OFB"" or ""SEED\-OFB128""" 4 +.IX Item """SEED-OFB"" or ""SEED-OFB128""" +.IP """SEED\-CFB"" or ""SEED\-CFB128""" 4 +.IX Item """SEED-CFB"" or ""SEED-CFB128""" +.PD +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the parameters described in +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_CIPHER-SM4.7 b/static/netbsd/man7/EVP_CIPHER-SM4.7 new file mode 100644 index 00000000..c024502f --- /dev/null +++ b/static/netbsd/man7/EVP_CIPHER-SM4.7 @@ -0,0 +1,116 @@ +.\" $NetBSD: EVP_CIPHER-SM4.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER-SM4 7" +.TH EVP_CIPHER-SM4 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER\-SM4 \- The SM4 EVP_CIPHER implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for SM4 symmetric encryption using the \fBEVP_CIPHER\fR API. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +The following algorithms are available in the default provider: +.IP """SM4\-CBC:SM4""" 4 +.IX Item """SM4-CBC:SM4""" +.PD 0 +.IP """SM4\-ECB""" 4 +.IX Item """SM4-ECB""" +.IP """SM4\-CTR""" 4 +.IX Item """SM4-CTR""" +.IP """SM4\-OFB"" or ""SM4\-OFB128""" 4 +.IX Item """SM4-OFB"" or ""SM4-OFB128""" +.IP """SM4\-CFB"" or ""SM4\-CFB128""" 4 +.IX Item """SM4-CFB"" or ""SM4-CFB128""" +.IP """SM4\-GCM""" 4 +.IX Item """SM4-GCM""" +.IP """SM4\-CCM""" 4 +.IX Item """SM4-CCM""" +.IP """SM4\-XTS""" 4 +.IX Item """SM4-XTS""" +.PD +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the parameters described in +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.SH NOTES +.IX Header "NOTES" +The SM4\-XTS implementation allows streaming to be performed, but each +\&\fBEVP_EncryptUpdate\fR\|(3) or \fBEVP_DecryptUpdate\fR\|(3) call requires each input +to be a multiple of the blocksize. Only the final \fBEVP_EncryptUpdate()\fR or +\&\fBEVP_DecryptUpdate()\fR call can optionally have an input that is not a multiple +of the blocksize but is larger than one block. In that case ciphertext +stealing (CTS) is used to fill the block. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-ARGON2.7 b/static/netbsd/man7/EVP_KDF-ARGON2.7 new file mode 100644 index 00000000..c3c99a44 --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-ARGON2.7 @@ -0,0 +1,241 @@ +.\" $NetBSD: EVP_KDF-ARGON2.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-ARGON2 7" +.TH EVP_KDF-ARGON2 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-ARGON2 \- The Argon2 EVP KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing the \fBargon2\fR password\-based KDF through the \fBEVP_KDF\fR +API. +.PP +The EVP_KDF\-ARGON2 algorithm implements the Argon2 password\-based key +derivation function, as described in IETF RFC 9106. It is memory\-hard in +the sense that it deliberately requires a significant amount of RAM for efficient +computation. The intention of this is to render brute forcing of passwords on +systems that lack large amounts of main memory (such as GPUs or ASICs) +computationally infeasible. +.PP +Argon2d (Argon2i) uses data\-dependent (data\-independent) memory access and +primary seek to address trade\-off (side\-channel) attacks. +.PP +Argon2id is a hybrid construction which, in the first two slices of the first +pass, generates reference addresses data\-independently as in Argon2i, whereas +in later slices and next passes it generates them data\-dependently as in +Argon2d. +.PP +Sbox\-hardened version Argon2ds is not supported. +.PP +For more information, please refer to RFC 9106. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """pass"" (\fBOSSL_KDF_PARAM_PASSWORD\fR) " 4 +.IX Item """pass"" (OSSL_KDF_PARAM_PASSWORD) " +.PD 0 +.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) " 4 +.IX Item """salt"" (OSSL_KDF_PARAM_SALT) " +.IP """secret"" (\fBOSSL_KDF_PARAM_SECRET\fR) " 4 +.IX Item """secret"" (OSSL_KDF_PARAM_SECRET) " +.IP """iter"" (\fBOSSL_KDF_PARAM_ITER\fR) " 4 +.IX Item """iter"" (OSSL_KDF_PARAM_ITER) " +.IP """size"" (\fBOSSL_KDF_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_KDF_PARAM_SIZE) " +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.Sp +Note that RFC 9106 recommends 128 bits salt for most applications, or 64 bits +salt in the case of space constraints. At least 128 bits output length is +recommended. +.Sp +Note that secret (or pepper) is an optional secret data used along the +password. +.IP """threads"" (\fBOSSL_KDF_PARAM_THREADS\fR) " 4 +.IX Item """threads"" (OSSL_KDF_PARAM_THREADS) " +The number of threads, bounded above by the number of lanes. +.Sp +This can only be used with built\-in thread support. Threading must be +explicitly enabled. See EXAMPLES section for more information. +.IP """ad"" (\fBOSSL_KDF_PARAM_ARGON2_AD\fR) " 4 +.IX Item """ad"" (OSSL_KDF_PARAM_ARGON2_AD) " +Optional associated data, may be used to "tag" a group of keys, or tie them +to a particular public key, without having to modify salt. +.IP """lanes"" (\fBOSSL_KDF_PARAM_ARGON2_LANES\fR) " 4 +.IX Item """lanes"" (OSSL_KDF_PARAM_ARGON2_LANES) " +Argon2 splits the requested memory size into lanes, each of which is designed +to be processed in parallel. For example, on a system with p cores, it\*(Aqs +recommended to use p lanes. +.Sp +The number of lanes is used to derive the key. It is possible to specify +more lanes than the number of available computational threads. This is +especially encouraged if multi\-threading is disabled. +.IP """memcost"" (\fBOSSL_KDF_PARAM_ARGON2_MEMCOST\fR) " 4 +.IX Item """memcost"" (OSSL_KDF_PARAM_ARGON2_MEMCOST) " +Memory cost parameter (the number of 1k memory blocks used). +.IP """version"" (\fBOSSL_KDF_PARAM_ARGON2_VERSION\fR) " 4 +.IX Item """version"" (OSSL_KDF_PARAM_ARGON2_VERSION) " +Argon2 version. Supported values: 0x10, 0x13 (default). +.IP """early_clean"" (\fBOSSL_KDF_PARAM_EARLY_CLEAN\fR) " 4 +.IX Item """early_clean"" (OSSL_KDF_PARAM_EARLY_CLEAN) " +If set (nonzero), password and secret stored in Argon2 context are zeroed +early during initial hash computation, as soon as they are not needed. +Otherwise, they are zeroed along the rest of Argon2 context data on clear, +free, reset. +.Sp +This can be useful if, for example, multiple keys with different ad value +are to be generated from a single password and secret. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example uses Argon2d with password "1234567890", salt "saltsalt", +using 2 lanes, 2 threads, and memory cost of 65536: +.PP +.Vb 5 +\& #include /* strlen */ +\& #include /* OSSL_KDF_* */ +\& #include /* OSSL_PARAM_* */ +\& #include /* OSSL_set_max_threads */ +\& #include /* EVP_KDF_* */ +\& +\& int main(void) +\& { +\& int retval = 1; +\& +\& EVP_KDF *kdf = NULL; +\& EVP_KDF_CTX *kctx = NULL; +\& OSSL_PARAM params[6], *p = params; +\& +\& /* argon2 params, please refer to RFC9106 for recommended defaults */ +\& uint32_t lanes = 2, threads = 2, memcost = 65536; +\& char pwd[] = "1234567890", salt[] = "saltsalt"; +\& +\& /* derive result */ +\& size_t outlen = 128; +\& unsigned char result[outlen]; +\& +\& /* required if threads > 1 */ +\& if (OSSL_set_max_threads(NULL, threads) != 1) +\& goto fail; +\& +\& p = params; +\& *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_THREADS, &threads); +\& *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_LANES, +\& &lanes); +\& *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_MEMCOST, +\& &memcost); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& salt, +\& strlen((const char *)salt)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD, +\& pwd, +\& strlen((const char *)pwd)); +\& *p++ = OSSL_PARAM_construct_end(); +\& +\& if ((kdf = EVP_KDF_fetch(NULL, "ARGON2D", NULL)) == NULL) +\& goto fail; +\& if ((kctx = EVP_KDF_CTX_new(kdf)) == NULL) +\& goto fail; +\& if (EVP_KDF_derive(kctx, &result[0], outlen, params) != 1) +\& goto fail; +\& +\& printf("Output = %s\en", OPENSSL_buf2hexstr(result, outlen)); +\& retval = 0; +\& +\& fail: +\& EVP_KDF_free(kdf); +\& EVP_KDF_CTX_free(kctx); +\& OSSL_set_max_threads(NULL, 0); +\& +\& return retval; +\& } +.Ve +.SH NOTES +.IX Header "NOTES" +"ARGON2I", "ARGON2D", and "ARGON2ID" are the names for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 9106 Argon2, see . +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added to OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-HKDF.7 b/static/netbsd/man7/EVP_KDF-HKDF.7 new file mode 100644 index 00000000..91ef1450 --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-HKDF.7 @@ -0,0 +1,223 @@ +.\" $NetBSD: EVP_KDF-HKDF.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-HKDF 7" +.TH EVP_KDF-HKDF 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-HKDF \- The HKDF EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing the \fBHKDF\fR KDF through the \fBEVP_KDF\fR API. +.PP +The EVP_KDF\-HKDF algorithm implements the HKDF key derivation function. +HKDF follows the "extract\-then\-expand" paradigm, where the KDF logically +consists of two modules. The first stage takes the input keying material +and "extracts" from it a fixed\-length pseudorandom key K. The second stage +"expands" the key K into several additional pseudorandom keys (the output +of the KDF). +.PP +The output is considered to be keying material. +.SS Identity +.IX Subsection "Identity" +"HKDF" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.PD 0 +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) " +.IP """key"" (\fBOSSL_KDF_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_KDF_PARAM_KEY) " +.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) " 4 +.IX Item """salt"" (OSSL_KDF_PARAM_SALT) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.IP """info"" (\fBOSSL_KDF_PARAM_INFO\fR) " 4 +.IX Item """info"" (OSSL_KDF_PARAM_INFO) " +This parameter sets the info value. +The length of the context info buffer cannot exceed 1024 bytes; +this should be more than enough for any normal use of HKDF. +.IP """mode"" (\fBOSSL_KDF_PARAM_MODE\fR) or " 4 +.IX Item """mode"" (OSSL_KDF_PARAM_MODE) or " +This parameter sets the mode for the HKDF operation. +There are three modes that are currently defined: +.RS 4 +.IP """EXTRACT_AND_EXPAND"" or \fBEVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND\fR" 4 +.IX Item """EXTRACT_AND_EXPAND"" or EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND" +This is the default mode. Calling \fBEVP_KDF_derive\fR\|(3) on an EVP_KDF_CTX set +up for HKDF will perform an extract followed by an expand operation in one go. +The derived key returned will be the result after the expand operation. The +intermediate fixed\-length pseudorandom key K is not returned. +.Sp +In this mode the digest, key, salt and info values must be set before a key is +derived otherwise an error will occur. +.IP """EXTRACT_ONLY"" or \fBEVP_KDF_HKDF_MODE_EXTRACT_ONLY\fR" 4 +.IX Item """EXTRACT_ONLY"" or EVP_KDF_HKDF_MODE_EXTRACT_ONLY" +In this mode calling \fBEVP_KDF_derive\fR\|(3) will just perform the extract +operation. The value returned will be the intermediate fixed\-length pseudorandom +key K. The \fIkeylen\fR parameter must match the size of K, which can be looked +up by calling \fBEVP_KDF_CTX_get_kdf_size()\fR after setting the mode and digest. +.Sp +The digest, key and salt values must be set before a key is derived otherwise +an error will occur. +.IP """EXPAND_ONLY"" or \fBEVP_KDF_HKDF_MODE_EXPAND_ONLY\fR" 4 +.IX Item """EXPAND_ONLY"" or EVP_KDF_HKDF_MODE_EXPAND_ONLY" +In this mode calling \fBEVP_KDF_derive\fR\|(3) will just perform the expand +operation. The input key should be set to the intermediate fixed\-length +pseudorandom key K returned from a previous extract operation. +.Sp +The digest, key and info values must be set before a key is derived otherwise +an error will occur. +.RE +.RS 4 +.RE +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling EVP_KDF_derive. It returns 0 if "key\-check" +is set to 0 and the check fails. +.IP """key\-check"" (\fBOSSL_KDF_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) " +The default value of 1 causes an error during \fBEVP_KDF_CTX_set_params()\fR if the +length of used key\-derivation key (\fBOSSL_KDF_PARAM_KEY\fR) is shorter than 112 +bits. +Setting this to zero will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SH NOTES +.IX Header "NOTES" +A context for HKDF can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "HKDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of an HKDF expand operation is specified via the \fIkeylen\fR +parameter to the \fBEVP_KDF_derive\fR\|(3) function. When using +EVP_KDF_HKDF_MODE_EXTRACT_ONLY the \fIkeylen\fR parameter must equal the size of +the intermediate fixed\-length pseudorandom key otherwise an error will occur. +For that mode, the fixed output size can be looked up by calling \fBEVP_KDF_CTX_get_kdf_size()\fR +after setting the mode and digest on the \fBEVP_KDF_CTX\fR. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example derives 10 bytes using SHA\-256 with the secret key "secret", +salt value "salt" and info value "label": +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[5], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "HKDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, +\& SN_sha256, strlen(SN_sha256)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, +\& "secret", (size_t)6); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, +\& "label", (size_t)5); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& "salt", (size_t)4); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { +\& error("EVP_KDF_derive"); +\& } +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 5869 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF\-TLS13_KDF\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-HMAC-DRBG.7 b/static/netbsd/man7/EVP_KDF-HMAC-DRBG.7 new file mode 100644 index 00000000..bbb73778 --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-HMAC-DRBG.7 @@ -0,0 +1,122 @@ +.\" $NetBSD: EVP_KDF-HMAC-DRBG.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-HMAC-DRBG 7" +.TH EVP_KDF-HMAC-DRBG 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-HMAC\-DRBG +\&\- The HMAC DRBG DETERMINISTIC EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for a deterministic HMAC DRBG using the \fBEVP_KDF\fR API. This is similar +to \fBEVP_RAND\-HMAC\-DRBG\fR\|(7), but uses fixed values for its entropy and nonce +values. This is used to generate deterministic nonce value required by ECDSA +and DSA (as defined in RFC 6979). +.SS Identity +.IX Subsection "Identity" +"HMAC\-DRBG\-KDF" is the name for this implementation; it can be used +with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """digest"" (\fBOSSL_DRBG_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_DRBG_PARAM_DIGEST) " +.PD 0 +.IP """properties"" (\fBOSSL_DRBG_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_DRBG_PARAM_PROPERTIES) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.IP """entropy"" (\fBOSSL_KDF_PARAM_HMACDRBG_ENTROPY\fR) " 4 +.IX Item """entropy"" (OSSL_KDF_PARAM_HMACDRBG_ENTROPY) " +Sets the entropy bytes supplied to the HMAC\-DRBG. +.IP """nonce"" (\fBOSSL_KDF_PARAM_HMACDRBG_NONCE\fR) " 4 +.IX Item """nonce"" (OSSL_KDF_PARAM_HMACDRBG_NONCE) " +Sets the nonce bytes supplied to the HMAC\-DRBG. +.SH NOTES +.IX Header "NOTES" +A context for KDF HMAC DRBG can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "HMAC\-DRBG\-KDF", NULL); +\& EVP_KDF_CTX *kdf_ctx = EVP_KDF_CTX_new(kdf, NULL); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 6979 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The EVP_KDF\-HMAC\-DRBG functionality was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-KB.7 b/static/netbsd/man7/EVP_KDF-KB.7 new file mode 100644 index 00000000..44a2995a --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-KB.7 @@ -0,0 +1,250 @@ +.\" $NetBSD: EVP_KDF-KB.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-KB 7" +.TH EVP_KDF-KB 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-KB \- The Key\-Based EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP_KDF\-KB algorithm implements the Key\-Based key derivation function +(KBKDF). KBKDF derives a key from repeated application of a keyed MAC to an +input secret (and other optional values). +.PP +The output is considered to be keying material. +.SS Identity +.IX Subsection "Identity" +"KBKDF" is the name for this implementation; it can be used with the +\&\fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """mode"" (\fBOSSL_KDF_PARAM_MODE\fR) " 4 +.IX Item """mode"" (OSSL_KDF_PARAM_MODE) " +The mode parameter determines which flavor of KBKDF to use \- currently the +choices are "counter" and "feedback". "counter" is the default, and will be +used if unspecified. +.IP """mac"" (\fBOSSL_KDF_PARAM_MAC\fR) " 4 +.IX Item """mac"" (OSSL_KDF_PARAM_MAC) " +The value is either CMAC, HMAC, KMAC128 or KMAC256. +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) " +.PD 0 +.IP """cipher"" (\fBOSSL_KDF_PARAM_CIPHER\fR) " 4 +.IX Item """cipher"" (OSSL_KDF_PARAM_CIPHER) " +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.IP """key"" (\fBOSSL_KDF_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_KDF_PARAM_KEY) " +.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) " 4 +.IX Item """salt"" (OSSL_KDF_PARAM_SALT) " +.IP """info (\fBOSSL_KDF_PARAM_INFO\fR) " 4 +.IX Item """info (OSSL_KDF_PARAM_INFO) " +.IP """seed"" (\fBOSSL_KDF_PARAM_SEED\fR) " 4 +.IX Item """seed"" (OSSL_KDF_PARAM_SEED) " +.PD +The seed parameter is unused in counter mode. +.IP """use\-l"" (\fBOSSL_KDF_PARAM_KBKDF_USE_L\fR) " 4 +.IX Item """use-l"" (OSSL_KDF_PARAM_KBKDF_USE_L) " +Set to \fB0\fR to disable use of the optional Fixed Input data \*(AqL\*(Aq (see SP800\-108). +The default value of \fB1\fR will be used if unspecified. +.IP """use\-separator"" (\fBOSSL_KDF_PARAM_KBKDF_USE_SEPARATOR\fR) " 4 +.IX Item """use-separator"" (OSSL_KDF_PARAM_KBKDF_USE_SEPARATOR) " +Set to \fB0\fR to disable use of the optional Fixed Input data \*(Aqzero separator\*(Aq +(see SP800\-108) that is placed between the Label and Context. +The default value of \fB1\fR will be used if unspecified. +.IP """r"" (\fBOSSL_KDF_PARAM_KBKDF_R\fR) " 4 +.IX Item """r"" (OSSL_KDF_PARAM_KBKDF_R) " +Set the fixed value \*(Aqr\*(Aq, indicating the length of the counter in bits. +.Sp +Supported values are \fB8\fR, \fB16\fR, \fB24\fR, and \fB32\fR. +The default value of \fB32\fR will be used if unspecified. +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling EVP_KDF_derive. It returns 0 if "key\-check" +is set to 0 and the check fails. +.IP """key\-check"" (\fBOSSL_KDF_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) " +The default value of 1 causes an error during \fBEVP_KDF_CTX_set_params()\fR if the +length of used key\-derivation key (\fBOSSL_KDF_PARAM_KEY\fR) is shorter than 112 +bits. +Setting this to zero will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.PP +Depending on whether mac is CMAC or HMAC, either digest or cipher is required +(respectively) and the other is unused. They are unused for KMAC128 and KMAC256. +.PP +The parameters key, salt, info, and seed correspond to KI, Label, Context, and +IV (respectively) in SP800\-108. As in that document, salt, info, and seed are +optional and may be omitted. +.PP +"mac", "digest", cipher" and "properties" are described in +"PARAMETERS" in \fBEVP_KDF\fR\|(3). +.SH NOTES +.IX Header "NOTES" +A context for KBKDF can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of an KBKDF is specified via the \f(CW\*(C`keylen\*(C'\fR +parameter to the \fBEVP_KDF_derive\fR\|(3) function. +.PP +Note that currently OpenSSL only implements counter and feedback modes. Other +variants may be supported in the future. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example derives 10 bytes using COUNTER\-HMAC\-SHA256, with KI "secret", +Label "label", and Context "context". +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[6], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, +\& "SHA2\-256", 0); +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, +\& "HMAC", 0); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, +\& "secret", strlen("secret")); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& "label", strlen("label")); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, +\& "context", strlen("context")); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) +\& error("EVP_KDF_derive"); +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.PP +This example derives 10 bytes using FEEDBACK\-CMAC\-AES256, with KI "secret", +Label "label", and IV "sixteen bytes iv". +.PP +.Vb 5 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[8], *p = params; +\& unsigned char *iv = "sixteen bytes iv"; +\& +\& kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER, "AES256", 0); +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, "CMAC", 0); +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MODE, "FEEDBACK", 0); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, +\& "secret", strlen("secret")); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& "label", strlen("label")); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, +\& "context", strlen("context")); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED, +\& iv, strlen(iv)); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) +\& error("EVP_KDF_derive"); +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +NIST SP800\-108, IETF RFC 6803, IETF RFC 8009. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.PP +Support for KMAC was added in OpenSSL 3.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019 Red Hat, Inc. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-KRB5KDF.7 b/static/netbsd/man7/EVP_KDF-KRB5KDF.7 new file mode 100644 index 00000000..c681e3b2 --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-KRB5KDF.7 @@ -0,0 +1,167 @@ +.\" $NetBSD: EVP_KDF-KRB5KDF.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-KRB5KDF 7" +.TH EVP_KDF-KRB5KDF 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-KRB5KDF \- The RFC3961 Krb5 KDF EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing the \fBKRB5KDF\fR KDF through the \fBEVP_KDF\fR API. +.PP +The EVP_KDF\-KRB5KDF algorithm implements the key derivation function defined +in RFC 3961, section 5.1 and is used by Krb5 to derive session keys. +Three inputs are required to perform key derivation: a cipher, (for example +AES\-128\-CBC), the initial key, and a constant. +.SS Identity +.IX Subsection "Identity" +"KRB5KDF" is the name for this implementation; +it can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.PD 0 +.IP """cipher"" (\fBOSSL_KDF_PARAM_CIPHER\fR) " 4 +.IX Item """cipher"" (OSSL_KDF_PARAM_CIPHER) " +.IP """key"" (\fBOSSL_KDF_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_KDF_PARAM_KEY) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.IP """constant"" (\fBOSSL_KDF_PARAM_CONSTANT\fR) " 4 +.IX Item """constant"" (OSSL_KDF_PARAM_CONSTANT) " +This parameter sets the constant value for the KDF. +If a value is already set, the contents are replaced. +.SH NOTES +.IX Header "NOTES" +A context for KRB5KDF can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KRB5KDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of the KRB5KDF derivation is specified via the \fIkeylen\fR +parameter to the \fBEVP_KDF_derive\fR\|(3) function, and MUST match the key +length for the chosen cipher or an error is returned. Moreover, the +constant\*(Aqs length must not exceed the block size of the cipher. +Since the KRB5KDF output length depends on the chosen cipher, calling +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3) to obtain the requisite length returns the correct length +only after the cipher is set. Prior to that \fBEVP_MAX_KEY_LENGTH\fR is returned. +The caller must allocate a buffer of the correct length for the chosen +cipher, and pass that buffer to the \fBEVP_KDF_derive\fR\|(3) function along +with that length. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example derives a key using the AES\-128\-CBC cipher: +.PP +.Vb 7 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char key[16] = "01234..."; +\& unsigned char constant[] = "I\*(Aqm a constant"; +\& unsigned char out[16]; +\& size_t outlen = sizeof(out); +\& OSSL_PARAM params[4], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "KRB5KDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER, +\& SN_aes_128_cbc, +\& strlen(SN_aes_128_cbc)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, +\& key, (size_t)16); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_CONSTANT, +\& constant, strlen(constant)); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, outlen, params) <= 0) +\& /* Error */ +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 3961 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-PBKDF1.7 b/static/netbsd/man7/EVP_KDF-PBKDF1.7 new file mode 100644 index 00000000..2fb39753 --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-PBKDF1.7 @@ -0,0 +1,137 @@ +.\" $NetBSD: EVP_KDF-PBKDF1.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-PBKDF1 7" +.TH EVP_KDF-PBKDF1 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-PBKDF1 \- The PBKDF1 EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing the \fBPBKDF1\fR password\-based KDF through the \fBEVP_KDF\fR +API. +.PP +The EVP_KDF\-PBKDF1 algorithm implements the PBKDF1 password\-based key +derivation function, as described in RFC 8018; it derives a key from a password +using a salt and iteration count. +.SS Identity +.IX Subsection "Identity" +"PBKDF1" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """pass"" (\fBOSSL_KDF_PARAM_PASSWORD\fR) " 4 +.IX Item """pass"" (OSSL_KDF_PARAM_PASSWORD) " +.PD 0 +.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) " 4 +.IX Item """salt"" (OSSL_KDF_PARAM_SALT) " +.IP """iter"" (\fBOSSL_KDF_PARAM_ITER\fR) " 4 +.IX Item """iter"" (OSSL_KDF_PARAM_ITER) " +.PD +This parameter has a default value of 0 and should be set. +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.PD 0 +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.SH NOTES +.IX Header "NOTES" +A typical application of this algorithm is to derive keying material for an +encryption algorithm from a password in the "pass", a salt in "salt", +and an iteration count. +.PP +Increasing the "iter" parameter slows down the algorithm which makes it +harder for an attacker to perform a brute force attack using a large number +of candidate passwords. +.PP +No assumption is made regarding the given password; it is simply treated as a +byte sequence. +.PP +The legacy provider needs to be available in order to access this algorithm. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 8018 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3), +\&\fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-PBKDF2.7 b/static/netbsd/man7/EVP_KDF-PBKDF2.7 new file mode 100644 index 00000000..6c58a9bf --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-PBKDF2.7 @@ -0,0 +1,167 @@ +.\" $NetBSD: EVP_KDF-PBKDF2.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-PBKDF2 7" +.TH EVP_KDF-PBKDF2 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-PBKDF2 \- The PBKDF2 EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing the \fBPBKDF2\fR password\-based KDF through the \fBEVP_KDF\fR +API. +.PP +The EVP_KDF\-PBKDF2 algorithm implements the PBKDF2 password\-based key +derivation function, as described in SP800\-132; it derives a key from a password +using a salt and iteration count. +.PP +The output is considered to be a cryptographic key. +.SS Identity +.IX Subsection "Identity" +"PBKDF2" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """pass"" (\fBOSSL_KDF_PARAM_PASSWORD\fR) " 4 +.IX Item """pass"" (OSSL_KDF_PARAM_PASSWORD) " +.PD 0 +.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) " 4 +.IX Item """salt"" (OSSL_KDF_PARAM_SALT) " +.IP """iter"" (\fBOSSL_KDF_PARAM_ITER\fR) " 4 +.IX Item """iter"" (OSSL_KDF_PARAM_ITER) " +.PD +This parameter has a default value of 2048. +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.PD 0 +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.IP """pkcs5"" (\fBOSSL_KDF_PARAM_PKCS5\fR) " 4 +.IX Item """pkcs5"" (OSSL_KDF_PARAM_PKCS5) " +This parameter can be used to enable or disable SP800\-132 compliance checks. +Setting the mode to 0 enables the compliance checks. +.Sp +The checks performed are: +.RS 4 +.IP "\- the iteration count is at least 1000." 4 +.IX Item "- the iteration count is at least 1000." +.PD 0 +.IP "\- the salt length is at least 128 bits." 4 +.IX Item "- the salt length is at least 128 bits." +.IP "\- the derived key length is at least 112 bits." 4 +.IX Item "- the derived key length is at least 112 bits." +.PD +.RE +.RS 4 +.Sp +The default provider uses a default mode of 1 for backwards compatibility, +and the FIPS provider uses a default mode of 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.RE +.IP """fips\-indicator"" (\fBOSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) " +This option is used by the OpenSSL FIPS provider. +.Sp +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling EVP_KDF_derive. It returns 0 if "pkcs5" +is set to 1 and the derived key length, salt length or iteration count test +fails. +.SH NOTES +.IX Header "NOTES" +A typical application of this algorithm is to derive keying material for an +encryption algorithm from a password in the "pass", a salt in "salt", +and an iteration count. +.PP +Increasing the "iter" parameter slows down the algorithm which makes it +harder for an attacker to perform a brute force attack using a large number +of candidate passwords. +.PP +No assumption is made regarding the given password; it is simply treated as a +byte sequence. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +SP800\-132 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-PKCS12KDF.7 b/static/netbsd/man7/EVP_KDF-PKCS12KDF.7 new file mode 100644 index 00000000..bcb1f367 --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-PKCS12KDF.7 @@ -0,0 +1,140 @@ +.\" $NetBSD: EVP_KDF-PKCS12KDF.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-PKCS12KDF 7" +.TH EVP_KDF-PKCS12KDF 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-PKCS12KDF \- The PKCS#12 EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing the \fBPKCS#12\fR password\-based KDF through the \fBEVP_KDF\fR +API. +.PP +The EVP_KDF\-PKCS12KDF algorithm implements the PKCS#12 password\-based key +derivation function, as described in appendix B of RFC 7292 (PKCS #12: +Personal Information Exchange Syntax); it derives a key from a password +using a salt, iteration count and the intended usage. +.SS Identity +.IX Subsection "Identity" +"PKCS12KDF" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """pass"" (\fBOSSL_KDF_PARAM_PASSWORD\fR) " 4 +.IX Item """pass"" (OSSL_KDF_PARAM_PASSWORD) " +.PD 0 +.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) " 4 +.IX Item """salt"" (OSSL_KDF_PARAM_SALT) " +.IP """iter"" (\fBOSSL_KDF_PARAM_ITER\fR) " 4 +.IX Item """iter"" (OSSL_KDF_PARAM_ITER) " +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.IP """id"" (\fBOSSL_KDF_PARAM_PKCS12_ID\fR) " 4 +.IX Item """id"" (OSSL_KDF_PARAM_PKCS12_ID) " +This parameter is used to specify the intended usage of the output bits, as per +RFC 7292 section B.3. +.SH NOTES +.IX Header "NOTES" +This algorithm is not available in the FIPS provider as it is not FIPS +approvable. +.PP +A typical application of this algorithm is to derive keying material for an +encryption algorithm from a password in the "pass", a salt in "salt", +and an iteration count. +.PP +Increasing the "iter" parameter slows down the algorithm which makes it +harder for an attacker to perform a brute force attack using a large number +of candidate passwords. +.PP +No assumption is made regarding the given password; it is simply treated as a +byte sequence. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC7292 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-PVKKDF.7 b/static/netbsd/man7/EVP_KDF-PVKKDF.7 new file mode 100644 index 00000000..f3846f52 --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-PVKKDF.7 @@ -0,0 +1,123 @@ +.\" $NetBSD: EVP_KDF-PVKKDF.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-PVKKDF 7" +.TH EVP_KDF-PVKKDF 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-PVKKDF \- The PVK EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing the \fBPVK KDF\fR PIN\-based KDF through the \fBEVP_KDF\fR +API. +.PP +The EVP_KDF\-PVKKDF algorithm implements a PVK PIN\-based key +derivation function; it derives a key from a password using a salt. +.SS Identity +.IX Subsection "Identity" +"PVKKDF" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """pass"" (\fBOSSL_KDF_PARAM_PASSWORD\fR) " 4 +.IX Item """pass"" (OSSL_KDF_PARAM_PASSWORD) " +.PD 0 +.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) " 4 +.IX Item """salt"" (OSSL_KDF_PARAM_SALT) " +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.SH NOTES +.IX Header "NOTES" +A typical application of this algorithm is to derive keying material for an +encryption algorithm from a password in the "pass" and a salt in "salt". +.PP +No assumption is made regarding the given password; it is simply treated as a +byte sequence. +.PP +The legacy provider needs to be available in order to access this algorithm. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3), +\&\fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-SCRYPT.7 b/static/netbsd/man7/EVP_KDF-SCRYPT.7 new file mode 100644 index 00000000..03773638 --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-SCRYPT.7 @@ -0,0 +1,204 @@ +.\" $NetBSD: EVP_KDF-SCRYPT.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-SCRYPT 7" +.TH EVP_KDF-SCRYPT 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-SCRYPT \- The scrypt EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing the \fBscrypt\fR password\-based KDF through the \fBEVP_KDF\fR +API. +.PP +The EVP_KDF\-SCRYPT algorithm implements the scrypt password\-based key +derivation function, as described in RFC 7914. It is memory\-hard in the sense +that it deliberately requires a significant amount of RAM for efficient +computation. The intention of this is to render brute forcing of passwords on +systems that lack large amounts of main memory (such as GPUs or ASICs) +computationally infeasible. +.PP +scrypt provides three work factors that can be customized: N, r and p. N, which +has to be a positive power of two, is the general work factor and scales CPU +time in an approximately linear fashion. r is the block size of the internally +used hash function and p is the parallelization factor. Both r and p need to be +greater than zero. The amount of RAM that scrypt requires for its computation +is roughly (128 * N * r * p) bytes. +.PP +In the original paper of Colin Percival ("Stronger Key Derivation via +Sequential Memory\-Hard Functions", 2009), the suggested values that give a +computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N = +2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for +this computation is roughly 1 GiB. On a more recent CPU (Intel i7\-5930K at 3.5 +GHz), this computation takes about 3 seconds. When N, r or p are not specified, +they default to 1048576, 8, and 1, respectively. The maximum amount of RAM that +may be used by scrypt defaults to 1025 MiB. +.SS Identity +.IX Subsection "Identity" +"SCRYPT" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """pass"" (\fBOSSL_KDF_PARAM_PASSWORD\fR) " 4 +.IX Item """pass"" (OSSL_KDF_PARAM_PASSWORD) " +.PD 0 +.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) " 4 +.IX Item """salt"" (OSSL_KDF_PARAM_SALT) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.IP """n"" (\fBOSSL_KDF_PARAM_SCRYPT_N\fR) " 4 +.IX Item """n"" (OSSL_KDF_PARAM_SCRYPT_N) " +.PD 0 +.IP """r"" (\fBOSSL_KDF_PARAM_SCRYPT_R\fR) " 4 +.IX Item """r"" (OSSL_KDF_PARAM_SCRYPT_R) " +.IP """p"" (\fBOSSL_KDF_PARAM_SCRYPT_P\fR) " 4 +.IX Item """p"" (OSSL_KDF_PARAM_SCRYPT_P) " +.IP """maxmem_bytes"" (\fBOSSL_KDF_PARAM_SCRYPT_MAXMEM\fR) " 4 +.IX Item """maxmem_bytes"" (OSSL_KDF_PARAM_SCRYPT_MAXMEM) " +.PD +These parameters configure the scrypt work factors N, r, maxmem and p. +Both N and maxmem_bytes are parameters of type \fBuint64_t\fR. +Both r and p are parameters of type \fBuint32_t\fR. +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +This can be used to set the property query string when fetching the +fixed digest internally. NULL is used if this value is not set. +.SH NOTES +.IX Header "NOTES" +A context for scrypt can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of an scrypt key derivation is specified via the +"keylen" parameter to the \fBEVP_KDF_derive\fR\|(3) function. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example derives a 64\-byte long test vector using scrypt with the password +"password", salt "NaCl" and N = 1024, r = 8, p = 16. +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[64]; +\& OSSL_PARAM params[6], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD, +\& "password", (size_t)8); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& "NaCl", (size_t)4); +\& *p++ = OSSL_PARAM_construct_uint64(OSSL_KDF_PARAM_SCRYPT_N, (uint64_t)1024); +\& *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_R, (uint32_t)8); +\& *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_P, (uint32_t)16); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { +\& error("EVP_KDF_derive"); +\& } +\& +\& { +\& const unsigned char expected[sizeof(out)] = { +\& 0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00, +\& 0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe, +\& 0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30, +\& 0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62, +\& 0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88, +\& 0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda, +\& 0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d, +\& 0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40 +\& }; +\& +\& assert(!memcmp(out, expected, sizeof(out))); +\& } +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 7914 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-SS.7 b/static/netbsd/man7/EVP_KDF-SS.7 new file mode 100644 index 00000000..ccb2a3b8 --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-SS.7 @@ -0,0 +1,260 @@ +.\" $NetBSD: EVP_KDF-SS.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-SS 7" +.TH EVP_KDF-SS 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-SS \- The Single Step / One Step EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP_KDF\-SS algorithm implements the Single Step key derivation function (SSKDF). +SSKDF derives a key using input such as a shared secret key (that was generated +during the execution of a key establishment scheme) and fixedinfo. +SSKDF is also informally referred to as \*(AqConcat KDF\*(Aq. +.PP +The output is considered to be keying material. +.SS "Auxiliary function" +.IX Subsection "Auxiliary function" +The implementation uses a selectable auxiliary function H, which can be one of: +.IP "\fBH(x) = hash(x, digest=md)\fR" 4 +.IX Item "H(x) = hash(x, digest=md)" +.PD 0 +.IP "\fBH(x) = HMAC_hash(x, key=salt, digest=md)\fR" 4 +.IX Item "H(x) = HMAC_hash(x, key=salt, digest=md)" +.IP "\fBH(x) = KMACxxx(x, key=salt, custom=""KDF"", outlen=mac_size)\fR" 4 +.IX Item "H(x) = KMACxxx(x, key=salt, custom=""KDF"", outlen=mac_size)" +.PD +.PP +Both the HMAC and KMAC implementations set the key using the \*(Aqsalt\*(Aq value. +The hash and HMAC also require the digest to be set. +.SS Identity +.IX Subsection "Identity" +"SSKDF" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.PD 0 +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) " +.PD +This parameter is ignored for KMAC. +.IP """mac"" (\fBOSSL_KDF_PARAM_MAC\fR) " 4 +.IX Item """mac"" (OSSL_KDF_PARAM_MAC) " +.PD 0 +.IP """maclen"" (\fBOSSL_KDF_PARAM_MAC_SIZE\fR) " 4 +.IX Item """maclen"" (OSSL_KDF_PARAM_MAC_SIZE) " +.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) " 4 +.IX Item """salt"" (OSSL_KDF_PARAM_SALT) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.IP """key"" (\fBOSSL_KDF_PARAM_SECRET\fR) " 4 +.IX Item """key"" (OSSL_KDF_PARAM_SECRET) " +This parameter set the shared secret that is used for key derivation. +.IP """info"" (\fBOSSL_KDF_PARAM_INFO\fR) " 4 +.IX Item """info"" (OSSL_KDF_PARAM_INFO) " +This parameter sets an optional value for fixedinfo, also known as otherinfo. +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling EVP_KDF_derive. It returns 0 if "key\-check" +is set to 0 and the check fails. +.IP """key\-check"" (\fBOSSL_KDF_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) " +The default value of 1 causes an error during \fBEVP_KDF_CTX_set_params()\fR if the +length of used key\-derivation key (\fBOSSL_KDF_PARAM_KEY\fR) is shorter than 112 +bits. +Setting this to zero will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SH NOTES +.IX Header "NOTES" +A context for SSKDF can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of an SSKDF is specified via the \fIkeylen\fR +parameter to the \fBEVP_KDF_derive\fR\|(3) function. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example derives 10 bytes using H(x) = SHA\-256, with the secret key "secret" +and fixedinfo value "label": +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[4], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, +\& SN_sha256, strlen(SN_sha256)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, +\& "secret", (size_t)6); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, +\& "label", (size_t)5); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { +\& error("EVP_KDF_derive"); +\& } +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.PP +This example derives 10 bytes using H(x) = HMAC(SHA\-256), with the secret key "secret", +fixedinfo value "label" and salt "salt": +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[6], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, +\& SN_hmac, strlen(SN_hmac)); +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, +\& SN_sha256, strlen(SN_sha256)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, +\& "secret", (size_t)6); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, +\& "label", (size_t)5); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& "salt", (size_t)4); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { +\& error("EVP_KDF_derive"); +\& } +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.PP +This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret" +fixedinfo value "label", salt of "salt" and KMAC outlen of 20: +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[6], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, +\& SN_kmac128, strlen(SN_kmac128)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, +\& "secret", (size_t)6); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, +\& "label", (size_t)5); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& "salt", (size_t)4); +\& *p++ = OSSL_PARAM_construct_size_t(OSSL_KDF_PARAM_MAC_SIZE, (size_t)20); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { +\& error("EVP_KDF_derive"); +\& } +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +NIST SP800\-56Cr1. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. Copyright +(c) 2019, Oracle and/or its affiliates. All rights reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-SSHKDF.7 b/static/netbsd/man7/EVP_KDF-SSHKDF.7 new file mode 100644 index 00000000..57cb40f4 --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-SSHKDF.7 @@ -0,0 +1,236 @@ +.\" $NetBSD: EVP_KDF-SSHKDF.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-SSHKDF 7" +.TH EVP_KDF-SSHKDF 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-SSHKDF \- The SSHKDF EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing the \fBSSHKDF\fR KDF through the \fBEVP_KDF\fR API. +.PP +The EVP_KDF\-SSHKDF algorithm implements the SSHKDF key derivation function. +It is defined in RFC 4253, section 7.2 and is used by SSH to derive IVs, +encryption keys and integrity keys. +Five inputs are required to perform key derivation: The hashing function +(for example SHA256), the Initial Key, the Exchange Hash, the Session ID, +and the derivation key type. +.PP +The output is considered to be keying material. +.SS Identity +.IX Subsection "Identity" +"SSHKDF" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.PD 0 +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) " +.IP """key"" (\fBOSSL_KDF_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_KDF_PARAM_KEY) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.IP """xcghash"" (\fBOSSL_KDF_PARAM_SSHKDF_XCGHASH\fR) " 4 +.IX Item """xcghash"" (OSSL_KDF_PARAM_SSHKDF_XCGHASH) " +.PD 0 +.IP """session_id"" (\fBOSSL_KDF_PARAM_SSHKDF_SESSION_ID\fR) " 4 +.IX Item """session_id"" (OSSL_KDF_PARAM_SSHKDF_SESSION_ID) " +.PD +These parameters set the respective values for the KDF. +If a value is already set, the contents are replaced. +.IP """type"" (\fBOSSL_KDF_PARAM_SSHKDF_TYPE\fR) " 4 +.IX Item """type"" (OSSL_KDF_PARAM_SSHKDF_TYPE) " +This parameter sets the type for the SSHKDF operation. +There are six supported types: +.RS 4 +.IP EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV" +The Initial IV from client to server. +A single char of value 65 (ASCII char \*(AqA\*(Aq). +.IP EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI" +The Initial IV from server to client +A single char of value 66 (ASCII char \*(AqB\*(Aq). +.IP EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV" +The Encryption Key from client to server +A single char of value 67 (ASCII char \*(AqC\*(Aq). +.IP EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI" +The Encryption Key from server to client +A single char of value 68 (ASCII char \*(AqD\*(Aq). +.IP EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV" +The Integrity Key from client to server +A single char of value 69 (ASCII char \*(AqE\*(Aq). +.IP EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI" +The Integrity Key from client to server +A single char of value 70 (ASCII char \*(AqF\*(Aq). +.RE +.RS 4 +.RE +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling EVP_KDF_derive. It returns 0 if any "***\-check" +related parameter is set to 0 and the check fails. +.IP """digest\-check"" (\fBOSSL_KDF_PARAM_FIPS_DIGEST_CHECK\fR) " 4 +.IX Item """digest-check"" (OSSL_KDF_PARAM_FIPS_DIGEST_CHECK) " +The default value of 1 causes an error during \fBEVP_KDF_CTX_set_params()\fR if +used digest is not approved. +Setting this to zero will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.Sp +According to SP 800\-135r1, the following are approved digest algorithms: SHA\-1, +SHA2\-224, SHA2\-256, SHA2\-384, SHA2\-512. +.IP """key\-check"" (\fBOSSL_KDF_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) " +The default value of 1 causes an error during \fBEVP_KDF_CTX_set_params()\fR if the +length of used key\-derivation key (\fBOSSL_KDF_PARAM_KEY\fR) is shorter than 112 +bits. +Setting this to zero will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SH NOTES +.IX Header "NOTES" +A context for SSHKDF can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of the SSHKDF derivation is specified via the \fIkeylen\fR +parameter to the \fBEVP_KDF_derive\fR\|(3) function. +Since the SSHKDF output length is variable, calling \fBEVP_KDF_CTX_get_kdf_size\fR\|(3) +to obtain the requisite length is not meaningful. The caller must +allocate a buffer of the desired length, and pass that buffer to the +\&\fBEVP_KDF_derive\fR\|(3) function along with the desired length. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example derives an 8 byte IV using SHA\-256 with a 1K "key" and appropriate +"xcghash" and "session_id" values: +.PP +.Vb 9 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& char type = EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV; +\& unsigned char key[1024] = "01234..."; +\& unsigned char xcghash[32] = "012345..."; +\& unsigned char session_id[32] = "012345..."; +\& unsigned char out[8]; +\& size_t outlen = sizeof(out); +\& OSSL_PARAM params[6], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, +\& SN_sha256, strlen(SN_sha256)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, +\& key, (size_t)1024); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_XCGHASH, +\& xcghash, (size_t)32); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_SESSION_ID, +\& session_id, (size_t)32); +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_SSHKDF_TYPE, +\& &type, sizeof(type)); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, outlen, params) <= 0) +\& /* Error */ +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 4253 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-TLS13_KDF.7 b/static/netbsd/man7/EVP_KDF-TLS13_KDF.7 new file mode 100644 index 00000000..3e4e0032 --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-TLS13_KDF.7 @@ -0,0 +1,208 @@ +.\" $NetBSD: EVP_KDF-TLS13_KDF.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-TLS13_KDF 7" +.TH EVP_KDF-TLS13_KDF 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-TLS13_KDF \- The TLS 1.3 EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing the TLS 1.3 version of the \fBHKDF\fR KDF through +the \fBEVP_KDF\fR API. +.PP +The EVP_KDF\-TLS13_KDF algorithm implements the HKDF key derivation function +as used by TLS 1.3. +.PP +The output is considered to be keying material. +.SS Identity +.IX Subsection "Identity" +"TLS13\-KDF" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.PD 0 +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) " +.IP """key"" (\fBOSSL_KDF_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_KDF_PARAM_KEY) " +.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) " 4 +.IX Item """salt"" (OSSL_KDF_PARAM_SALT) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.IP """prefix"" (\fBOSSL_KDF_PARAM_PREFIX\fR) " 4 +.IX Item """prefix"" (OSSL_KDF_PARAM_PREFIX) " +This parameter sets the label prefix on the specified TLS 1.3 KDF context. +For TLS 1.3 this should be set to the ASCII string "tls13 " without a +trailing zero byte. Refer to RFC 8446 section 7.1 "Key Schedule" for details. +.IP """label"" (\fBOSSL_KDF_PARAM_LABEL\fR) " 4 +.IX Item """label"" (OSSL_KDF_PARAM_LABEL) " +This parameter sets the label on the specified TLS 1.3 KDF context. +Refer to RFC 8446 section 7.1 "Key Schedule" for details. +.IP """data"" (\fBOSSL_KDF_PARAM_DATA\fR) " 4 +.IX Item """data"" (OSSL_KDF_PARAM_DATA) " +This parameter sets the context data on the specified TLS 1.3 KDF context. +Refer to RFC 8446 section 7.1 "Key Schedule" for details. +.IP """mode"" (\fBOSSL_KDF_PARAM_MODE\fR) or " 4 +.IX Item """mode"" (OSSL_KDF_PARAM_MODE) or " +This parameter sets the mode for the TLS 1.3 KDF operation. +There are two modes that are currently defined: +.RS 4 +.IP """EXTRACT_ONLY"" or \fBEVP_KDF_HKDF_MODE_EXTRACT_ONLY\fR" 4 +.IX Item """EXTRACT_ONLY"" or EVP_KDF_HKDF_MODE_EXTRACT_ONLY" +In this mode calling \fBEVP_KDF_derive\fR\|(3) will just perform the extract +operation. The value returned will be the intermediate fixed\-length pseudorandom +key K. The \fIkeylen\fR parameter must match the size of K, which can be looked +up by calling \fBEVP_KDF_CTX_get_kdf_size()\fR after setting the mode and digest. +.Sp +The digest, key and salt values must be set before a key is derived otherwise +an error will occur. +.IP """EXPAND_ONLY"" or \fBEVP_KDF_HKDF_MODE_EXPAND_ONLY\fR" 4 +.IX Item """EXPAND_ONLY"" or EVP_KDF_HKDF_MODE_EXPAND_ONLY" +In this mode calling \fBEVP_KDF_derive\fR\|(3) will just perform the expand +operation. The input key should be set to the intermediate fixed\-length +pseudorandom key K returned from a previous extract operation. +.Sp +The digest, key and info values must be set before a key is derived otherwise +an error will occur. +.RE +.RS 4 +.RE +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling EVP_KDF_derive. It returns 0 if any "***\-check" +related parameter is set to 0 and the check fails. +.IP """digest\-check"" (\fBOSSL_KDF_PARAM_FIPS_DIGEST_CHECK\fR) " 4 +.IX Item """digest-check"" (OSSL_KDF_PARAM_FIPS_DIGEST_CHECK) " +The default value of 1 causes an error during \fBEVP_KDF_CTX_set_params()\fR if +used digest is not approved. +Setting this to zero will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.Sp +According to RFC 8446, the following are approved digest algorithms: SHA2\-256, +SHA2\-384. +.IP """key\-check"" (\fBOSSL_KDF_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) " +The default value of 1 causes an error during \fBEVP_KDF_CTX_set_params()\fR if the +length of used key\-derivation key (\fBOSSL_KDF_PARAM_KEY\fR) is shorter than 112 +bits. +Setting this to zero will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SH NOTES +.IX Header "NOTES" +This KDF is intended for use by the TLS 1.3 implementation in libssl. +It does not support all the options and capabilities that HKDF does. +.PP +The \fIOSSL_PARAM\fR array passed to \fBEVP_KDF_derive\fR\|(3) or +\&\fBEVP_KDF_CTX_set_params\fR\|(3) must specify all of the parameters required. +This KDF does not support a piecemeal approach to providing these. +.PP +A context for a TLS 1.3 KDF can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS13\-KDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of a TLS 1.3 KDF expand operation is specified via the +\&\fIkeylen\fR parameter to the \fBEVP_KDF_derive\fR\|(3) function. When using +EVP_KDF_HKDF_MODE_EXTRACT_ONLY the \fIkeylen\fR parameter must equal the size of +the intermediate fixed\-length pseudorandom key otherwise an error will occur. +For that mode, the fixed output size can be looked up by calling +\&\fBEVP_KDF_CTX_get_kdf_size()\fR after setting the mode and digest on the +\&\fBEVP_KDF_CTX\fR. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 8446 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF\-HKDF\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-TLS1_PRF.7 b/static/netbsd/man7/EVP_KDF-TLS1_PRF.7 new file mode 100644 index 00000000..40cb6829 --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-TLS1_PRF.7 @@ -0,0 +1,202 @@ +.\" $NetBSD: EVP_KDF-TLS1_PRF.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-TLS1_PRF 7" +.TH EVP_KDF-TLS1_PRF 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-TLS1_PRF \- The TLS1 PRF EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing the \fBTLS1\fR PRF through the \fBEVP_KDF\fR API. +.PP +The EVP_KDF\-TLS1_PRF algorithm implements the PRF used by TLS versions up to +and including TLS 1.2. +.PP +The output is considered to be keying material. +.SS Identity +.IX Subsection "Identity" +"TLS1\-PRF" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.PD 0 +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.Sp +The \fBOSSL_KDF_PARAM_DIGEST\fR parameter is used to set the message digest +associated with the TLS PRF. +\&\fBEVP_md5_sha1()\fR is treated as a special case which uses the +PRF algorithm using both \fBMD5\fR and \fBSHA1\fR as used in TLS 1.0 and 1.1. +.IP """secret"" (\fBOSSL_KDF_PARAM_SECRET\fR) " 4 +.IX Item """secret"" (OSSL_KDF_PARAM_SECRET) " +This parameter sets the secret value of the TLS PRF. +Any existing secret value is replaced. +.IP """seed"" (\fBOSSL_KDF_PARAM_SEED\fR) " 4 +.IX Item """seed"" (OSSL_KDF_PARAM_SEED) " +This parameter sets the context seed. +The length of the context seed cannot exceed 1024 bytes; +this should be more than enough for any normal use of the TLS PRF. +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling EVP_KDF_derive. It returns 0 if any "***\-check" +related parameter is set to 0 and the check fails. +.IP """ems_check"" (\fBOSSL_KDF_PARAM_FIPS_EMS_CHECK\fR) " 4 +.IX Item """ems_check"" (OSSL_KDF_PARAM_FIPS_EMS_CHECK) " +The default value of 1 causes an error during \fBEVP_KDF_derive()\fR if +"master secret" is used instead of "extended master secret" Setting this to zero +will ignore the error and set the approved "fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.IP """digest\-check"" (\fBOSSL_KDF_PARAM_FIPS_DIGEST_CHECK\fR) " 4 +.IX Item """digest-check"" (OSSL_KDF_PARAM_FIPS_DIGEST_CHECK) " +The default value of 1 causes an error during \fBEVP_KDF_CTX_set_params()\fR if +used digest is not approved. +Setting this to zero will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.Sp +According to SP 800\-135r1, the following are approved digest algorithms: +SHA2\-256, SHA2\-384, SHA2\-512. +.IP """key\-check"" (\fBOSSL_KDF_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) " +The default value of 1 causes an error during \fBEVP_KDF_CTX_set_params()\fR if the +length of used key\-derivation key (\fBOSSL_KDF_PARAM_SECRET\fR) is shorter than 112 +bits. +Setting this to zero will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SH NOTES +.IX Header "NOTES" +A context for the TLS PRF can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS1\-PRF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The digest, secret value and seed must be set before a key is derived otherwise +an error will occur. +.PP +The output length of the PRF is specified by the \fIkeylen\fR parameter to the +\&\fBEVP_KDF_derive()\fR function. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example derives 10 bytes using SHA\-256 with the secret key "secret" +and seed value "seed": +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[4], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "TLS1\-PRF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, +\& SN_sha256, strlen(SN_sha256)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, +\& "secret", (size_t)6); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED, +\& "seed", (size_t)4); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { +\& error("EVP_KDF_derive"); +\& } +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 2246, RFC 5246 and NIST SP 800\-135 r1 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-X942-ASN1.7 b/static/netbsd/man7/EVP_KDF-X942-ASN1.7 new file mode 100644 index 00000000..11cd54ca --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-X942-ASN1.7 @@ -0,0 +1,214 @@ +.\" $NetBSD: EVP_KDF-X942-ASN1.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-X942-ASN1 7" +.TH EVP_KDF-X942-ASN1 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-X942\-ASN1 \- The X9.42\-2003 asn1 EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP_KDF\-X942\-ASN1 algorithm implements the key derivation function +X942KDF\-ASN1. It is used by DH KeyAgreement, to derive a key using input such as +a shared secret key and other info. The other info is DER encoded data that +contains a 32 bit counter as well as optional fields for "partyu\-info", +"partyv\-info", "supp\-pubinfo" and "supp\-privinfo". +This kdf is used by Cryptographic Message Syntax (CMS). +.PP +The output is considered to be keying material. +.SS Identity +.IX Subsection "Identity" +"X942KDF\-ASN1" or "X942KDF" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.PD 0 +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.IP """secret"" (\fBOSSL_KDF_PARAM_SECRET\fR) " 4 +.IX Item """secret"" (OSSL_KDF_PARAM_SECRET) " +The shared secret used for key derivation. This parameter sets the secret. +.IP """acvp\-info"" (\fBOSSL_KDF_PARAM_X942_ACVPINFO\fR) " 4 +.IX Item """acvp-info"" (OSSL_KDF_PARAM_X942_ACVPINFO) " +This value should not be used in production and should only be used for ACVP +testing. It is an optional octet string containing a combined DER encoded blob +of any of the optional fields related to "partyu\-info", "partyv\-info", +"supp\-pubinfo" and "supp\-privinfo". If it is specified then none of these other +fields should be used. +.IP """partyu\-info"" (\fBOSSL_KDF_PARAM_X942_PARTYUINFO\fR) " 4 +.IX Item """partyu-info"" (OSSL_KDF_PARAM_X942_PARTYUINFO) " +An optional octet string containing public info contributed by the initiator. +.IP """ukm"" (\fBOSSL_KDF_PARAM_UKM\fR) " 4 +.IX Item """ukm"" (OSSL_KDF_PARAM_UKM) " +An alias for "partyu\-info". +In CMS this is the user keying material. +.IP """partyv\-info"" (\fBOSSL_KDF_PARAM_X942_PARTYVINFO\fR) " 4 +.IX Item """partyv-info"" (OSSL_KDF_PARAM_X942_PARTYVINFO) " +An optional octet string containing public info contributed by the responder. +.IP """supp\-pubinfo"" (\fBOSSL_KDF_PARAM_X942_SUPP_PUBINFO\fR) " 4 +.IX Item """supp-pubinfo"" (OSSL_KDF_PARAM_X942_SUPP_PUBINFO) " +An optional octet string containing some additional, mutually\-known public +information. Setting this value also sets "use\-keybits" to 0. +.IP """use\-keybits"" (\fBOSSL_KDF_PARAM_X942_USE_KEYBITS\fR) " 4 +.IX Item """use-keybits"" (OSSL_KDF_PARAM_X942_USE_KEYBITS) " +The default value of 1 will use the KEK key length (in bits) as the +"supp\-pubinfo". A value of 0 disables setting the "supp\-pubinfo". +.IP """supp\-privinfo"" (\fBOSSL_KDF_PARAM_X942_SUPP_PRIVINFO\fR) " 4 +.IX Item """supp-privinfo"" (OSSL_KDF_PARAM_X942_SUPP_PRIVINFO) " +An optional octet string containing some additional, mutually\-known private +information. +.IP """cekalg"" (\fBOSSL_KDF_PARAM_CEK_ALG\fR) " 4 +.IX Item """cekalg"" (OSSL_KDF_PARAM_CEK_ALG) " +This parameter sets the CEK wrapping algorithm name. +Valid values are "AES\-128\-WRAP", "AES\-192\-WRAP", "AES\-256\-WRAP" and "DES3\-WRAP". +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling EVP_KDF_derive. It returns 0 if "key\-check" +parameter is set to 0 and the check fails. +.IP """key\-check"" (\fBOSSL_KDF_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) " +The default value of 1 causes an error during \fBEVP_KDF_CTX_set_params()\fR if the +length of used key\-derivation key (\fBOSSL_KDF_PARAM_KEY\fR) is shorter than 112 +bits. +Setting this to zero will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SH NOTES +.IX Header "NOTES" +A context for X942KDF can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of an X942KDF is specified via the \fIkeylen\fR +parameter to the \fBEVP_KDF_derive\fR\|(3) function. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example derives 24 bytes, with the secret key "secret" and random user +keying material: +.PP +.Vb 5 +\& EVP_KDF_CTX *kctx; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[192/8]; +\& unsignred char ukm[64]; +\& OSSL_PARAM params[5], *p = params; +\& +\& if (RAND_bytes(ukm, sizeof(ukm)) <= 0) +\& error("RAND_bytes"); +\& +\& kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL); +\& if (kctx == NULL) +\& error("EVP_KDF_fetch"); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& if (kctx == NULL) +\& error("EVP_KDF_CTX_new"); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, "SHA256", 0); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, +\& "secret", (size_t)6); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_UKM, ukm, sizeof(ukm)); +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CEK_ALG, "AES\-256\-WRAP, 0); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) +\& error("EVP_KDF_derive"); +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +ANS1 X9.42\-2003 +RFC 2631 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-X942-CONCAT.7 b/static/netbsd/man7/EVP_KDF-X942-CONCAT.7 new file mode 100644 index 00000000..ac43cd13 --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-X942-CONCAT.7 @@ -0,0 +1,93 @@ +.\" $NetBSD: EVP_KDF-X942-CONCAT.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-X942-CONCAT 7" +.TH EVP_KDF-X942-CONCAT 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-X942\-CONCAT \- The X942 Concat EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP_KDF\-X942\-CONCAT algorithm is identical to EVP_KDF\-X963. It is +used for key agreement to derive a key using input such as a shared secret key +and shared info. +.SS Identity +.IX Subsection "Identity" +"X942KDF_CONCAT" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.PP +This is an alias for "X963KDF". +.PP +See \fBEVP_KDF\-X963\fR\|(7) for a list of supported parameters and examples. +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KDF-X963.7 b/static/netbsd/man7/EVP_KDF-X963.7 new file mode 100644 index 00000000..ad8fadd1 --- /dev/null +++ b/static/netbsd/man7/EVP_KDF-X963.7 @@ -0,0 +1,190 @@ +.\" $NetBSD: EVP_KDF-X963.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-X963 7" +.TH EVP_KDF-X963 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-X963 \- The X9.63\-2001 EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP_KDF\-X963 algorithm implements the key derivation function (X963KDF). +X963KDF is used by Cryptographic Message Syntax (CMS) for EC KeyAgreement, to +derive a key using input such as a shared secret key and shared info. +.PP +The output is considered to be keying material. +.SS Identity +.IX Subsection "Identity" +"X963KDF" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.PD 0 +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.IP """key"" (\fBOSSL_KDF_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_KDF_PARAM_KEY) " +The shared secret used for key derivation. +This parameter sets the secret. +.IP """info"" (\fBOSSL_KDF_PARAM_INFO\fR) " 4 +.IX Item """info"" (OSSL_KDF_PARAM_INFO) " +This parameter specifies an optional value for shared info. +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling EVP_KDF_derive. It returns 0 if any "***\-check" +related parameter is set to 0 and the check fails. +.IP """digest\-check"" (\fBOSSL_KDF_PARAM_FIPS_DIGEST_CHECK\fR) " 4 +.IX Item """digest-check"" (OSSL_KDF_PARAM_FIPS_DIGEST_CHECK) " +The default value of 1 causes an error during \fBEVP_KDF_CTX_set_params()\fR if +used digest is not approved. +Setting this to zero will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.Sp +According to ANSI X9.63\-2001, the following are approved digest algorithms: +SHA2\-224, SHA2\-256, SHA2\-384, SHA2\-512, SHA2\-512/224, SHA2\-512/256, SHA3\-224, +SHA3\-256, SHA3\-384, SHA3\-512. +.IP """key\-check"" (\fBOSSL_KDF_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) " +The default value of 1 causes an error during \fBEVP_KDF_CTX_set_params()\fR if the +length of used key\-derivation key (\fBOSSL_KDF_PARAM_KEY\fR) is shorter than 112 +bits. +Setting this to zero will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SH NOTES +.IX Header "NOTES" +X963KDF is very similar to the SSKDF that uses a digest as the auxiliary function, +X963KDF appends the counter to the secret, whereas SSKDF prepends the counter. +.PP +A context for X963KDF can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of an X963KDF is specified via the \fIkeylen\fR +parameter to the \fBEVP_KDF_derive\fR\|(3) function. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example derives 10 bytes, with the secret key "secret" and sharedinfo +value "label": +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[10]; +\& OSSL_PARAM params[4], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, +\& SN_sha256, strlen(SN_sha256)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, +\& "secret", (size_t)6); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, +\& "label", (size_t)5); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { +\& error("EVP_KDF_derive"); +\& } +\& +\& EVP_KDF_CTX_free(kctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +"SEC 1: Elliptic Curve Cryptography" +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_CTX_get_kdf_size\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KEM-EC.7 b/static/netbsd/man7/EVP_KEM-EC.7 new file mode 100644 index 00000000..23320b05 --- /dev/null +++ b/static/netbsd/man7/EVP_KEM-EC.7 @@ -0,0 +1,133 @@ +.\" $NetBSD: EVP_KEM-EC.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KEM-EC 7" +.TH EVP_KEM-EC 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KEM\-EC +\&\- EVP_KEM EC keytype and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBEC\fR keytype and its parameters are described in \fBEVP_PKEY\-EC\fR\|(7). +See \fBEVP_PKEY_encapsulate\fR\|(3) and \fBEVP_PKEY_decapsulate\fR\|(3) for more info. +.SS "EC KEM parameters" +.IX Subsection "EC KEM parameters" +.IP """operation"" (\fBOSSL_KEM_PARAM_OPERATION\fR)" 4 +.IX Item """operation"" (OSSL_KEM_PARAM_OPERATION)" +The OpenSSL EC Key Encapsulation Mechanisms only supports the +following default operation (operating mode): +.RS 4 +.IP """DHKEM"" (\fBOSSL_KEM_PARAM_OPERATION_DHKEM\fR)" 4 +.IX Item """DHKEM"" (OSSL_KEM_PARAM_OPERATION_DHKEM)" +The encapsulate function generates an ephemeral keypair. It produces keymaterial +by doing an ECDH key exchange using the ephemeral private key and a supplied +recipient public key. A HKDF operation using the keymaterial and a kem context +then produces a shared secret. The shared secret and the ephemeral public key +are returned. +The decapsulate function uses the recipient private key and the +ephemeral public key to produce the same keymaterial, which can then be used to +produce the same shared secret. +See +.RE +.RS 4 +.Sp +This can be set using either \fBEVP_PKEY_CTX_set_kem_op()\fR or +\&\fBEVP_PKEY_CTX_set_params()\fR. +.RE +.IP """ikme"" (\fBOSSL_KEM_PARAM_IKME\fR) " 4 +.IX Item """ikme"" (OSSL_KEM_PARAM_IKME) " +Used to specify the key material used for generation of the ephemeral key. +This value should not be reused for other purposes. +It can only be used for the curves "P\-256", "P\-384" and "P\-521" and should +have a length of at least the size of the encoded private key +(i.e. 32, 48 and 66 for the listed curves). +If this value is not set, then a random ikm is used. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP RFC9180 4 +.IX Item "RFC9180" +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set_kem_op\fR\|(3), +\&\fBEVP_PKEY_encapsulate\fR\|(3), +\&\fBEVP_PKEY_decapsulate\fR\|(3) +\&\fBEVP_KEYMGMT\fR\|(3), +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.2. +.PP +The \f(CW\*(C`operation\*(C'\fR (operating mode) was a required parameter prior to OpenSSL 3.5. +As of OpenSSL 3.5, \f(CW\*(C`DHKEM\*(C'\fR is the default operating mode, and no explicit value +need be specified. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KEM-ML-KEM.7 b/static/netbsd/man7/EVP_KEM-ML-KEM.7 new file mode 100644 index 00000000..b1ea5968 --- /dev/null +++ b/static/netbsd/man7/EVP_KEM-ML-KEM.7 @@ -0,0 +1,113 @@ +.\" $NetBSD: EVP_KEM-ML-KEM.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KEM-ML-KEM 7" +.TH EVP_KEM-ML-KEM 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KEM\-ML\-KEM\-512, EVP_KEM\-ML\-KEM\-768, EVP_KEM\-ML\-KEM\-1024, EVP_KEM\-ML\-KEM +\&\- EVP_KEM ML\-KEM keytype and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBML\-KEM\fR keytypes and parameters are described in \fBEVP_PKEY\-ML\-KEM\fR\|(7). +See \fBEVP_PKEY_encapsulate\fR\|(3) and \fBEVP_PKEY_decapsulate\fR\|(3) for more details +about basic KEM operations. +.SS "ML\-KEM KEM parameters" +.IX Subsection "ML-KEM KEM parameters" +.IP """ikme"" (\fBOSSL_KEM_PARAM_IKME\fR) " 4 +.IX Item """ikme"" (OSSL_KEM_PARAM_IKME) " +The OpenSSL ML\-KEM encapsulation mechanism can only be modified by +setting randomness during encapsulation, this enables testing, as per +FIPS 203, section 6.2, algorithm 17. +.Sp +This parameter should not be used for purposes other than testing. +.Sp +When this parameter is not set, encapsulation proceeds as per FIPS 203, +section 7.2 +.Sp +This parameter is only settable. +.PP +This can be set when using \fBEVP_PKEY_encapsulate_init()\fR. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP FIPS203 4 +.IX Item "FIPS203" +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_encapsulate\fR\|(3), +\&\fBEVP_PKEY_decapsulate\fR\|(3), +\&\fBEVP_KEYMGMT\fR\|(3), +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KEM-RSA.7 b/static/netbsd/man7/EVP_KEM-RSA.7 new file mode 100644 index 00000000..b89cc336 --- /dev/null +++ b/static/netbsd/man7/EVP_KEM-RSA.7 @@ -0,0 +1,127 @@ +.\" $NetBSD: EVP_KEM-RSA.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KEM-RSA 7" +.TH EVP_KEM-RSA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KEM\-RSA +\&\- EVP_KEM RSA keytype and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBRSA\fR keytype and its parameters are described in \fBEVP_PKEY\-RSA\fR\|(7). +See \fBEVP_PKEY_encapsulate\fR\|(3) and \fBEVP_PKEY_decapsulate\fR\|(3) for more info. +.SS "RSA KEM parameters" +.IX Subsection "RSA KEM parameters" +.IP """operation"" (\fBOSSL_KEM_PARAM_OPERATION\fR) " 4 +.IX Item """operation"" (OSSL_KEM_PARAM_OPERATION) " +The OpenSSL RSA Key Encapsulation Mechanism only currently supports the +following default operation (operating mode): +.RS 4 +.IP """RSASVE""" 4 +.IX Item """RSASVE""" +The encapsulate function simply generates a secret using random bytes and then +encrypts the secret using the RSA public key (with no padding). +The decapsulate function recovers the secret using the RSA private key. +.RE +.RS 4 +.Sp +This can be set using \fBEVP_PKEY_CTX_set_kem_op()\fR. +.RE +.IP """fips\-indicator"" (\fBOSSL_KEM_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_KEM_PARAM_FIPS_APPROVED_INDICATOR) " +.PD 0 +.IP """key\-check"" (\fBOSSL_KEM_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_KEM_PARAM_FIPS_KEY_CHECK) " +.PD +These parameters are described in \fBprovider\-kem\fR\|(7). +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP SP800\-56Br2 4 +.IX Item "SP800-56Br2" +Section 7.2.1.2 RSASVE Generate Operation (RSASVE.GENERATE). +Section 7.2.1.3 RSASVE Recovery Operation (RSASVE.RECOVER). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set_kem_op\fR\|(3), +\&\fBEVP_PKEY_encapsulate\fR\|(3), +\&\fBEVP_PKEY_decapsulate\fR\|(3) +\&\fBEVP_KEYMGMT\fR\|(3), +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.PP +The \f(CW\*(C`operation\*(C'\fR (operating mode) was a required parameter prior to OpenSSL 3.5. +As of OpenSSL 3.5, \f(CW\*(C`RSASVE\*(C'\fR is the default operating mode, and no explicit +value need be specified. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KEM-X25519.7 b/static/netbsd/man7/EVP_KEM-X25519.7 new file mode 100644 index 00000000..6af6547f --- /dev/null +++ b/static/netbsd/man7/EVP_KEM-X25519.7 @@ -0,0 +1,132 @@ +.\" $NetBSD: EVP_KEM-X25519.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KEM-X25519 7" +.TH EVP_KEM-X25519 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KEM\-X25519, EVP_KEM\-X448 +\&\- EVP_KEM X25519 and EVP_KEM X448 keytype and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBX25519\fR and keytype and its parameters are described in +\&\fBEVP_PKEY\-X25519\fR\|(7). +See \fBEVP_PKEY_encapsulate\fR\|(3) and \fBEVP_PKEY_decapsulate\fR\|(3) for more info. +.SS "X25519 and X448 KEM parameters" +.IX Subsection "X25519 and X448 KEM parameters" +.IP """operation"" (\fBOSSL_KEM_PARAM_OPERATION\fR)" 4 +.IX Item """operation"" (OSSL_KEM_PARAM_OPERATION)" +The OpenSSL X25519 and X448 Key Encapsulation Mechanisms only support the +following default operation (operating mode): +.RS 4 +.IP """DHKEM"" (\fBOSSL_KEM_PARAM_OPERATION_DHKEM\fR)" 4 +.IX Item """DHKEM"" (OSSL_KEM_PARAM_OPERATION_DHKEM)" +The encapsulate function generates an ephemeral keypair. It produces keymaterial +by doing an X25519 or X448 key exchange using the ephemeral private key and a +supplied recipient public key. A HKDF operation using the keymaterial and a kem +context then produces a shared secret. The shared secret and the ephemeral +public key are returned. +The decapsulate function uses the recipient private key and the +ephemeral public key to produce the same keymaterial, which can then be used to +produce the same shared secret. +See +.RE +.RS 4 +.Sp +This can be set using either \fBEVP_PKEY_CTX_set_kem_op()\fR or +\&\fBEVP_PKEY_CTX_set_params()\fR. +.RE +.IP """ikme"" (\fBOSSL_KEM_PARAM_IKME\fR) " 4 +.IX Item """ikme"" (OSSL_KEM_PARAM_IKME) " +Used to specify the key material used for generation of the ephemeral key. +This value should not be reused for other purposes. +It should have a length of at least 32 for X25519, and 56 for X448. +If this value is not set, then a random ikm is used. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP RFC9180 4 +.IX Item "RFC9180" +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set_kem_op\fR\|(3), +\&\fBEVP_PKEY_encapsulate\fR\|(3), +\&\fBEVP_PKEY_decapsulate\fR\|(3) +\&\fBEVP_KEYMGMT\fR\|(3), +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.2. +.PP +The \f(CW\*(C`operation\*(C'\fR (operating mode) was a required parameter prior to OpenSSL 3.5. +As of OpenSSL 3.5, \f(CW\*(C`DHKEM\*(C'\fR is the default operating mode, and no explicit value +need be specified. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KEYEXCH-DH.7 b/static/netbsd/man7/EVP_KEYEXCH-DH.7 new file mode 100644 index 00000000..b7dbc92d --- /dev/null +++ b/static/netbsd/man7/EVP_KEYEXCH-DH.7 @@ -0,0 +1,194 @@ +.\" $NetBSD: EVP_KEYEXCH-DH.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KEYEXCH-DH 7" +.TH EVP_KEYEXCH-DH 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KEYEXCH\-DH +\&\- DH Key Exchange algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Key exchange support for the \fBDH\fR and \fBDHX\fR key types. +.PP +Please note that although both key types support the same key exchange +operations, they cannot be used together in a single key exchange. It +is not possible to use a private key of the \fBDH\fR type in key exchange +with the public key of \fBDHX\fR type and vice versa. +.SS "DH and DHX key exchange parameters" +.IX Subsection "DH and DHX key exchange parameters" +.IP """pad"" (\fBOSSL_EXCHANGE_PARAM_PAD\fR) " 4 +.IX Item """pad"" (OSSL_EXCHANGE_PARAM_PAD) " +Sets the padding mode for the associated key exchange ctx. +Setting a value of 1 will turn padding on. +Setting a value of 0 will turn padding off. +If padding is off then the derived shared secret may be smaller than the +largest possible secret size. +If padding is on then the derived shared secret will have its first bytes +filled with zeros where necessary to make the shared secret the same size as +the largest possible secret size. +The padding mode parameter is ignored (and padding implicitly enabled) when +the KDF type is set to "X942KDF\-ASN1" (\fBOSSL_KDF_NAME_X942KDF_ASN1\fR). +.IP """kdf\-type"" (\fBOSSL_EXCHANGE_PARAM_KDF_TYPE\fR) " 4 +.IX Item """kdf-type"" (OSSL_EXCHANGE_PARAM_KDF_TYPE) " +.PD 0 +.IP """kdf\-digest"" (\fBOSSL_EXCHANGE_PARAM_KDF_DIGEST\fR) " 4 +.IX Item """kdf-digest"" (OSSL_EXCHANGE_PARAM_KDF_DIGEST) " +.IP """kdf\-digest\-props"" (\fBOSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS\fR) " 4 +.IX Item """kdf-digest-props"" (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) " +.IP """kdf\-outlen"" (\fBOSSL_EXCHANGE_PARAM_KDF_OUTLEN\fR) " 4 +.IX Item """kdf-outlen"" (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) " +.IP """kdf\-ukm"" (\fBOSSL_EXCHANGE_PARAM_KDF_UKM\fR) " 4 +.IX Item """kdf-ukm"" (OSSL_EXCHANGE_PARAM_KDF_UKM) " +.IP """fips\-indicator"" (\fBOSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR) " +.IP """key\-check"" (\fBOSSL_EXCHANGE_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_EXCHANGE_PARAM_FIPS_KEY_CHECK) " +.IP """digest\-check"" (\fBOSSL_EXCHANGE_PARAM_FIPS_DIGEST_CHECK\fR) " 4 +.IX Item """digest-check"" (OSSL_EXCHANGE_PARAM_FIPS_DIGEST_CHECK) " +.PD +See "Common Key Exchange parameters" in \fBprovider\-keyexch\fR\|(7). +.IP """cekalg"" (\fBOSSL_KDF_PARAM_CEK_ALG\fR) " 4 +.IX Item """cekalg"" (OSSL_KDF_PARAM_CEK_ALG) " +See "KDF Parameters" in \fBprovider\-kdf\fR\|(7). +.SH EXAMPLES +.IX Header "EXAMPLES" +The examples assume a host and peer both generate keys using the same +named group (or domain parameters). See "Examples" in \fBEVP_PKEY\-DH\fR\|(7). +Both the host and peer transfer their public key to each other. +.PP +To convert the peer\*(Aqs generated key pair to a public key in DER format in order +to transfer to the host: +.PP +.Vb 3 +\& EVP_PKEY *peer_key; /* It is assumed this contains the peers generated key */ +\& unsigned char *peer_pub_der = NULL; +\& int peer_pub_der_len; +\& +\& peer_pub_der_len = i2d_PUBKEY(peer_key, &peer_pub_der); +\& ... +\& OPENSSL_free(peer_pub_der); +.Ve +.PP +To convert the received peer\*(Aqs public key from DER format on the host: +.PP +.Vb 4 +\& const unsigned char *pd = peer_pub_der; +\& EVP_PKEY *peer_pub_key = d2i_PUBKEY(NULL, &pd, peer_pub_der_len); +\& ... +\& EVP_PKEY_free(peer_pub_key); +.Ve +.PP +To derive a shared secret on the host using the host\*(Aqs key and the peer\*(Aqs public +key: +.PP +.Vb 8 +\& /* It is assumed that the host_key and peer_pub_key are set up */ +\& void derive_secret(EVP_KEY *host_key, EVP_PKEY *peer_pub_key) +\& { +\& unsigned int pad = 1; +\& OSSL_PARAM params[2]; +\& unsigned char *secret = NULL; +\& size_t secret_len = 0; +\& EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL); +\& +\& EVP_PKEY_derive_init(dctx); +\& +\& /* Optionally set the padding */ +\& params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad); +\& params[1] = OSSL_PARAM_construct_end(); +\& EVP_PKEY_CTX_set_params(dctx, params); +\& +\& EVP_PKEY_derive_set_peer(dctx, peer_pub_key); +\& +\& /* Get the size by passing NULL as the buffer */ +\& EVP_PKEY_derive(dctx, NULL, &secret_len); +\& secret = OPENSSL_zalloc(secret_len); +\& +\& EVP_PKEY_derive(dctx, secret, &secret_len); +\& ... +\& OPENSSL_clear_free(secret, secret_len); +\& EVP_PKEY_CTX_free(dctx); +\& } +.Ve +.PP +Very similar code can be used by the peer to derive the same shared secret +using the host\*(Aqs public key and the peer\*(Aqs generated key pair. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY\-DH\fR\|(7), +\&\fBEVP_PKEY\-FFC\fR\|(7), +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keyexch\fR\|(7), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KEYEXCH-ECDH.7 b/static/netbsd/man7/EVP_KEYEXCH-ECDH.7 new file mode 100644 index 00000000..216242ec --- /dev/null +++ b/static/netbsd/man7/EVP_KEYEXCH-ECDH.7 @@ -0,0 +1,186 @@ +.\" $NetBSD: EVP_KEYEXCH-ECDH.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KEYEXCH-ECDH 7" +.TH EVP_KEYEXCH-ECDH 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KEYEXCH\-ECDH \- ECDH Key Exchange algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Key exchange support for the \fBECDH\fR key type. +.SS "ECDH Key Exchange parameters" +.IX Subsection "ECDH Key Exchange parameters" +.IP """ecdh\-cofactor\-mode"" (\fBOSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE\fR) " 4 +.IX Item """ecdh-cofactor-mode"" (OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE) " +Sets or gets the ECDH mode of operation for the associated key exchange ctx. +.Sp +In the context of an Elliptic Curve Diffie\-Hellman key exchange, this parameter +can be used to select between the plain Diffie\-Hellman (DH) or Cofactor +Diffie\-Hellman (CDH) variants of the key exchange algorithm. +.Sp +When setting, the value should be 1, 0 or \-1, respectively forcing cofactor mode +on, off, or resetting it to the default for the private key associated with the +given key exchange ctx. +.Sp +When getting, the value should be either 1 or 0, respectively signaling if the +cofactor mode is on or off. +.Sp +See also \fBprovider\-keymgmt\fR\|(7) for the related +\&\fBOSSL_PKEY_PARAM_USE_COFACTOR_ECDH\fR parameter that can be set on a +per\-key basis. +.IP """kdf\-type"" (\fBOSSL_EXCHANGE_PARAM_KDF_TYPE\fR) " 4 +.IX Item """kdf-type"" (OSSL_EXCHANGE_PARAM_KDF_TYPE) " +.PD 0 +.IP """kdf\-digest"" (\fBOSSL_EXCHANGE_PARAM_KDF_DIGEST\fR) " 4 +.IX Item """kdf-digest"" (OSSL_EXCHANGE_PARAM_KDF_DIGEST) " +.IP """kdf\-digest\-props"" (\fBOSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS\fR) " 4 +.IX Item """kdf-digest-props"" (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) " +.IP """kdf\-outlen"" (\fBOSSL_EXCHANGE_PARAM_KDF_OUTLEN\fR) " 4 +.IX Item """kdf-outlen"" (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) " +.IP """kdf\-ukm"" (\fBOSSL_EXCHANGE_PARAM_KDF_UKM\fR) " 4 +.IX Item """kdf-ukm"" (OSSL_EXCHANGE_PARAM_KDF_UKM) " +.PD +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR) " +.PD 0 +.IP """key\-check"" (\fBOSSL_EXCHANGE_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_EXCHANGE_PARAM_FIPS_KEY_CHECK) " +.IP """digest\-check"" (\fBOSSL_EXCHANGE_PARAM_FIPS_DIGEST_CHECK\fR) " 4 +.IX Item """digest-check"" (OSSL_EXCHANGE_PARAM_FIPS_DIGEST_CHECK) " +.PD +See "Common Key Exchange parameters" in \fBprovider\-keyexch\fR\|(7). +.IP """ecdh\-cofactor\-check"" (\fBOSSL_EXCHANGE_PARAM_FIPS_ECDH_COFACTOR_CHECK\fR) " 4 +.IX Item """ecdh-cofactor-check"" (OSSL_EXCHANGE_PARAM_FIPS_ECDH_COFACTOR_CHECK) " +If required this parameter should before \fBOSSL_FUNC_keyexch_derive()\fR. +The default value of 1 causes an error during the OSSL_FUNC_keyexch_derive if +the EC curve has a cofactor that is not 1, and the cofactor is not used. +Setting this to 0 will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SH EXAMPLES +.IX Header "EXAMPLES" +Examples of key agreement can be found in demos/keyexch. +.PP +Keys for the host and peer must be generated as shown in +"Examples" in \fBEVP_PKEY\-EC\fR\|(7) using the same curve name. +.PP +The code to generate a shared secret for the normal case is identical to +"Examples" in \fBEVP_KEYEXCH\-DH\fR\|(7). +.PP +To derive a shared secret on the host using the host\*(Aqs key and the peer\*(Aqs public +key but also using X963KDF with a user key material: +.PP +.Vb 10 +\& /* It is assumed that the host_key, peer_pub_key and ukm are set up */ +\& void derive_secret(EVP_PKEY *host_key, EVP_PKEY *peer_key, +\& unsigned char *ukm, size_t ukm_len) +\& { +\& unsigned char secret[64]; +\& size_t out_len = sizeof(secret); +\& size_t secret_len = out_len; +\& unsigned int pad = 1; +\& OSSL_PARAM params[6]; +\& EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL); +\& +\& EVP_PKEY_derive_init(dctx); +\& +\& params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad); +\& params[1] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_TYPE, +\& "X963KDF", 0); +\& params[2] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_DIGEST, +\& "SHA1", 0); +\& params[3] = OSSL_PARAM_construct_size_t(OSSL_EXCHANGE_PARAM_KDF_OUTLEN, +\& &out_len); +\& params[4] = OSSL_PARAM_construct_octet_string(OSSL_EXCHANGE_PARAM_KDF_UKM, +\& ukm, ukm_len); +\& params[5] = OSSL_PARAM_construct_end(); +\& EVP_PKEY_CTX_set_params(dctx, params); +\& +\& EVP_PKEY_derive_set_peer(dctx, peer_pub_key); +\& EVP_PKEY_derive(dctx, secret, &secret_len); +\& ... +\& OPENSSL_clear_free(secret, secret_len); +\& EVP_PKEY_CTX_free(dctx); +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY\-EC\fR\|(7) +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keyexch\fR\|(7), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_KEYEXCH-X25519.7 b/static/netbsd/man7/EVP_KEYEXCH-X25519.7 new file mode 100644 index 00000000..ef1d0c95 --- /dev/null +++ b/static/netbsd/man7/EVP_KEYEXCH-X25519.7 @@ -0,0 +1,110 @@ +.\" $NetBSD: EVP_KEYEXCH-X25519.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KEYEXCH-X25519 7" +.TH EVP_KEYEXCH-X25519 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KEYEXCH\-X25519, +EVP_KEYEXCH\-X448 +\&\- X25519 and X448 Key Exchange algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Key exchange support for the \fBX25519\fR and \fBX448\fR key types. +.SS "Key exchange parameters" +.IX Subsection "Key exchange parameters" +.IP """pad"" (\fBOSSL_EXCHANGE_PARAM_PAD\fR) " 4 +.IX Item """pad"" (OSSL_EXCHANGE_PARAM_PAD) " +.PD 0 +.IP """fips\-indicator"" (\fBOSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR) " +.PD +\&\fBX25519\fR and \fBX448\fR are not FIPS approved in FIPS 140\-3. +So this getter will return 0. +.Sp +See "Common Key Exchange parameters" in \fBprovider\-keyexch\fR\|(7). +.SH EXAMPLES +.IX Header "EXAMPLES" +Keys for the host and peer can be generated as shown in +"Examples" in \fBEVP_PKEY\-X25519\fR\|(7). +.PP +The code to generate a shared secret is identical to +"Examples" in \fBEVP_KEYEXCH\-DH\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY\-FFC\fR\|(7), +\&\fBEVP_PKEY\-DH\fR\|(7) +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keyexch\fR\|(7), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MAC-BLAKE2.7 b/static/netbsd/man7/EVP_MAC-BLAKE2.7 new file mode 100644 index 00000000..4057af53 --- /dev/null +++ b/static/netbsd/man7/EVP_MAC-BLAKE2.7 @@ -0,0 +1,136 @@ +.\" $NetBSD: EVP_MAC-BLAKE2.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MAC-BLAKE2 7" +.TH EVP_MAC-BLAKE2 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MAC\-BLAKE2, EVP_MAC\-BLAKE2BMAC, EVP_MAC\-BLAKE2SMAC +\&\- The BLAKE2 EVP_MAC implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing BLAKE2 MACs through the \fBEVP_MAC\fR API. +.SS Identity +.IX Subsection "Identity" +These implementations are identified with one of these names and +properties, to be used with \fBEVP_MAC_fetch()\fR: +.IP """BLAKE2BMAC"", ""provider=default""" 4 +.IX Item """BLAKE2BMAC"", ""provider=default""" +.PD 0 +.IP """BLAKE2SMAC"", ""provider=default""" 4 +.IX Item """BLAKE2SMAC"", ""provider=default""" +.PD +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The general description of these parameters can be found in +"PARAMETERS" in \fBEVP_MAC\fR\|(3). +.PP +All these parameters (except for "block\-size") can be set with +\&\fBEVP_MAC_CTX_set_params()\fR. +Furthermore, the "size" parameter can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR, or with \fBEVP_MAC_CTX_get_mac_size()\fR. +The length of the "size" parameter should not exceed that of a \fBsize_t\fR. +Likewise, the "block\-size" parameter can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR, or with \fBEVP_MAC_CTX_get_block_size()\fR. +.IP """key"" (\fBOSSL_MAC_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_MAC_PARAM_KEY) " +Sets the MAC key. +It may be at most 64 bytes for BLAKE2BMAC or 32 for BLAKE2SMAC and at +least 1 byte in both cases. +Setting this parameter is identical to passing a \fIkey\fR to \fBEVP_MAC_init\fR\|(3). +.IP """custom"" (\fBOSSL_MAC_PARAM_CUSTOM\fR) " 4 +.IX Item """custom"" (OSSL_MAC_PARAM_CUSTOM) " +Sets the customization/personalization string. +It is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for +BLAKE2SMAC, and is empty by default. +.IP """salt"" (\fBOSSL_MAC_PARAM_SALT\fR) " 4 +.IX Item """salt"" (OSSL_MAC_PARAM_SALT) " +Sets the salt. +It is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for +BLAKE2SMAC, and is empty by default. +.IP """size"" (\fBOSSL_MAC_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_MAC_PARAM_SIZE) " +Sets the MAC size. +It can be any number between 1 and 32 for EVP_MAC_BLAKE2S or between 1 +and 64 for EVP_MAC_BLAKE2B. +It is 32 and 64 respectively by default. +.IP """block\-size"" (\fBOSSL_MAC_PARAM_BLOCK_SIZE\fR) " 4 +.IX Item """block-size"" (OSSL_MAC_PARAM_BLOCK_SIZE) " +Gets the MAC block size. +It is 64 for EVP_MAC_BLAKE2S and 128 for EVP_MAC_BLAKE2B. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_CTX_get_params\fR\|(3), \fBEVP_MAC_CTX_set_params\fR\|(3), +"PARAMETERS" in \fBEVP_MAC\fR\|(3), \fBOSSL_PARAM\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The macros and functions described here were added to OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MAC-CMAC.7 b/static/netbsd/man7/EVP_MAC-CMAC.7 new file mode 100644 index 00000000..d1019c73 --- /dev/null +++ b/static/netbsd/man7/EVP_MAC-CMAC.7 @@ -0,0 +1,141 @@ +.\" $NetBSD: EVP_MAC-CMAC.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MAC-CMAC 7" +.TH EVP_MAC-CMAC 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MAC\-CMAC \- The CMAC EVP_MAC implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing CMAC MACs through the \fBEVP_MAC\fR API. +.PP +This implementation uses EVP_CIPHER functions to get access to the underlying +cipher. +.SS Identity +.IX Subsection "Identity" +This implementation is identified with this name and properties, to be +used with \fBEVP_MAC_fetch()\fR: +.IP """CMAC"", ""provider=default"" or ""provider=fips""" 4 +.IX Item """CMAC"", ""provider=default"" or ""provider=fips""" +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The general description of these parameters can be found in +"PARAMETERS" in \fBEVP_MAC\fR\|(3). +.PP +The following parameter can be set with \fBEVP_MAC_CTX_set_params()\fR: +.IP """key"" (\fBOSSL_MAC_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_MAC_PARAM_KEY) " +Sets the MAC key. +Setting this parameter is identical to passing a \fIkey\fR to \fBEVP_MAC_init\fR\|(3). +.IP """cipher"" (\fBOSSL_MAC_PARAM_CIPHER\fR) " 4 +.IX Item """cipher"" (OSSL_MAC_PARAM_CIPHER) " +Sets the name of the underlying cipher to be used. The mode of the cipher +must be CBC. +.IP """properties"" (\fBOSSL_MAC_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_MAC_PARAM_PROPERTIES) " +Sets the properties to be queried when trying to fetch the underlying cipher. +This must be given together with the cipher naming parameter to be considered +valid. +.IP """encrypt\-check"" (\fBOSSL_CIPHER_PARAM_FIPS_ENCRYPT_CHECK\fR) " 4 +.IX Item """encrypt-check"" (OSSL_CIPHER_PARAM_FIPS_ENCRYPT_CHECK) " +This option is used by the OpenSSL FIPS provider. +If required this parameter should be set before \fBEVP_MAC_init()\fR +.Sp +The default value of 1 causes an error when a unapproved Triple\-DES encryption +operation is triggered. +Setting this to 0 will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.PP +The following parameters can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR: +.IP """size"" (\fBOSSL_MAC_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_MAC_PARAM_SIZE) " +The "size" parameter can also be retrieved with with \fBEVP_MAC_CTX_get_mac_size()\fR. +The length of the "size" parameter is equal to that of an \fBunsigned int\fR. +.IP """block\-size"" (\fBOSSL_MAC_PARAM_BLOCK_SIZE\fR) " 4 +.IX Item """block-size"" (OSSL_MAC_PARAM_BLOCK_SIZE) " +Gets the MAC block size. The "block\-size" parameter can also be retrieved with +\&\fBEVP_MAC_CTX_get_block_size()\fR. +.IP """fips\-indicator"" (\fBOSSL_CIPHER_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_CIPHER_PARAM_FIPS_APPROVED_INDICATOR) " +This option is used by the OpenSSL FIPS provider. +.Sp +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling \fBEVP_MAC_final()\fR. +It may return 0 if the "encrypt\-check" option is set to 0. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_CTX_get_params\fR\|(3), \fBEVP_MAC_CTX_set_params\fR\|(3), +"PARAMETERS" in \fBEVP_MAC\fR\|(3), \fBOSSL_PARAM\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MAC-GMAC.7 b/static/netbsd/man7/EVP_MAC-GMAC.7 new file mode 100644 index 00000000..c3231f66 --- /dev/null +++ b/static/netbsd/man7/EVP_MAC-GMAC.7 @@ -0,0 +1,123 @@ +.\" $NetBSD: EVP_MAC-GMAC.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MAC-GMAC 7" +.TH EVP_MAC-GMAC 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MAC\-GMAC \- The GMAC EVP_MAC implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing GMAC MACs through the \fBEVP_MAC\fR API. +.PP +This implementation uses EVP_CIPHER functions to get access to the underlying +cipher. +.SS Identity +.IX Subsection "Identity" +This implementation is identified with this name and properties, to be +used with \fBEVP_MAC_fetch()\fR: +.IP """GMAC"", ""provider=default"" or ""provider=fips""" 4 +.IX Item """GMAC"", ""provider=default"" or ""provider=fips""" +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The general description of these parameters can be found in +"PARAMETERS" in \fBEVP_MAC\fR\|(3). +.PP +The following parameter can be set with \fBEVP_MAC_CTX_set_params()\fR: +.IP """key"" (\fBOSSL_MAC_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_MAC_PARAM_KEY) " +Sets the MAC key. +Setting this parameter is identical to passing a \fIkey\fR to \fBEVP_MAC_init\fR\|(3). +.IP """iv"" (\fBOSSL_MAC_PARAM_IV\fR) " 4 +.IX Item """iv"" (OSSL_MAC_PARAM_IV) " +Sets the IV of the underlying cipher, when applicable. +.IP """cipher"" (\fBOSSL_MAC_PARAM_CIPHER\fR) " 4 +.IX Item """cipher"" (OSSL_MAC_PARAM_CIPHER) " +Sets the name of the underlying cipher to be used. +.IP """properties"" (\fBOSSL_MAC_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_MAC_PARAM_PROPERTIES) " +Sets the properties to be queried when trying to fetch the underlying cipher. +This must be given together with the cipher naming parameter to be considered +valid. +.PP +The following parameters can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR: +.IP """size"" (\fBOSSL_MAC_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_MAC_PARAM_SIZE) " +Gets the MAC size. +.PP +The "size" parameter can also be retrieved with \fBEVP_MAC_CTX_get_mac_size()\fR. +The length of the "size" parameter is equal to that of an \fBunsigned int\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_CTX_get_params\fR\|(3), \fBEVP_MAC_CTX_set_params\fR\|(3), +"PARAMETERS" in \fBEVP_MAC\fR\|(3), \fBOSSL_PARAM\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MAC-HMAC.7 b/static/netbsd/man7/EVP_MAC-HMAC.7 new file mode 100644 index 00000000..cc03bae0 --- /dev/null +++ b/static/netbsd/man7/EVP_MAC-HMAC.7 @@ -0,0 +1,144 @@ +.\" $NetBSD: EVP_MAC-HMAC.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MAC-HMAC 7" +.TH EVP_MAC-HMAC 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MAC\-HMAC \- The HMAC EVP_MAC implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing HMAC MACs through the \fBEVP_MAC\fR API. +.PP +This implementation uses EVP_MD functions to get access to the underlying +digest. +.SS Identity +.IX Subsection "Identity" +This implementation is identified with this name and properties, to be +used with \fBEVP_MAC_fetch()\fR: +.IP """HMAC"", ""provider=default"" or ""provider=fips""" 4 +.IX Item """HMAC"", ""provider=default"" or ""provider=fips""" +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The general description of these parameters can be found in +"PARAMETERS" in \fBEVP_MAC\fR\|(3). +.PP +The following parameters can be set with \fBEVP_MAC_CTX_set_params()\fR: +.IP """key"" (\fBOSSL_MAC_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_MAC_PARAM_KEY) " +Sets the MAC key. +Setting this parameter is identical to passing a \fIkey\fR to \fBEVP_MAC_init\fR\|(3). +.IP """digest"" (\fBOSSL_MAC_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_MAC_PARAM_DIGEST) " +Sets the name of the underlying digest to be used. +.IP """properties"" (\fBOSSL_MAC_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_MAC_PARAM_PROPERTIES) " +Sets the properties to be queried when trying to fetch the underlying digest. +This must be given together with the digest naming parameter ("digest", or +\&\fBOSSL_MAC_PARAM_DIGEST\fR) to be considered valid. +.IP """digest\-noinit"" (\fBOSSL_MAC_PARAM_DIGEST_NOINIT\fR) " 4 +.IX Item """digest-noinit"" (OSSL_MAC_PARAM_DIGEST_NOINIT) " +A flag to set the MAC digest to not initialise the implementation +specific data. +The value 0 or 1 is expected. +This option is deprecated and will be removed in a future release. +It may be set but is currently ignored +.IP """digest\-oneshot"" (\fBOSSL_MAC_PARAM_DIGEST_ONESHOT\fR) " 4 +.IX Item """digest-oneshot"" (OSSL_MAC_PARAM_DIGEST_ONESHOT) " +A flag to set the MAC digest to be a one\-shot operation. +The value 0 or 1 is expected. +This option is deprecated and will be removed in a future release. +It may be set but is currently ignored. +.IP """tls\-data\-size"" (\fBOSSL_MAC_PARAM_TLS_DATA_SIZE\fR) " 4 +.IX Item """tls-data-size"" (OSSL_MAC_PARAM_TLS_DATA_SIZE) " +.PD 0 +.IP """key\-check"" (\fBOSSL_MAC_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_MAC_PARAM_FIPS_KEY_CHECK) " +.PD +See "Mac Parameters" in \fBprovider\-mac\fR\|(7). +.PP +The following parameters can be retrieved with \fBEVP_MAC_CTX_get_params()\fR: +.IP """size"" (\fBOSSL_MAC_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_MAC_PARAM_SIZE) " +The "size" parameter can also be retrieved with \fBEVP_MAC_CTX_get_mac_size()\fR. +The length of the "size" parameter is equal to that of an \fBunsigned int\fR. +.IP """block\-size"" (\fBOSSL_MAC_PARAM_BLOCK_SIZE\fR) " 4 +.IX Item """block-size"" (OSSL_MAC_PARAM_BLOCK_SIZE) " +Gets the MAC block size. The "block\-size" parameter can also be retrieved with +\&\fBEVP_MAC_CTX_get_block_size()\fR. +.IP """fips\-indicator"" (\fBOSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) " +See "Mac Parameters" in \fBprovider\-mac\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_CTX_get_params\fR\|(3), \fBEVP_MAC_CTX_set_params\fR\|(3), +"PARAMETERS" in \fBEVP_MAC\fR\|(3), \fBOSSL_PARAM\fR\|(3), \fBHMAC\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MAC-KMAC.7 b/static/netbsd/man7/EVP_MAC-KMAC.7 new file mode 100644 index 00000000..dfff38e0 --- /dev/null +++ b/static/netbsd/man7/EVP_MAC-KMAC.7 @@ -0,0 +1,213 @@ +.\" $NetBSD: EVP_MAC-KMAC.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MAC-KMAC 7" +.TH EVP_MAC-KMAC 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MAC\-KMAC, EVP_MAC\-KMAC128, EVP_MAC\-KMAC256 +\&\- The KMAC EVP_MAC implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing KMAC MACs through the \fBEVP_MAC\fR API. +.SS Identity +.IX Subsection "Identity" +These implementations are identified with one of these names and +properties, to be used with \fBEVP_MAC_fetch()\fR: +.IP """KMAC\-128"", ""provider=default"" or ""provider=fips""" 4 +.IX Item """KMAC-128"", ""provider=default"" or ""provider=fips""" +.PD 0 +.IP """KMAC\-256"", ""provider=default"" or ""provider=fips""" 4 +.IX Item """KMAC-256"", ""provider=default"" or ""provider=fips""" +.PD +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The general description of these parameters can be found in +"PARAMETERS" in \fBEVP_MAC\fR\|(3). +.PP +All these parameters (except for "block\-size") can be set with +\&\fBEVP_MAC_CTX_set_params()\fR. +Furthermore, the "size" parameter can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR, or with \fBEVP_MAC_CTX_get_mac_size()\fR. +The length of the "size" parameter should not exceed that of a \fBsize_t\fR. +Likewise, the "block\-size" parameter can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR, or with \fBEVP_MAC_CTX_get_block_size()\fR. +.IP """key"" (\fBOSSL_MAC_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_MAC_PARAM_KEY) " +Sets the MAC key. +Setting this parameter is identical to passing a \fIkey\fR to \fBEVP_MAC_init\fR\|(3). +The length of the key (in bytes) must be in the range 4...512. +.IP """custom"" (\fBOSSL_MAC_PARAM_CUSTOM\fR) " 4 +.IX Item """custom"" (OSSL_MAC_PARAM_CUSTOM) " +Sets the customization string. +It is an optional value with a length of at most 512 bytes, and is +empty by default. +.IP """size"" (\fBOSSL_MAC_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_MAC_PARAM_SIZE) " +Sets the MAC size. +By default, it is 32 for \f(CW\*(C`KMAC\-128\*(C'\fR and 64 for \f(CW\*(C`KMAC\-256\*(C'\fR. +.IP """block\-size"" (\fBOSSL_MAC_PARAM_BLOCK_SIZE\fR) " 4 +.IX Item """block-size"" (OSSL_MAC_PARAM_BLOCK_SIZE) " +Gets the MAC block size. +It is 168 for \f(CW\*(C`KMAC\-128\*(C'\fR and 136 for \f(CW\*(C`KMAC\-256\*(C'\fR. +.IP """xof"" (\fBOSSL_MAC_PARAM_XOF\fR) " 4 +.IX Item """xof"" (OSSL_MAC_PARAM_XOF) " +The "xof" parameter value is expected to be 1 or 0. Use 1 to enable XOF mode. +The default value is 0. +.IP """fips\-indicator"" (\fBOSSL_MAC_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_MAC_PARAM_FIPS_APPROVED_INDICATOR) " +This settable parameter is described in \fBprovider\-mac\fR\|(7). +.IP """no\-short\-mac"" (\fBOSSL_MAC_PARAM_FIPS_NO_SHORT_MAC\fR) " 4 +.IX Item """no-short-mac"" (OSSL_MAC_PARAM_FIPS_NO_SHORT_MAC) " +This settable parameter is described in \fBprovider\-mac\fR\|(7). It is used by +the OpenSSL FIPS provider and the minimum length output for KMAC +is defined by NIST\*(Aqs SP 800\-185 8.4.2. +.IP """key\-check"" (\fBOSSL_MAC_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_MAC_PARAM_FIPS_KEY_CHECK) " +This settable parameter is described in \fBprovider\-mac\fR\|(7). +.PP +The "custom" and "no\-short\-mac" parameters must be set as part of or before +the \fBEVP_MAC_init()\fR call. +The "xof" and "size" parameters can be set at any time before \fBEVP_MAC_final()\fR. +The "key" parameter is set as part of the \fBEVP_MAC_init()\fR call, but can be +set before it instead. +.SH EXAMPLES +.IX Header "EXAMPLES" +.Vb 2 +\& #include +\& #include +\& +\& static int do_kmac(const unsigned char *in, size_t in_len, +\& const unsigned char *key, size_t key_len, +\& const unsigned char *custom, size_t custom_len, +\& int xof_enabled, unsigned char *out, int out_len) +\& { +\& EVP_MAC_CTX *ctx = NULL; +\& EVP_MAC *mac = NULL; +\& OSSL_PARAM params[4], *p; +\& int ret = 0; +\& size_t l = 0; +\& +\& mac = EVP_MAC_fetch(NULL, "KMAC\-128", NULL); +\& if (mac == NULL) +\& goto err; +\& ctx = EVP_MAC_CTX_new(mac); +\& /* The mac can be freed after it is used by EVP_MAC_CTX_new */ +\& EVP_MAC_free(mac); +\& if (ctx == NULL) +\& goto err; +\& +\& /* +\& * Setup parameters required before calling EVP_MAC_init() +\& * The parameters OSSL_MAC_PARAM_XOF and OSSL_MAC_PARAM_SIZE may also be +\& * used at this point. +\& */ +\& p = params; +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY, +\& (void *)key, key_len); +\& if (custom != NULL && custom_len != 0) +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_CUSTOM, +\& (void *)custom, custom_len); +\& *p = OSSL_PARAM_construct_end(); +\& if (!EVP_MAC_CTX_set_params(ctx, params)) +\& goto err; +\& +\& if (!EVP_MAC_init(ctx)) +\& goto err; +\& +\& /* +\& * Note: the following optional parameters can be set any time +\& * before EVP_MAC_final(). +\& */ +\& p = params; +\& *p++ = OSSL_PARAM_construct_int(OSSL_MAC_PARAM_XOF, &xof_enabled); +\& *p++ = OSSL_PARAM_construct_int(OSSL_MAC_PARAM_SIZE, &out_len); +\& *p = OSSL_PARAM_construct_end(); +\& if (!EVP_MAC_CTX_set_params(ctx, params)) +\& goto err; +\& +\& /* The update may be called multiple times here for streamed input */ +\& if (!EVP_MAC_update(ctx, in, in_len)) +\& goto err; +\& if (!EVP_MAC_final(ctx, out, &l, out_len)) +\& goto err; +\& ret = 1; +\& err: +\& EVP_MAC_CTX_free(ctx); +\& return ret; +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_CTX_get_params\fR\|(3), \fBEVP_MAC_CTX_set_params\fR\|(3), +"PARAMETERS" in \fBEVP_MAC\fR\|(3), \fBOSSL_PARAM\fR\|(3), +SP 800\-185 8.4.2 +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MAC-Poly1305.7 b/static/netbsd/man7/EVP_MAC-Poly1305.7 new file mode 100644 index 00000000..bfb347d5 --- /dev/null +++ b/static/netbsd/man7/EVP_MAC-Poly1305.7 @@ -0,0 +1,115 @@ +.\" $NetBSD: EVP_MAC-Poly1305.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MAC-POLY1305 7" +.TH EVP_MAC-POLY1305 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MAC\-Poly1305 \- The Poly1305 EVP_MAC implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing Poly1305 MACs through the \fBEVP_MAC\fR API. +.SS Identity +.IX Subsection "Identity" +This implementation is identified with this name and properties, to be +used with \fBEVP_MAC_fetch()\fR: +.IP """POLY1305"", ""provider=default""" 4 +.IX Item """POLY1305"", ""provider=default""" +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The general description of these parameters can be found in +"PARAMETERS" in \fBEVP_MAC\fR\|(3). +.PP +The following parameter can be set with \fBEVP_MAC_CTX_set_params()\fR: +.IP """key"" (\fBOSSL_MAC_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_MAC_PARAM_KEY) " +Sets the MAC key. +Setting this parameter is identical to passing a \fIkey\fR to \fBEVP_MAC_init\fR\|(3). +.PP +The following parameters can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR: +.IP """size"" (\fBOSSL_MAC_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_MAC_PARAM_SIZE) " +Gets the MAC size. +.PP +The "size" parameter can also be retrieved with with \fBEVP_MAC_CTX_get_mac_size()\fR. +The length of the "size" parameter should not exceed that of an \fBunsigned int\fR. +.SH NOTES +.IX Header "NOTES" +The OpenSSL implementation of the Poly 1305 MAC corresponds to RFC 7539. +.PP +It is critical to never reuse the key. The security implication noted in +RFC 8439 applies equally to the OpenSSL implementation. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_CTX_get_params\fR\|(3), \fBEVP_MAC_CTX_set_params\fR\|(3), +"PARAMETERS" in \fBEVP_MAC\fR\|(3), \fBOSSL_PARAM\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MAC-Siphash.7 b/static/netbsd/man7/EVP_MAC-Siphash.7 new file mode 100644 index 00000000..f33428bf --- /dev/null +++ b/static/netbsd/man7/EVP_MAC-Siphash.7 @@ -0,0 +1,112 @@ +.\" $NetBSD: EVP_MAC-Siphash.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MAC-SIPHASH 7" +.TH EVP_MAC-SIPHASH 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MAC\-Siphash \- The Siphash EVP_MAC implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing Siphash MACs through the \fBEVP_MAC\fR API. +.SS Identity +.IX Subsection "Identity" +This implementation is identified with this name and properties, to be +used with \fBEVP_MAC_fetch()\fR: +.IP """SIPHASH"", ""provider=default""" 4 +.IX Item """SIPHASH"", ""provider=default""" +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The general description of these parameters can be found in +"PARAMETERS" in \fBEVP_MAC\fR\|(3). +.PP +All these parameters can be set with \fBEVP_MAC_CTX_set_params()\fR. +Furthermore, the "size" parameter can be retrieved with +\&\fBEVP_MAC_CTX_get_params()\fR, or with \fBEVP_MAC_CTX_get_mac_size()\fR. +The length of the "size" parameter should not exceed that of a \fBsize_t\fR. +.IP """key"" (\fBOSSL_MAC_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_MAC_PARAM_KEY) " +Sets the MAC key. +Setting this parameter is identical to passing a \fIkey\fR to \fBEVP_MAC_init\fR\|(3). +.IP """size"" (\fBOSSL_MAC_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_MAC_PARAM_SIZE) " +Sets the MAC size. +.IP """c\-rounds"" (\fBOSSL_MAC_PARAM_C_ROUNDS\fR) " 4 +.IX Item """c-rounds"" (OSSL_MAC_PARAM_C_ROUNDS) " +Specifies the number of rounds per message block. By default this is \fI2\fR. +.IP """d\-rounds"" (\fBOSSL_MAC_PARAM_D_ROUNDS\fR) " 4 +.IX Item """d-rounds"" (OSSL_MAC_PARAM_D_ROUNDS) " +Specifies the number of finalisation rounds. By default this is \fI4\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_CTX_get_params\fR\|(3), \fBEVP_MAC_CTX_set_params\fR\|(3), +"PARAMETERS" in \fBEVP_MAC\fR\|(3), \fBOSSL_PARAM\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-BLAKE2.7 b/static/netbsd/man7/EVP_MD-BLAKE2.7 new file mode 100644 index 00000000..d62e0d76 --- /dev/null +++ b/static/netbsd/man7/EVP_MD-BLAKE2.7 @@ -0,0 +1,123 @@ +.\" $NetBSD: EVP_MD-BLAKE2.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-BLAKE2 7" +.TH EVP_MD-BLAKE2 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-BLAKE2 \- The BLAKE2 EVP_MD implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing BLAKE2 digests through the \fBEVP_MD\fR API. +.SS Identities +.IX Subsection "Identities" +This implementation is only available with the default provider, and +includes the following varieties: +.IP BLAKE2S\-256 4 +.IX Item "BLAKE2S-256" +Known names are "BLAKE2S\-256" and "BLAKE2s256". +.IP BLAKE2B\-512 4 +.IX Item "BLAKE2B-512" +Known names are "BLAKE2B\-512" and "BLAKE2b512". +.SS "Settable Parameters" +.IX Subsection "Settable Parameters" +"BLAKE2B\-512" supports the following \fBEVP_MD_CTX_set_params()\fR key +described in "PARAMETERS" in \fBEVP_DigestInit\fR\|(3). +.IP """size"" (\fBOSSL_DIGEST_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_DIGEST_PARAM_SIZE) " +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SS "Settable Context Parameters" +.IX Subsection "Settable Context Parameters" +The implementation supports the following \fBOSSL_PARAM\fR\|(3) entries which +are settable for an \fBEVP_MD_CTX\fR with \fBEVP_DigestInit_ex2\fR\|(3) or +\&\fBEVP_MD_CTX_set_params\fR\|(3): +.IP """size"" (\fBOSSL_DIGEST_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_DIGEST_PARAM_SIZE) " +Sets a different digest length for the \fBEVP_DigestFinal\fR\|(3) output. +The value of the "size" parameter must not exceed the default digest length +of the respective BLAKE2 algorithm variants, 64 for BLAKE2B\-512 and +32 for BLAKE2S\-256. The parameter must be set with the +\&\fBEVP_DigestInit_ex2\fR\|(3) call to have an immediate effect. When set with +\&\fBEVP_MD_CTX_set_params\fR\|(3) it will have an effect only if the \fBEVP_MD_CTX\fR +context is reinitialized. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.PP +The variable size support was added in OpenSSL 3.2 for BLAKE2B\-512 and +in OpenSSL 3.3 for BLAKE2S\-256. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-KECCAK.7 b/static/netbsd/man7/EVP_MD-KECCAK.7 new file mode 100644 index 00000000..4e5eb0ed --- /dev/null +++ b/static/netbsd/man7/EVP_MD-KECCAK.7 @@ -0,0 +1,101 @@ +.\" $NetBSD: EVP_MD-KECCAK.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-KECCAK 7" +.TH EVP_MD-KECCAK 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-KECCAK \- The KECCAK EVP_MD implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing KECCAK digests through the \fBEVP_MD\fR API. +.SS Identities +.IX Subsection "Identities" +This implementation is available in the default provider and +includes the following varieties: +.IP """KECCAK\-224""" 4 +.IX Item """KECCAK-224""" +.PD 0 +.IP """KECCAK\-256""" 4 +.IX Item """KECCAK-256""" +.IP """KECCAK\-384""" 4 +.IX Item """KECCAK-384""" +.IP """KECCAK\-512""" 4 +.IX Item """KECCAK-512""" +.PD +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-MD2.7 b/static/netbsd/man7/EVP_MD-MD2.7 new file mode 100644 index 00000000..33b373e4 --- /dev/null +++ b/static/netbsd/man7/EVP_MD-MD2.7 @@ -0,0 +1,91 @@ +.\" $NetBSD: EVP_MD-MD2.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-MD2 7" +.TH EVP_MD-MD2 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-MD2 \- The MD2 EVP_MD implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing MD2 digests through the \fBEVP_MD\fR API. +.SS Identity +.IX Subsection "Identity" +This implementation is only available with the legacy provider, and is +identified with the name "MD2". +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-MD4.7 b/static/netbsd/man7/EVP_MD-MD4.7 new file mode 100644 index 00000000..37388687 --- /dev/null +++ b/static/netbsd/man7/EVP_MD-MD4.7 @@ -0,0 +1,91 @@ +.\" $NetBSD: EVP_MD-MD4.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-MD4 7" +.TH EVP_MD-MD4 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-MD4 \- The MD4 EVP_MD implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing MD4 digests through the \fBEVP_MD\fR API. +.SS Identity +.IX Subsection "Identity" +This implementation is only available with the legacy provider, and is +identified with the name "MD4". +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-MD5-SHA1.7 b/static/netbsd/man7/EVP_MD-MD5-SHA1.7 new file mode 100644 index 00000000..0812d184 --- /dev/null +++ b/static/netbsd/man7/EVP_MD-MD5-SHA1.7 @@ -0,0 +1,107 @@ +.\" $NetBSD: EVP_MD-MD5-SHA1.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-MD5-SHA1 7" +.TH EVP_MD-MD5-SHA1 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-MD5\-SHA1 \- The MD5\-SHA1 EVP_MD implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing MD5\-SHA1 digests through the \fBEVP_MD\fR API. +.PP +MD5\-SHA1 is a rather special digest that\*(Aqs used with SSLv3. +.SS Identity +.IX Subsection "Identity" +This implementation is only available with the default provider, and is +identified with the name "MD5\-SHA1". +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SS "Settable Context Parameters" +.IX Subsection "Settable Context Parameters" +This implementation supports the following \fBOSSL_PARAM\fR\|(3) entries, +settable for an \fBEVP_MD_CTX\fR with \fBEVP_MD_CTX_set_params\fR\|(3): +.IP """ssl3\-ms"" (\fBOSSL_DIGEST_PARAM_SSL3_MS\fR) " 4 +.IX Item """ssl3-ms"" (OSSL_DIGEST_PARAM_SSL3_MS) " +This parameter is set by libssl in order to calculate a signature hash for an +SSLv3 CertificateVerify message as per RFC6101. +It is only set after all handshake messages have already been digested via +\&\fBOP_digest_update()\fR calls. +The parameter provides the master secret value to be added to the digest. +The digest implementation should calculate the complete digest as per RFC6101 +section 5.6.8. +The next call after setting this parameter should be \fBOP_digest_final()\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MD_CTX_set_params\fR\|(3), \fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-MD5.7 b/static/netbsd/man7/EVP_MD-MD5.7 new file mode 100644 index 00000000..ce5fc0b7 --- /dev/null +++ b/static/netbsd/man7/EVP_MD-MD5.7 @@ -0,0 +1,91 @@ +.\" $NetBSD: EVP_MD-MD5.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-MD5 7" +.TH EVP_MD-MD5 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-MD5 \- The MD5 EVP_MD implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing MD5 digests through the \fBEVP_MD\fR API. +.SS Identity +.IX Subsection "Identity" +This implementation is only available with the default provider, and is +identified with the name "MD5". +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-MDC2.7 b/static/netbsd/man7/EVP_MD-MDC2.7 new file mode 100644 index 00000000..39e43c66 --- /dev/null +++ b/static/netbsd/man7/EVP_MD-MDC2.7 @@ -0,0 +1,101 @@ +.\" $NetBSD: EVP_MD-MDC2.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-MDC2 7" +.TH EVP_MD-MDC2 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-MDC2 \- The MDC2 EVP_MD implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing MDC2 digests through the \fBEVP_MD\fR API. +.SS Identity +.IX Subsection "Identity" +This implementation is only available with the legacy provider, and is +identified with the name "MDC2". +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SS "Settable Context Parameters" +.IX Subsection "Settable Context Parameters" +This implementation supports the following \fBOSSL_PARAM\fR\|(3) entries, +settable for an \fBEVP_MD_CTX\fR with \fBEVP_MD_CTX_set_params\fR\|(3): +.IP """pad\-type"" (\fBOSSL_DIGEST_PARAM_PAD_TYPE\fR) " 4 +.IX Item """pad-type"" (OSSL_DIGEST_PARAM_PAD_TYPE) " +Sets the padding type to be used. +Normally the final MDC2 block is padded with zeros. +If the pad type is set to 2 then the final block is padded with 0x80 followed by +zeros. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MD_CTX_set_params\fR\|(3), \fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-NULL.7 b/static/netbsd/man7/EVP_MD-NULL.7 new file mode 100644 index 00000000..a860b799 --- /dev/null +++ b/static/netbsd/man7/EVP_MD-NULL.7 @@ -0,0 +1,95 @@ +.\" $NetBSD: EVP_MD-NULL.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-NULL 7" +.TH EVP_MD-NULL 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-NULL \- The NULL EVP_MD implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for a NULL digest through the \fBEVP_MD\fR API. +This algorithm does nothing and returns 1 for its init, +update and final methods. +.SS "Algorithm Name" +.IX Subsection "Algorithm Name" +The following algorithm is available in the default provider: +.IP """NULL""" 4 +.IX Item """NULL""" +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MD_CTX_set_params\fR\|(3), \fBprovider\-digest\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-RIPEMD160.7 b/static/netbsd/man7/EVP_MD-RIPEMD160.7 new file mode 100644 index 00000000..6d90128a --- /dev/null +++ b/static/netbsd/man7/EVP_MD-RIPEMD160.7 @@ -0,0 +1,95 @@ +.\" $NetBSD: EVP_MD-RIPEMD160.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-RIPEMD160 7" +.TH EVP_MD-RIPEMD160 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-RIPEMD160 \- The RIPEMD160 EVP_MD implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing RIPEMD160 digests through the \fBEVP_MD\fR API. +.SS Identities +.IX Subsection "Identities" +This implementation is available in both the default and legacy providers, and is +identified with any of the names "RIPEMD\-160", "RIPEMD160", "RIPEMD" and +"RMD160". +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This digest was added to the default provider in OpenSSL 3.0.7. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-SHA1.7 b/static/netbsd/man7/EVP_MD-SHA1.7 new file mode 100644 index 00000000..517e8c18 --- /dev/null +++ b/static/netbsd/man7/EVP_MD-SHA1.7 @@ -0,0 +1,106 @@ +.\" $NetBSD: EVP_MD-SHA1.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-SHA1 7" +.TH EVP_MD-SHA1 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-SHA1 \- The SHA1 EVP_MD implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing SHA1 digests through the \fBEVP_MD\fR API. +.SS Identities +.IX Subsection "Identities" +This implementation is available with the FIPS provider as well as the +default provider, and is identified with the names "SHA1" and "SHA\-1". +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SS "Settable Context Parameters" +.IX Subsection "Settable Context Parameters" +This implementation supports the following \fBOSSL_PARAM\fR\|(3) entries, +settable for an \fBEVP_MD_CTX\fR with \fBEVP_MD_CTX_set_params\fR\|(3): +.IP """ssl3\-ms"" (\fBOSSL_DIGEST_PARAM_SSL3_MS\fR) " 4 +.IX Item """ssl3-ms"" (OSSL_DIGEST_PARAM_SSL3_MS) " +This parameter is set by libssl in order to calculate a signature hash for an +SSLv3 CertificateVerify message as per RFC6101. +It is only set after all handshake messages have already been digested via +\&\fBOP_digest_update()\fR calls. +The parameter provides the master secret value to be added to the digest. +The digest implementation should calculate the complete digest as per RFC6101 +section 5.6.8. +The next call after setting this parameter should be \fBOP_digest_final()\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MD_CTX_set_params\fR\|(3), \fBprovider\-digest\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-SHA2.7 b/static/netbsd/man7/EVP_MD-SHA2.7 new file mode 100644 index 00000000..f8bd5d00 --- /dev/null +++ b/static/netbsd/man7/EVP_MD-SHA2.7 @@ -0,0 +1,123 @@ +.\" $NetBSD: EVP_MD-SHA2.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-SHA2 7" +.TH EVP_MD-SHA2 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-SHA2 \- The SHA2 EVP_MD implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing SHA2 digests through the \fBEVP_MD\fR API. +.SS Identities +.IX Subsection "Identities" +This implementation includes the following varieties: +.IP \(bu 4 +Available with the FIPS provider as well as the default provider: +.RS 4 +.IP SHA2\-224 4 +.IX Item "SHA2-224" +Known names are "SHA2\-224", "SHA\-224" and "SHA224". +.IP SHA2\-256 4 +.IX Item "SHA2-256" +Known names are "SHA2\-256", "SHA\-256" and "SHA256". +.IP SHA2\-384 4 +.IX Item "SHA2-384" +Known names are "SHA2\-384", "SHA\-384" and "SHA384". +.IP SHA2\-512 4 +.IX Item "SHA2-512" +Known names are "SHA2\-512", "SHA\-512" and "SHA512". +.RE +.RS 4 +.RE +.IP \(bu 4 +Available with the default provider: +.RS 4 +.IP SHA2\-256/192 4 +.IX Item "SHA2-256/192" +Known names are "SHA2\-256/192", "SHA\-256/192" and "SHA256\-192". +.IP SHA2\-512/224 4 +.IX Item "SHA2-512/224" +Known names are "SHA2\-512/224", "SHA\-512/224" and "SHA512\-224". +.IP SHA2\-512/256 4 +.IX Item "SHA2-512/256" +Known names are "SHA2\-512/256", "SHA\-512/256" and "SHA512\-256". +.RE +.RS 4 +.RE +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-SHA3.7 b/static/netbsd/man7/EVP_MD-SHA3.7 new file mode 100644 index 00000000..cf03cf01 --- /dev/null +++ b/static/netbsd/man7/EVP_MD-SHA3.7 @@ -0,0 +1,101 @@ +.\" $NetBSD: EVP_MD-SHA3.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-SHA3 7" +.TH EVP_MD-SHA3 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-SHA3 \- The SHA3 EVP_MD implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing SHA3 digests through the \fBEVP_MD\fR API. +.SS Identities +.IX Subsection "Identities" +This implementation is available with the FIPS provider as well as the +default provider, and includes the following varieties: +.IP """SHA3\-224""" 4 +.IX Item """SHA3-224""" +.PD 0 +.IP """SHA3\-256""" 4 +.IX Item """SHA3-256""" +.IP """SHA3\-384""" 4 +.IX Item """SHA3-384""" +.IP """SHA3\-512""" 4 +.IX Item """SHA3-512""" +.PD +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-SHAKE.7 b/static/netbsd/man7/EVP_MD-SHAKE.7 new file mode 100644 index 00000000..774e675b --- /dev/null +++ b/static/netbsd/man7/EVP_MD-SHAKE.7 @@ -0,0 +1,142 @@ +.\" $NetBSD: EVP_MD-SHAKE.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-SHAKE 7" +.TH EVP_MD-SHAKE 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-SHAKE, EVP_MD\-KECCAK\-KMAC +\&\- The SHAKE / KECCAK family EVP_MD implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing SHAKE or KECCAK\-KMAC digests through the +\&\fBEVP_MD\fR API. +.PP +KECCAK\-KMAC is an Extendable Output Function (XOF), with a definition +similar to SHAKE, used by the KMAC EVP_MAC implementation (see +\&\fBEVP_MAC\-KMAC\fR\|(7)). +.SS Identities +.IX Subsection "Identities" +This implementation is available in the FIPS provider as well as the default +provider, and includes the following varieties: +.IP KECCAK\-KMAC\-128 4 +.IX Item "KECCAK-KMAC-128" +Known names are "KECCAK\-KMAC\-128" and "KECCAK\-KMAC128". This is used +by \fBEVP_MAC\-KMAC128\fR\|(7). Using the notation from NIST FIPS 202 +(Section 6.2), we have KECCAK\-KMAC\-128(M,\ d) = KECCAK[256](M\ ||\ 00,\ d) +(see the description of KMAC128 in Appendix A of NIST SP 800\-185). +.IP KECCAK\-KMAC\-256 4 +.IX Item "KECCAK-KMAC-256" +Known names are "KECCAK\-KMAC\-256" and "KECCAK\-KMAC256". This is used +by \fBEVP_MAC\-KMAC256\fR\|(7). Using the notation from NIST FIPS 202 +(Section 6.2), we have KECCAK\-KMAC\-256(M,\ d) = KECCAK[512](M\ ||\ 00,\ d) +(see the description of KMAC256 in Appendix A of NIST SP 800\-185). +.IP SHAKE\-128 4 +.IX Item "SHAKE-128" +Known names are "SHAKE\-128" and "SHAKE128". +.IP SHAKE\-256 4 +.IX Item "SHAKE-256" +Known names are "SHAKE\-256" and "SHAKE256". +.SS Parameters +.IX Subsection "Parameters" +This implementation supports the following \fBOSSL_PARAM\fR\|(3) entries: +.IP """xoflen"" (\fBOSSL_DIGEST_PARAM_XOFLEN\fR) " 4 +.IX Item """xoflen"" (OSSL_DIGEST_PARAM_XOFLEN) " +Sets or Gets the digest length for extendable output functions. +The length of the "xoflen" parameter should not exceed that of a \fBsize_t\fR. +.Sp +The SHAKE\-128 and SHAKE\-256 implementations do not have any default digest +length. +.Sp +This parameter must be set before calling either \fBEVP_DigestFinal_ex()\fR or +\&\fBEVP_DigestFinal()\fR, since these functions were not designed to handle variable +length output. It is recommended to either use \fBEVP_DigestSqueeze()\fR or +\&\fBEVP_DigestFinalXOF()\fR instead. +.IP """size"" (\fBOSSL_DIGEST_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_DIGEST_PARAM_SIZE) " +An alias of "xoflen". +.PP +See "PARAMETERS" in \fBEVP_DigestInit\fR\|(3) for further information related to parameters +.SH NOTES +.IX Header "NOTES" +For SHAKE\-128, to ensure the maximum security strength of 128 bits, the output +length passed to \fBEVP_DigestFinalXOF()\fR should be at least 32. +.PP +For SHAKE\-256, to ensure the maximum security strength of 256 bits, the output +length passed to \fBEVP_DigestFinalXOF()\fR should be at least 64. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MD_CTX_set_params\fR\|(3), \fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +Since OpenSSL 3.4 the SHAKE\-128 and SHAKE\-256 implementations have no default +digest length. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-SM3.7 b/static/netbsd/man7/EVP_MD-SM3.7 new file mode 100644 index 00000000..6a9d16f0 --- /dev/null +++ b/static/netbsd/man7/EVP_MD-SM3.7 @@ -0,0 +1,91 @@ +.\" $NetBSD: EVP_MD-SM3.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-SM3 7" +.TH EVP_MD-SM3 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-SM3 \- The SM3 EVP_MD implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing SM3 digests through the \fBEVP_MD\fR API. +.SS Identity +.IX Subsection "Identity" +This implementation is only available with the default provider, and is +identified with the name "SM3". +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-WHIRLPOOL.7 b/static/netbsd/man7/EVP_MD-WHIRLPOOL.7 new file mode 100644 index 00000000..57c341cf --- /dev/null +++ b/static/netbsd/man7/EVP_MD-WHIRLPOOL.7 @@ -0,0 +1,91 @@ +.\" $NetBSD: EVP_MD-WHIRLPOOL.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-WHIRLPOOL 7" +.TH EVP_MD-WHIRLPOOL 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-WHIRLPOOL \- The WHIRLPOOL EVP_MD implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing WHIRLPOOL digests through the \fBEVP_MD\fR API. +.SS Identity +.IX Subsection "Identity" +This implementation is only available with the legacy provider, and is +identified with the name "WHIRLPOOL". +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_MD-common.7 b/static/netbsd/man7/EVP_MD-common.7 new file mode 100644 index 00000000..3d521cef --- /dev/null +++ b/static/netbsd/man7/EVP_MD-common.7 @@ -0,0 +1,107 @@ +.\" $NetBSD: EVP_MD-common.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD-COMMON 7" +.TH EVP_MD-COMMON 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD\-common \- The OpenSSL EVP_MD implementations, common things +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All the OpenSSL EVP_MD implementations understand the following +\&\fBOSSL_PARAM\fR\|(3) entries that are +gettable with \fBEVP_MD_get_params\fR\|(3), as well as these: +.IP """blocksize"" (\fBOSSL_DIGEST_PARAM_BLOCK_SIZE\fR) " 4 +.IX Item """blocksize"" (OSSL_DIGEST_PARAM_BLOCK_SIZE) " +The digest block size. +The length of the "blocksize" parameter should not exceed that of a +\&\fBsize_t\fR. +.Sp +This value can also be retrieved with \fBEVP_MD_get_block_size\fR\|(3). +.IP """size"" (\fBOSSL_DIGEST_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_DIGEST_PARAM_SIZE) " +The digest output size. +The length of the "size" parameter should not exceed that of a \fBsize_t\fR. +.Sp +This value can also be retrieved with \fBEVP_MD_get_size\fR\|(3). +.IP """flags"" (\fBOSSL_DIGEST_PARAM_FLAGS\fR) " 4 +.IX Item """flags"" (OSSL_DIGEST_PARAM_FLAGS) " +Diverse flags that describe exceptional behaviour for the digest. +These flags are described in "DESCRIPTION" in \fBEVP_MD_meth_set_flags\fR\|(3). +.Sp +The length of the "flags" parameter should equal that of an +\&\fBunsigned long int\fR. +.Sp +This value can also be retrieved with \fBEVP_MD_get_flags\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +"PARAMETERS" in \fBEVP_DigestInit\fR\|(3), \fBEVP_MD_get_params\fR\|(3), \fBprovider\-digest\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_PKEY-DH.7 b/static/netbsd/man7/EVP_PKEY-DH.7 new file mode 100644 index 00000000..5f2c7376 --- /dev/null +++ b/static/netbsd/man7/EVP_PKEY-DH.7 @@ -0,0 +1,374 @@ +.\" $NetBSD: EVP_PKEY-DH.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY-DH 7" +.TH EVP_PKEY-DH 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY\-DH, EVP_PKEY\-DHX, EVP_KEYMGMT\-DH, EVP_KEYMGMT\-DHX +\&\- EVP_PKEY DH and DHX keytype and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +For finite field Diffie\-Hellman key agreement, two classes of domain +parameters can be used: "safe" domain parameters that are associated with +approved named safe\-prime groups, and a class of "FIPS186\-type" domain +parameters. FIPS186\-type domain parameters should only be used for backward +compatibility with existing applications that cannot be upgraded to use the +approved safe\-prime groups. +.PP +See \fBEVP_PKEY\-FFC\fR\|(7) for more information about FFC keys. +.PP +The \fBDH\fR key type uses PKCS#3 format which saves \fIp\fR and \fIg\fR, but not the +\&\fIq\fR value. +The \fBDHX\fR key type uses X9.42 format which saves the value of \fIq\fR and this +must be used for FIPS186\-4. If key validation is required, users should be aware +of the nuances associated with FIPS186\-4 style parameters as discussed in +"DH and DHX key validation". +.SS "DH and DHX domain parameters" +.IX Subsection "DH and DHX domain parameters" +In addition to the common FFC parameters that all FFC keytypes should support +(see "FFC parameters" in \fBEVP_PKEY\-FFC\fR\|(7)) the \fBDHX\fR and \fBDH\fR keytype +implementations support the following: +.IP """group"" (\fBOSSL_PKEY_PARAM_GROUP_NAME\fR) " 4 +.IX Item """group"" (OSSL_PKEY_PARAM_GROUP_NAME) " +Sets or gets a string that associates a \fBDH\fR or \fBDHX\fR named safe prime group +with known values for \fIp\fR, \fIq\fR and \fIg\fR. +.Sp +The following values can be used by the OpenSSL\*(Aqs default and FIPS providers: +"ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192", +"modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192". +.Sp +The following additional values can also be used by OpenSSL\*(Aqs default provider: +"modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256". +.Sp +DH/DHX named groups can be easily validated since the parameters are well known. +For protocols that only transfer \fIp\fR and \fIg\fR the value of \fIq\fR can also be +retrieved. +.SS "DH and DHX additional parameters" +.IX Subsection "DH and DHX additional parameters" +.IP """encoded\-pub\-key"" (\fBOSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\fR) " 4 +.IX Item """encoded-pub-key"" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) " +Used for getting and setting the encoding of the DH public key used in a key +exchange message for the TLS protocol. +See \fBEVP_PKEY_set1_encoded_public_key()\fR and \fBEVP_PKEY_get1_encoded_public_key()\fR. +.SS "DH additional domain parameters" +.IX Subsection "DH additional domain parameters" +.IP """safeprime\-generator"" (\fBOSSL_PKEY_PARAM_DH_GENERATOR\fR) " 4 +.IX Item """safeprime-generator"" (OSSL_PKEY_PARAM_DH_GENERATOR) " +Used for DH generation of safe primes using the old safe prime generator code. +The default value is 2. +It is recommended to use a named safe prime group instead, if domain parameter +validation is required. +.Sp +Randomly generated safe primes are not allowed by FIPS, so setting this value +for the OpenSSL FIPS provider will instead choose a named safe prime group +based on the size of \fIp\fR. +.SS "DH and DHX domain parameter / key generation parameters" +.IX Subsection "DH and DHX domain parameter / key generation parameters" +In addition to the common FFC key generation parameters that all FFC key types +should support (see "FFC key generation parameters" in \fBEVP_PKEY\-FFC\fR\|(7)) the +\&\fBDH\fR and \fBDHX\fR keytype implementation supports the following: +.IP """type"" (\fBOSSL_PKEY_PARAM_FFC_TYPE\fR) " 4 +.IX Item """type"" (OSSL_PKEY_PARAM_FFC_TYPE) " +Sets the type of parameter generation. For \fBDH\fR valid values are: +.RS 4 +.IP """fips186_4""" 4 +.IX Item """fips186_4""" +.PD 0 +.IP """default""" 4 +.IX Item """default""" +.IP """fips186_2""" 4 +.IX Item """fips186_2""" +.PD +These are described in "FFC key generation parameters" in \fBEVP_PKEY\-FFC\fR\|(7) +.IP """group""" 4 +.IX Item """group""" +This specifies that a named safe prime name will be chosen using the "pbits" +type. +.IP """generator""" 4 +.IX Item """generator""" +A safe prime generator. See the "safeprime\-generator" type above. +This is only valid for \fBDH\fR keys. +.RE +.RS 4 +.RE +.IP """pbits"" (\fBOSSL_PKEY_PARAM_FFC_PBITS\fR) " 4 +.IX Item """pbits"" (OSSL_PKEY_PARAM_FFC_PBITS) " +Sets the size (in bits) of the prime \*(Aqp\*(Aq. +.Sp +For "fips186_4" this must be 2048. +For "fips186_2" this must be 1024. +For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192. +.IP """priv_len"" (\fBOSSL_PKEY_PARAM_DH_PRIV_LEN\fR) " 4 +.IX Item """priv_len"" (OSSL_PKEY_PARAM_DH_PRIV_LEN) " +An optional value to set the maximum length of the generated private key. +The default value used if this is not set is the maximum value of +BN_num_bits(\fIq\fR)). The minimum value that this can be set to is 2 * s. +Where s is the security strength of the key which has values of +112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192. +.SS "DH and DHX key validation" +.IX Subsection "DH and DHX key validation" +For keys that are not a named group the FIPS186\-4 standard specifies that the +values used for FFC parameter generation are also required for parameter +validation. This means that optional FFC domain parameter values for +\&\fIseed\fR, \fIpcounter\fR and \fIgindex\fR or \fIhindex\fR may need to be stored for +validation purposes. +For \fBDHX\fR the \fIseed\fR and \fIpcounter\fR can be stored in ASN1 data +(but the \fIgindex\fR or \fIhindex\fR cannot be stored). It is recommended to use a +\&\fBDH\fR parameters with named safe prime group instead. +.PP +With the OpenSSL FIPS provider, \fBEVP_PKEY_param_check\fR\|(3) and +\&\fBEVP_PKEY_param_check_quick\fR\|(3) behave in the following way: the parameters +are tested if they are either an approved safe prime group OR that the FFC +parameters conform to FIPS186\-4 as defined in SP800\-56Ar3 \fIAssurances of +Domain\-Parameter Validity\fR. +.PP +The OpenSSL default provider uses simpler checks that allows there to be no \fIq\fR +value for backwards compatibility, however the \fBEVP_PKEY_param_check\fR\|(3) will +test the \fIp\fR value for being a prime (and a safe prime if \fIq\fR is missing) +which can take significant time. The \fBEVP_PKEY_param_check_quick\fR\|(3) avoids +the prime tests. +.PP +\&\fBEVP_PKEY_public_check\fR\|(3) conforms to SP800\-56Ar3 +\&\fIFFC Full Public\-Key Validation\fR. +.PP +\&\fBEVP_PKEY_public_check_quick\fR\|(3) conforms to SP800\-56Ar3 +\&\fIFFC Partial Public\-Key Validation\fR when the key is an approved named safe +prime group, otherwise it is the same as \fBEVP_PKEY_public_check\fR\|(3). +.PP +\&\fBEVP_PKEY_private_check\fR\|(3) tests that the private key is in the correct range +according to SP800\-56Ar3. The OpenSSL FIPS provider requires the value of \fIq\fR +to be set (note that this is implicitly set for named safe prime groups). +For backwards compatibility the OpenSSL default provider only requires \fIp\fR to +be set. +.PP +\&\fBEVP_PKEY_pairwise_check\fR\|(3) conforms to SP800\-56Ar3 +\&\fIOwner Assurance of Pair\-wise Consistency\fR. +.SH EXAMPLES +.IX Header "EXAMPLES" +An \fBEVP_PKEY\fR context can be obtained by calling: +.PP +.Vb 1 +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); +.Ve +.PP +A \fBDH\fR key can be generated with a named safe prime group by calling: +.PP +.Vb 4 +\& int priv_len = 2 * 112; +\& OSSL_PARAM params[3]; +\& EVP_PKEY *pkey = NULL; +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); +\& +\& params[0] = OSSL_PARAM_construct_utf8_string("group", "ffdhe2048", 0); +\& /* "priv_len" is optional */ +\& params[1] = OSSL_PARAM_construct_int("priv_len", &priv_len); +\& params[2] = OSSL_PARAM_construct_end(); +\& +\& EVP_PKEY_keygen_init(pctx); +\& EVP_PKEY_CTX_set_params(pctx, params); +\& EVP_PKEY_generate(pctx, &pkey); +\& ... +\& EVP_PKEY_free(pkey); +\& EVP_PKEY_CTX_free(pctx); +.Ve +.PP +\&\fBDHX\fR domain parameters can be generated according to \fBFIPS186\-4\fR by calling: +.PP +.Vb 6 +\& int gindex = 2; +\& unsigned int pbits = 2048; +\& unsigned int qbits = 256; +\& OSSL_PARAM params[6]; +\& EVP_PKEY *param_key = NULL; +\& EVP_PKEY_CTX *pctx = NULL; +\& +\& pctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL); +\& EVP_PKEY_paramgen_init(pctx); +\& +\& params[0] = OSSL_PARAM_construct_uint("pbits", &pbits); +\& params[1] = OSSL_PARAM_construct_uint("qbits", &qbits); +\& params[2] = OSSL_PARAM_construct_int("gindex", &gindex); +\& params[3] = OSSL_PARAM_construct_utf8_string("type", "fips186_4", 0); +\& params[4] = OSSL_PARAM_construct_utf8_string("digest", "SHA256", 0); +\& params[5] = OSSL_PARAM_construct_end(); +\& EVP_PKEY_CTX_set_params(pctx, params); +\& +\& EVP_PKEY_generate(pctx, ¶m_key); +\& +\& EVP_PKEY_print_params(bio_out, param_key, 0, NULL); +\& ... +\& EVP_PKEY_free(param_key); +\& EVP_PKEY_CTX_free(pctx); +.Ve +.PP +A \fBDH\fR key can be generated using domain parameters by calling: +.PP +.Vb 2 +\& EVP_PKEY *key = NULL; +\& EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL); +\& +\& EVP_PKEY_keygen_init(gctx); +\& EVP_PKEY_generate(gctx, &key); +\& EVP_PKEY_print_private(bio_out, key, 0, NULL); +\& ... +\& EVP_PKEY_free(key); +\& EVP_PKEY_CTX_free(gctx); +.Ve +.PP +To validate \fBFIPS186\-4\fR \fBDHX\fR domain parameters decoded from \fBPEM\fR or +\&\fBDER\fR data, additional values used during generation may be required to +be set into the key. +.PP +\&\fBEVP_PKEY_todata()\fR, \fBOSSL_PARAM_merge()\fR, and \fBEVP_PKEY_fromdata()\fR are useful +to add these parameters to the original key or domain parameters before +the actual validation. In production code the return values should be checked. +.PP +.Vb 11 +\& EVP_PKEY *received_domp = ...; /* parameters received and decoded */ +\& unsigned char *seed = ...; /* and additional parameters received */ +\& size_t seedlen = ...; /* by other means, required */ +\& int gindex = ...; /* for the validation */ +\& int pcounter = ...; +\& int hindex = ...; +\& OSSL_PARAM extra_params[4]; +\& OSSL_PARAM *domain_params = NULL; +\& OSSL_PARAM *merged_params = NULL; +\& EVP_PKEY_CTX *ctx = NULL, *validate_ctx = NULL; +\& EVP_PKEY *complete_domp = NULL; +\& +\& EVP_PKEY_todata(received_domp, OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, +\& &domain_params); +\& extra_params[0] = OSSL_PARAM_construct_octet_string("seed", seed, seedlen); +\& /* +\& * NOTE: For unverifiable g use "hindex" instead of "gindex" +\& * extra_params[1] = OSSL_PARAM_construct_int("hindex", &hindex); +\& */ +\& extra_params[1] = OSSL_PARAM_construct_int("gindex", &gindex); +\& extra_params[2] = OSSL_PARAM_construct_int("pcounter", &pcounter); +\& extra_params[3] = OSSL_PARAM_construct_end(); +\& merged_params = OSSL_PARAM_merge(domain_params, extra_params); +\& +\& ctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL); +\& EVP_PKEY_fromdata_init(ctx); +\& EVP_PKEY_fromdata(ctx, &complete_domp, OSSL_KEYMGMT_SELECT_ALL, +\& merged_params); +\& +\& validate_ctx = EVP_PKEY_CTX_new_from_pkey(NULL, complete_domp, NULL); +\& if (EVP_PKEY_param_check(validate_ctx) > 0) +\& /* validation_passed(); */ +\& else +\& /* validation_failed(); */ +\& +\& OSSL_PARAM_free(domain_params); +\& OSSL_PARAM_free(merged_params); +\& EVP_PKEY_CTX_free(ctx); +\& EVP_PKEY_CTX_free(validate_ctx); +\& EVP_PKEY_free(complete_domp); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP "RFC 7919 (TLS ffdhe named safe prime groups)" 4 +.IX Item "RFC 7919 (TLS ffdhe named safe prime groups)" +.PD 0 +.IP "RFC 3526 (IKE modp named safe prime groups)" 4 +.IX Item "RFC 3526 (IKE modp named safe prime groups)" +.IP "RFC 5114 (Additional DH named groups for dh_1024_160"", ""dh_2048_224"" and ""dh_2048_256"")." 4 +.IX Item "RFC 5114 (Additional DH named groups for dh_1024_160"", ""dh_2048_224"" and ""dh_2048_256"")." +.PD +.PP +The following sections of SP800\-56Ar3: +.IP "5.5.1.1 FFC Domain Parameter Selection/Generation" 4 +.IX Item "5.5.1.1 FFC Domain Parameter Selection/Generation" +.PD 0 +.IP "Appendix D: FFC Safe\-prime Groups" 4 +.IX Item "Appendix D: FFC Safe-prime Groups" +.PD +.PP +The following sections of FIPS186\-4: +.IP "A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function." 4 +.IX Item "A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function." +.PD 0 +.IP "A.2.3 Generation of canonical generator g." 4 +.IX Item "A.2.3 Generation of canonical generator g." +.IP "A.2.1 Unverifiable Generation of the Generator g." 4 +.IX Item "A.2.1 Unverifiable Generation of the Generator g." +.PD +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY\-FFC\fR\|(7), +\&\fBEVP_KEYEXCH\-DH\fR\|(7) +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBEVP_KEYMGMT\fR\|(3), +\&\fBOSSL_PROVIDER\-default\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_PKEY-DSA.7 b/static/netbsd/man7/EVP_PKEY-DSA.7 new file mode 100644 index 00000000..ec5bfff4 --- /dev/null +++ b/static/netbsd/man7/EVP_PKEY-DSA.7 @@ -0,0 +1,196 @@ +.\" $NetBSD: EVP_PKEY-DSA.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY-DSA 7" +.TH EVP_PKEY-DSA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY\-DSA, EVP_KEYMGMT\-DSA \- EVP_PKEY DSA keytype and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +For \fBDSA\fR the FIPS 186\-4 standard specifies that the values used for FFC +parameter generation are also required for parameter validation. +This means that optional FFC domain parameter values for \fIseed\fR, \fIpcounter\fR +and \fIgindex\fR may need to be stored for validation purposes. For \fBDSA\fR these +fields are not stored in the ASN1 data so they need to be stored externally if +validation is required. +.PP +As part of FIPS 140\-3 DSA is not longer FIPS approved for key generation and +signature validation, but is still allowed for signature verification. +.SS "DSA parameters" +.IX Subsection "DSA parameters" +The \fBDSA\fR key type supports the FFC parameters (see +"FFC parameters" in \fBEVP_PKEY\-FFC\fR\|(7)). +.PP +It also supports the following parameters: +.IP """sign\-check"" (\fBOSSL_PKEY_PARAM_FIPS_SIGN_CHECK\fR) " 4 +.IX Item """fips-indicator"" (OSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR) " +.PD +See "Common Information Parameters" in \fBprovider\-keymgmt\fR\|(7) for more information. +.SS "DSA key generation parameters" +.IX Subsection "DSA key generation parameters" +The \fBDSA\fR key type supports the FFC key generation parameters (see +"FFC key generation parameters" in \fBEVP_PKEY\-FFC\fR\|(7) +.PP +The following restrictions apply to the "pbits" field: +.PP +For "fips186_4" this must be either 2048 or 3072. +For "fips186_2" this must be 1024. +For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192. +.SS "DSA key validation" +.IX Subsection "DSA key validation" +For DSA keys, \fBEVP_PKEY_param_check\fR\|(3) behaves in the following way: +The OpenSSL FIPS provider conforms to the rules within the FIPS186\-4 +standard for FFC parameter validation. For backwards compatibility the OpenSSL +default provider uses a much simpler check (see below) for parameter validation, +unless the seed parameter is set. +.PP +For DSA keys, \fBEVP_PKEY_param_check_quick\fR\|(3) behaves in the following way: +A simple check of L and N and partial g is performed. The default provider +also supports validation of legacy "fips186_2" keys. +.PP +For DSA keys, \fBEVP_PKEY_public_check\fR\|(3), \fBEVP_PKEY_private_check\fR\|(3) and +\&\fBEVP_PKEY_pairwise_check\fR\|(3) the OpenSSL default and FIPS providers conform to +the rules within SP800\-56Ar3 for public, private and pairwise tests respectively. +.SH EXAMPLES +.IX Header "EXAMPLES" +An \fBEVP_PKEY\fR context can be obtained by calling: +.PP +.Vb 1 +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL); +.Ve +.PP +The \fBDSA\fR domain parameters can be generated by calling: +.PP +.Vb 6 +\& unsigned int pbits = 2048; +\& unsigned int qbits = 256; +\& int gindex = 1; +\& OSSL_PARAM params[5]; +\& EVP_PKEY *param_key = NULL; +\& EVP_PKEY_CTX *pctx = NULL; +\& +\& pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL); +\& EVP_PKEY_paramgen_init(pctx); +\& +\& params[0] = OSSL_PARAM_construct_uint("pbits", &pbits); +\& params[1] = OSSL_PARAM_construct_uint("qbits", &qbits); +\& params[2] = OSSL_PARAM_construct_int("gindex", &gindex); +\& params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA384", 0); +\& params[4] = OSSL_PARAM_construct_end(); +\& EVP_PKEY_CTX_set_params(pctx, params); +\& +\& EVP_PKEY_generate(pctx, ¶m_key); +\& EVP_PKEY_CTX_free(pctx); +\& +\& EVP_PKEY_print_params(bio_out, param_key, 0, NULL); +.Ve +.PP +A \fBDSA\fR key can be generated using domain parameters by calling: +.PP +.Vb 2 +\& EVP_PKEY *key = NULL; +\& EVP_PKEY_CTX *gctx = NULL; +\& +\& gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL); +\& EVP_PKEY_keygen_init(gctx); +\& EVP_PKEY_generate(gctx, &key); +\& EVP_PKEY_CTX_free(gctx); +\& EVP_PKEY_print_private(bio_out, key, 0, NULL); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +The following sections of FIPS186\-4: +.IP "A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function." 4 +.IX Item "A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function." +.PD 0 +.IP "A.2.3 Generation of canonical generator g." 4 +.IX Item "A.2.3 Generation of canonical generator g." +.IP "A.2.1 Unverifiable Generation of the Generator g." 4 +.IX Item "A.2.1 Unverifiable Generation of the Generator g." +.PD +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY\-FFC\fR\|(7), +\&\fBEVP_SIGNATURE\-DSA\fR\|(7), +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBEVP_KEYMGMT\fR\|(3), +\&\fBOSSL_PROVIDER\-default\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +DSA Key generation and signature generation are no longer FIPS approved in +OpenSSL 3.4. See "FIPS indicators" in \fBfips_module\fR\|(7) for more information. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_PKEY-EC.7 b/static/netbsd/man7/EVP_PKEY-EC.7 new file mode 100644 index 00000000..6fe6de5c --- /dev/null +++ b/static/netbsd/man7/EVP_PKEY-EC.7 @@ -0,0 +1,344 @@ +.\" $NetBSD: EVP_PKEY-EC.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY-EC 7" +.TH EVP_PKEY-EC 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY\-EC, +EVP_KEYMGMT\-EC +\&\- EVP_PKEY EC keytype and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBEC\fR keytype is implemented in OpenSSL\*(Aqs default provider. +.SS "Common EC parameters" +.IX Subsection "Common EC parameters" +The normal way of specifying domain parameters for an EC curve is via the +curve name "group". For curves with no curve name, explicit parameters can be +used that specify "field\-type", "p", "a", "b", "generator" and "order". +Explicit parameters are supported for backwards compatibility reasons, but they +are not compliant with multiple standards (including RFC5915) which only allow +named curves. +.PP +The following Key generation/Gettable/Import/Export types are available for the +built\-in EC algorithm: +.IP """group"" (\fBOSSL_PKEY_PARAM_GROUP_NAME\fR) " 4 +.IX Item """group"" (OSSL_PKEY_PARAM_GROUP_NAME) " +The curve name. +.IP """field\-type"" (\fBOSSL_PKEY_PARAM_EC_FIELD_TYPE\fR) " 4 +.IX Item """field-type"" (OSSL_PKEY_PARAM_EC_FIELD_TYPE) " +The value should be either "prime\-field" or "characteristic\-two\-field", +which correspond to prime field Fp and binary field F2^m. +.IP """p"" (\fBOSSL_PKEY_PARAM_EC_P\fR) " 4 +.IX Item """p"" (OSSL_PKEY_PARAM_EC_P) " +For a curve over Fp \fIp\fR is the prime for the field. For a curve over F2^m \fIp\fR +represents the irreducible polynomial \- each bit represents a term in the +polynomial. Therefore, there will either be three or five bits set dependent on +whether the polynomial is a trinomial or a pentanomial. +.IP """a"" (\fBOSSL_PKEY_PARAM_EC_A\fR) " 4 +.IX Item """a"" (OSSL_PKEY_PARAM_EC_A) " +.PD 0 +.IP """b"" (\fBOSSL_PKEY_PARAM_EC_B\fR) " 4 +.IX Item """b"" (OSSL_PKEY_PARAM_EC_B) " +.IP """seed"" (\fBOSSL_PKEY_PARAM_EC_SEED\fR) " 4 +.IX Item """seed"" (OSSL_PKEY_PARAM_EC_SEED) " +.PD +\&\fIa\fR and \fIb\fR represents the coefficients of the curve +For Fp: y^2 mod p = x^3 +ax + b mod p OR +For F2^m: y^2 + xy = x^3 + ax^2 + b +.Sp +\&\fIseed\fR is an optional value that is for information purposes only. +It represents the random number seed used to generate the coefficient \fIb\fR from a +random number. +.IP """generator"" (\fBOSSL_PKEY_PARAM_EC_GENERATOR\fR) " 4 +.IX Item """generator"" (OSSL_PKEY_PARAM_EC_GENERATOR) " +.PD 0 +.IP """order"" (\fBOSSL_PKEY_PARAM_EC_ORDER\fR) " 4 +.IX Item """order"" (OSSL_PKEY_PARAM_EC_ORDER) " +.IP """cofactor"" (\fBOSSL_PKEY_PARAM_EC_COFACTOR\fR) " 4 +.IX Item """cofactor"" (OSSL_PKEY_PARAM_EC_COFACTOR) " +.PD +The \fIgenerator\fR is a well defined point on the curve chosen for cryptographic +operations. The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 ("Elliptic Curve +Cryptography") standard. See \fBEC_POINT_oct2point()\fR. +Integers used for point multiplications will be between 0 and +\&\fIorder\fR \- 1. +\&\fIcofactor\fR is an optional value. +\&\fIorder\fR multiplied by the \fIcofactor\fR gives the number of points on the curve. +.IP """decoded\-from\-explicit"" (\fBOSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS\fR) " 4 +.IX Item """decoded-from-explicit"" (OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS) " +Gets a flag indicating whether the key or parameters were decoded from explicit +curve parameters. Set to 1 if so or 0 if a named curve was used. +.IP """use\-cofactor\-flag"" (\fBOSSL_PKEY_PARAM_USE_COFACTOR_ECDH\fR) " 4 +.IX Item """use-cofactor-flag"" (OSSL_PKEY_PARAM_USE_COFACTOR_ECDH) " +Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal EC DH +if the value is zero. The cofactor variant multiplies the shared secret by the +EC curve\*(Aqs cofactor (note for some curves the cofactor is 1). +.Sp +See also \fBEVP_KEYEXCH\-ECDH\fR\|(7) for the related +\&\fBOSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE\fR parameter that can be set on a +per\-operation basis. +.IP """encoding"" (\fBOSSL_PKEY_PARAM_EC_ENCODING\fR) " 4 +.IX Item """encoding"" (OSSL_PKEY_PARAM_EC_ENCODING) " +Set the format used for serializing the EC group parameters. +Valid values are "explicit" or "named_curve". The default value is "named_curve". +.IP """point\-format"" (\fBOSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT\fR) " 4 +.IX Item """point-format"" (OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT) " +Sets or gets the point_conversion_form for the \fIkey\fR. For a description of +point_conversion_forms please see \fBEC_POINT_new\fR\|(3). Valid values are +"uncompressed" or "compressed". The default value is "uncompressed". +.IP """group\-check"" (\fBOSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE\fR) " 4 +.IX Item """group-check"" (OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE) " +Sets or Gets the type of group check done when \fBEVP_PKEY_param_check()\fR is called. +Valid values are "default", "named" and "named\-nist". +The "named" type checks that the domain parameters match the inbuilt curve parameters, +"named\-nist" is similar but also checks that the named curve is a nist curve. +The "default" type does domain parameter validation for the OpenSSL default provider, +but is equivalent to "named\-nist" for the OpenSSL FIPS provider. +.IP """include\-public"" (\fBOSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC\fR) " 4 +.IX Item """include-public"" (OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC) " +Setting this value to 0 indicates that the public key should not be included when +encoding the private key. The default value of 1 will include the public key. +.IP """pub"" (\fBOSSL_PKEY_PARAM_PUB_KEY\fR) " 4 +.IX Item """pub"" (OSSL_PKEY_PARAM_PUB_KEY) " +The public key value in encoded EC point format conforming to Sec. 2.3.3 and +2.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard. +This parameter is used when importing or exporting the public key value with the +\&\fBEVP_PKEY_fromdata()\fR and \fBEVP_PKEY_todata()\fR functions. +.Sp +Note, in particular, that the choice of point compression format used for +encoding the exported value via \fBEVP_PKEY_todata()\fR depends on the underlying +provider implementation. +Before OpenSSL 3.0.8, the implementation of providers included with OpenSSL always +opted for an encoding in compressed format, unconditionally. +Since OpenSSL 3.0.8, the implementation has been changed to honor the +\&\fBOSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT\fR parameter, if set, or to default +to uncompressed format. +.IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\fR) " 4 +.IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) " +The private key value. +.IP """encoded\-pub\-key"" (\fBOSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\fR) " 4 +.IX Item """encoded-pub-key"" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) " +Used for getting and setting the encoding of an EC public key. The public key +is expected to be a point conforming to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic +Curve Cryptography") standard. +.IP """qx"" (\fBOSSL_PKEY_PARAM_EC_PUB_X\fR) " 4 +.IX Item """qx"" (OSSL_PKEY_PARAM_EC_PUB_X) " +Used for getting the EC public key X component. +.IP """qy"" (\fBOSSL_PKEY_PARAM_EC_PUB_Y\fR) " 4 +.IX Item """qy"" (OSSL_PKEY_PARAM_EC_PUB_Y) " +Used for getting the EC public key Y component. +.IP """default\-digest"" (\fBOSSL_PKEY_PARAM_DEFAULT_DIGEST\fR) " 4 +.IX Item """default-digest"" (OSSL_PKEY_PARAM_DEFAULT_DIGEST) " +Getter that returns the default digest name. +(Currently returns "SHA256" as of OpenSSL 3.0). +.IP """dhkem\-ikm"" (\fBOSSL_PKEY_PARAM_DHKEM_IKM\fR) " 4 +.IX Item """dhkem-ikm"" (OSSL_PKEY_PARAM_DHKEM_IKM) " +DHKEM requires the generation of a keypair using an input key material (seed). +Use this to specify the key material used for generation of the private key. +This value should not be reused for other purposes. It can only be used +for the curves "P\-256", "P\-384" and "P\-521" and should have a length of at least +the size of the encoded private key (i.e. 32, 48 and 66 for the listed curves). +.PP +The following Gettable types are also available for the built\-in EC algorithm: +.IP """basis\-type"" (\fBOSSL_PKEY_PARAM_EC_CHAR2_TYPE\fR) " 4 +.IX Item """basis-type"" (OSSL_PKEY_PARAM_EC_CHAR2_TYPE) " +Supports the values "tpBasis" for a trinomial or "ppBasis" for a pentanomial. +This field is only used for a binary field F2^m. +.IP """m"" (\fBOSSL_PKEY_PARAM_EC_CHAR2_M\fR) " 4 +.IX Item """m"" (OSSL_PKEY_PARAM_EC_CHAR2_M) " +.PD 0 +.IP """tp"" (\fBOSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS\fR) " 4 +.IX Item """tp"" (OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS) " +.IP """k1"" (\fBOSSL_PKEY_PARAM_EC_CHAR2_PP_K1\fR) " 4 +.IX Item """k1"" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K1) " +.IP """k2"" (\fBOSSL_PKEY_PARAM_EC_CHAR2_PP_K2\fR) " 4 +.IX Item """k2"" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K2) " +.IP """k3"" (\fBOSSL_PKEY_PARAM_EC_CHAR2_PP_K3\fR) " 4 +.IX Item """k3"" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K3) " +.PD +These fields are only used for a binary field F2^m. +\&\fIm\fR is the degree of the binary field. +.Sp +\&\fItp\fR is the middle bit of a trinomial so its value must be in the +range m > tp > 0. +.Sp +\&\fIk1\fR, \fIk2\fR and \fIk3\fR are used to get the middle bits of a pentanomial such +that m > k3 > k2 > k1 > 0 +.PP +The following key generation settable parameter is also available for the +OpenSSL FIPS provider\*(Aqs EC algorithm: +.IP """key\-check"" (\fBOSSL_PKEY_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_PKEY_PARAM_FIPS_KEY_CHECK) " +See "Common Information Parameters" in \fBprovider\-keymgmt\fR\|(7) for further information. +.PP +The following key generation Gettable parameter is available for the OpenSSL +FIPS provider\*(Aqs EC algorithm: +.IP """fips\-indicator"" (\fBOSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR) " +See "Common Information Parameters" in \fBprovider\-keymgmt\fR\|(7) for further information. +.SS "EC key validation" +.IX Subsection "EC key validation" +For EC keys, \fBEVP_PKEY_param_check\fR\|(3) behaves in the following way: +For the OpenSSL default provider it uses either +\&\fBEC_GROUP_check\fR\|(3) or \fBEC_GROUP_check_named_curve\fR\|(3) depending on the flag +EC_FLAG_CHECK_NAMED_GROUP. +The OpenSSL FIPS provider uses \fBEC_GROUP_check_named_curve\fR\|(3) in order to +conform to SP800\-56Ar3 \fIAssurances of Domain\-Parameter Validity\fR. +.PP +For EC keys, \fBEVP_PKEY_param_check_quick\fR\|(3) is equivalent to +\&\fBEVP_PKEY_param_check\fR\|(3). +.PP +For EC keys, \fBEVP_PKEY_public_check\fR\|(3) and \fBEVP_PKEY_public_check_quick\fR\|(3) +conform to SP800\-56Ar3 \fIECC Full Public\-Key Validation\fR and +\&\fIECC Partial Public\-Key Validation\fR respectively. +.PP +For EC Keys, \fBEVP_PKEY_private_check\fR\|(3) and \fBEVP_PKEY_pairwise_check\fR\|(3) +conform to SP800\-56Ar3 \fIPrivate key validity\fR and +\&\fIOwner Assurance of Pair\-wise Consistency\fR respectively. +.SH EXAMPLES +.IX Header "EXAMPLES" +An \fBEVP_PKEY\fR context can be obtained by calling: +.PP +.Vb 2 +\& EVP_PKEY_CTX *pctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); +.Ve +.PP +An \fBEVP_PKEY\fR ECDSA or ECDH key can be generated with a "P\-256" named group by +calling: +.PP +.Vb 1 +\& pkey = EVP_EC_gen("P\-256"); +.Ve +.PP +or like this: +.PP +.Vb 4 +\& EVP_PKEY *key = NULL; +\& OSSL_PARAM params[2]; +\& EVP_PKEY_CTX *gctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); +\& +\& EVP_PKEY_keygen_init(gctx); +\& +\& params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME, +\& "P\-256", 0); +\& params[1] = OSSL_PARAM_construct_end(); +\& EVP_PKEY_CTX_set_params(gctx, params); +\& +\& EVP_PKEY_generate(gctx, &key); +\& +\& EVP_PKEY_print_private(bio_out, key, 0, NULL); +\& ... +\& EVP_PKEY_free(key); +\& EVP_PKEY_CTX_free(gctx); +.Ve +.PP +An \fBEVP_PKEY\fR EC CDH (Cofactor Diffie\-Hellman) key can be generated with a +"K\-571" named group by calling: +.PP +.Vb 5 +\& int use_cdh = 1; +\& EVP_PKEY *key = NULL; +\& OSSL_PARAM params[3]; +\& EVP_PKEY_CTX *gctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); +\& +\& EVP_PKEY_keygen_init(gctx); +\& +\& params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME, +\& "K\-571", 0); +\& /* +\& * This curve has a cofactor that is not 1 \- so setting CDH mode changes +\& * the behaviour. For many curves the cofactor is 1 \- so setting this has +\& * no effect. +\& */ +\& params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH, +\& &use_cdh); +\& params[2] = OSSL_PARAM_construct_end(); +\& EVP_PKEY_CTX_set_params(gctx, params); +\& +\& EVP_PKEY_generate(gctx, &key); +\& EVP_PKEY_print_private(bio_out, key, 0, NULL); +\& ... +\& EVP_PKEY_free(key); +\& EVP_PKEY_CTX_free(gctx); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_EC_gen\fR\|(3), +\&\fBEVP_KEYMGMT\fR\|(3), +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBEVP_SIGNATURE\-ECDSA\fR\|(7), +\&\fBEVP_KEYEXCH\-ECDH\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_PKEY-FFC.7 b/static/netbsd/man7/EVP_PKEY-FFC.7 new file mode 100644 index 00000000..540c9406 --- /dev/null +++ b/static/netbsd/man7/EVP_PKEY-FFC.7 @@ -0,0 +1,248 @@ +.\" $NetBSD: EVP_PKEY-FFC.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY-FFC 7" +.TH EVP_PKEY-FFC 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY\-FFC \- EVP_PKEY DSA and DH/DHX shared FFC parameters. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Finite field cryptography (FFC) is a method of implementing discrete logarithm +cryptography using finite field mathematics. DSA is an example of FFC and +Diffie\-Hellman key establishment algorithms specified in SP800\-56A can also be +implemented as FFC. +.PP +The \fBDSA\fR, \fBDH\fR and \fBDHX\fR keytypes are implemented in OpenSSL\*(Aqs default and +FIPS providers. +The implementations support the basic DSA, DH and DHX keys, containing the public +and private keys \fIpub\fR and \fIpriv\fR as well as the three main domain parameters +\&\fIp\fR, \fIq\fR and \fIg\fR. +.PP +For \fBDSA\fR (and \fBDH\fR that is not a named group) the FIPS186\-4 standard +specifies that the values used for FFC parameter generation are also required +for parameter validation. +This means that optional FFC domain parameter values for \fIseed\fR, \fIpcounter\fR +and \fIgindex\fR may need to be stored for validation purposes. +For \fBDH\fR the \fIseed\fR and \fIpcounter\fR can be stored in ASN1 data +(but the \fIgindex\fR is not). For \fBDSA\fR however, these fields are not stored in +the ASN1 data so they need to be stored externally if validation is required. +.PP +The \fBDH\fR key type uses PKCS#3 format which saves p and g, but not the \*(Aqq\*(Aq value. +The \fBDHX\fR key type uses X9.42 format which saves the value of \*(Aqq\*(Aq and this +must be used for FIPS186\-4. +.SS "FFC parameters" +.IX Subsection "FFC parameters" +In addition to the common parameters that all keytypes should support (see +"Common parameters" in \fBprovider\-keymgmt\fR\|(7)), the \fBDSA\fR, \fBDH\fR and \fBDHX\fR keytype +implementations support the following. +.IP """pub"" (\fBOSSL_PKEY_PARAM_PUB_KEY\fR) " 4 +.IX Item """pub"" (OSSL_PKEY_PARAM_PUB_KEY) " +The public key value. +.IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\fR) " 4 +.IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) " +The private key value. +.SS "FFC DSA, DH and DHX domain parameters" +.IX Subsection "FFC DSA, DH and DHX domain parameters" +.IP """p"" (\fBOSSL_PKEY_PARAM_FFC_P\fR) " 4 +.IX Item """p"" (OSSL_PKEY_PARAM_FFC_P) " +A DSA or Diffie\-Hellman prime "p" value. +.IP """g"" (\fBOSSL_PKEY_PARAM_FFC_G\fR) " 4 +.IX Item """g"" (OSSL_PKEY_PARAM_FFC_G) " +A DSA or Diffie\-Hellman generator "g" value. +.SS "FFC DSA and DHX domain parameters" +.IX Subsection "FFC DSA and DHX domain parameters" +.IP """q"" (\fBOSSL_PKEY_PARAM_FFC_Q\fR) " 4 +.IX Item """q"" (OSSL_PKEY_PARAM_FFC_Q) " +A DSA or Diffie\-Hellman prime "q" value. +.IP """seed"" (\fBOSSL_PKEY_PARAM_FFC_SEED\fR) " 4 +.IX Item """seed"" (OSSL_PKEY_PARAM_FFC_SEED) " +An optional domain parameter \fIseed\fR value used during generation and validation +of \fIp\fR, \fIq\fR and canonical \fIg\fR. +For validation this needs to set the \fIseed\fR that was produced during generation. +.IP """gindex"" (\fBOSSL_PKEY_PARAM_FFC_GINDEX\fR) " 4 +.IX Item """gindex"" (OSSL_PKEY_PARAM_FFC_GINDEX) " +Sets the index to use for canonical generation and verification of the generator +\&\fIg\fR. +Set this to a positive value from 0..FF to use this mode. This \fIgindex\fR can +then be reused during key validation to verify the value of \fIg\fR. If this value +is not set or is \-1 then unverifiable generation of the generator \fIg\fR will be +used. +.IP """pcounter"" (\fBOSSL_PKEY_PARAM_FFC_PCOUNTER\fR) " 4 +.IX Item """pcounter"" (OSSL_PKEY_PARAM_FFC_PCOUNTER) " +An optional domain parameter \fIcounter\fR value that is output during generation +of \fIp\fR. This value must be saved if domain parameter validation is required. +.IP """hindex"" (\fBOSSL_PKEY_PARAM_FFC_H\fR) " 4 +.IX Item """hindex"" (OSSL_PKEY_PARAM_FFC_H) " +For unverifiable generation of the generator \fIg\fR this value is output during +generation of \fIg\fR. Its value is the first integer larger than one that +satisfies g = h^j mod p (where g != 1 and "j" is the cofactor). +.IP """j"" (\fBOSSL_PKEY_PARAM_FFC_COFACTOR\fR) " 4 +.IX Item """j"" (OSSL_PKEY_PARAM_FFC_COFACTOR) " +An optional informational cofactor parameter that should equal to (p \- 1) / q. +.IP """validate\-pq"" (\fBOSSL_PKEY_PARAM_FFC_VALIDATE_PQ\fR) " 4 +.IX Item """validate-pq"" (OSSL_PKEY_PARAM_FFC_VALIDATE_PQ) " +.PD 0 +.IP """validate\-g"" (\fBOSSL_PKEY_PARAM_FFC_VALIDATE_G\fR) " 4 +.IX Item """validate-g"" (OSSL_PKEY_PARAM_FFC_VALIDATE_G) " +.PD +These boolean values are used during FIPS186\-4 or FIPS186\-2 key validation checks +(See \fBEVP_PKEY_param_check\fR\|(3)) to select validation options. By default +\&\fIvalidate\-pq\fR and \fIvalidate\-g\fR are both set to 1 to check that p,q and g are +valid. Either of these may be set to 0 to skip a test, which is mainly useful +for testing purposes. +.IP """validate\-legacy"" (\fBOSSL_PKEY_PARAM_FFC_VALIDATE_LEGACY\fR) " 4 +.IX Item """validate-legacy"" (OSSL_PKEY_PARAM_FFC_VALIDATE_LEGACY) " +This boolean value is used during key validation checks +(See \fBEVP_PKEY_param_check\fR\|(3)) to select the validation type. The default +value of 0 selects FIPS186\-4 validation. Setting this value to 1 selects +FIPS186\-2 validation. +.SS "FFC key generation parameters" +.IX Subsection "FFC key generation parameters" +The following key generation types are available for DSA and DHX algorithms: +.IP """type"" (\fBOSSL_PKEY_PARAM_FFC_TYPE\fR) " 4 +.IX Item """type"" (OSSL_PKEY_PARAM_FFC_TYPE) " +Sets the type of parameter generation. The shared valid values are: +.RS 4 +.IP """fips186_4""" 4 +.IX Item """fips186_4""" +The current standard. +.IP """fips186_2""" 4 +.IX Item """fips186_2""" +The old standard that should only be used for legacy purposes. +.IP """default""" 4 +.IX Item """default""" +This can choose one of "fips186_4" or "fips186_2" depending on other +parameters set for parameter generation. +.RE +.RS 4 +.RE +.IP """pbits"" (\fBOSSL_PKEY_PARAM_FFC_PBITS\fR) " 4 +.IX Item """pbits"" (OSSL_PKEY_PARAM_FFC_PBITS) " +Sets the size (in bits) of the prime \*(Aqp\*(Aq. +.IP """qbits"" (\fBOSSL_PKEY_PARAM_FFC_QBITS\fR) " 4 +.IX Item """qbits"" (OSSL_PKEY_PARAM_FFC_QBITS) " +Sets the size (in bits) of the prime \*(Aqq\*(Aq. +.Sp +For "fips186_4" this can be either 224 or 256. +For "fips186_2" this has a size of 160. +.IP """digest"" (\fBOSSL_PKEY_PARAM_FFC_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_PKEY_PARAM_FFC_DIGEST) " +Sets the Digest algorithm to be used as part of the Key Generation Function +associated with the given Key Generation \fIctx\fR. +This must also be set for key validation. +.IP """properties"" (\fBOSSL_PKEY_PARAM_FFC_DIGEST_PROPS\fR) " 4 +.IX Item """properties"" (OSSL_PKEY_PARAM_FFC_DIGEST_PROPS) " +Sets properties to be used upon look up of the implementation for the selected +Digest algorithm for the Key Generation Function associated with the given key +generation \fIctx\fR. This may also be set for key validation. +.IP """seed"" (\fBOSSL_PKEY_PARAM_FFC_SEED\fR) " 4 +.IX Item """seed"" (OSSL_PKEY_PARAM_FFC_SEED) " +For "fips186_4" or "fips186_2" generation this sets the \fIseed\fR data to use +instead of generating a random seed internally. This should be used for +testing purposes only. This will either produce fixed values for the generated +parameters OR it will fail if the seed did not generate valid primes. +.IP """gindex"" (\fBOSSL_PKEY_PARAM_FFC_GINDEX\fR) " 4 +.IX Item """gindex"" (OSSL_PKEY_PARAM_FFC_GINDEX) " +.PD 0 +.IP """pcounter"" (\fBOSSL_PKEY_PARAM_FFC_PCOUNTER\fR) " 4 +.IX Item """pcounter"" (OSSL_PKEY_PARAM_FFC_PCOUNTER) " +.IP """hindex"" (\fBOSSL_PKEY_PARAM_FFC_H\fR) " 4 +.IX Item """hindex"" (OSSL_PKEY_PARAM_FFC_H) " +.PD +These types are described above. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +The following sections of SP800\-56Ar3: +.IP "5.5.1.1 FFC Domain Parameter Selection/Generation" 4 +.IX Item "5.5.1.1 FFC Domain Parameter Selection/Generation" +.PP +The following sections of FIPS186\-4: +.IP "A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function." 4 +.IX Item "A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function." +.PD 0 +.IP "A.2.3 Generation of canonical generator g." 4 +.IX Item "A.2.3 Generation of canonical generator g." +.IP "A.2.1 Unverifiable Generation of the Generator g." 4 +.IX Item "A.2.1 Unverifiable Generation of the Generator g." +.PD +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY\-DSA\fR\|(7), +\&\fBEVP_PKEY\-DH\fR\|(7), +\&\fBEVP_SIGNATURE\-DSA\fR\|(7), +\&\fBEVP_KEYEXCH\-DH\fR\|(7), +\&\fBEVP_KEYMGMT\fR\|(3), +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBOSSL_PROVIDER\-default\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_PKEY-HMAC.7 b/static/netbsd/man7/EVP_PKEY-HMAC.7 new file mode 100644 index 00000000..67d89d2a --- /dev/null +++ b/static/netbsd/man7/EVP_PKEY-HMAC.7 @@ -0,0 +1,128 @@ +.\" $NetBSD: EVP_PKEY-HMAC.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY-HMAC 7" +.TH EVP_PKEY-HMAC 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY\-HMAC, EVP_KEYMGMT\-HMAC, EVP_PKEY\-Siphash, EVP_KEYMGMT\-Siphash, +EVP_PKEY\-Poly1305, EVP_KEYMGMT\-Poly1305, EVP_PKEY\-CMAC, EVP_KEYMGMT\-CMAC +\&\- EVP_PKEY legacy MAC keytypes and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBHMAC\fR and \fBCMAC\fR key types are implemented in OpenSSL\*(Aqs default and FIPS +providers. Additionally the \fBSiphash\fR and \fBPoly1305\fR key types are implemented +in the default provider. Performing MAC operations via an EVP_PKEY +is considered legacy and are only available for backwards compatibility purposes +and for a restricted set of algorithms. The preferred way of performing MAC +operations is via the EVP_MAC APIs. See \fBEVP_MAC_init\fR\|(3). +.PP +For further details on using EVP_PKEY based MAC keys see +\&\fBEVP_SIGNATURE\-HMAC\fR\|(7), \fBEVP_SIGNATURE\-Siphash\fR\|(7), +\&\fBEVP_SIGNATURE\-Poly1305\fR\|(7) or \fBEVP_SIGNATURE\-CMAC\fR\|(7). +.SS "Common MAC parameters" +.IX Subsection "Common MAC parameters" +All the \fBMAC\fR keytypes support the following parameters. +.IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\fR) " 4 +.IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) " +The MAC key value. +.IP """properties"" (\fBOSSL_PKEY_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_PKEY_PARAM_PROPERTIES) " +A property query string to be used when any algorithms are fetched. +.SS "CMAC parameters" +.IX Subsection "CMAC parameters" +As well as the parameters described above, the \fBCMAC\fR keytype additionally +supports the following parameters. +.IP """cipher"" (\fBOSSL_PKEY_PARAM_CIPHER\fR) " 4 +.IX Item """cipher"" (OSSL_PKEY_PARAM_CIPHER) " +The name of a cipher to be used when generating the MAC. +.IP """engine"" (\fBOSSL_PKEY_PARAM_ENGINE\fR) " 4 +.IX Item """engine"" (OSSL_PKEY_PARAM_ENGINE) " +The name of an engine to be used for the specified cipher (if any). +.SS "Common MAC key generation parameters" +.IX Subsection "Common MAC key generation parameters" +MAC key generation is unusual in that no new key is actually generated. Instead +a new provider side key object is created with the supplied raw key value. This +is done for backwards compatibility with previous versions of OpenSSL. +.IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\fR) " 4 +.IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) " +The MAC key value. +.SS "CMAC key generation parameters" +.IX Subsection "CMAC key generation parameters" +In addition to the common MAC key generation parameters, the CMAC key generation +additionally recognises the following. +.IP """cipher"" (\fBOSSL_PKEY_PARAM_CIPHER\fR) " 4 +.IX Item """cipher"" (OSSL_PKEY_PARAM_CIPHER) " +The name of a cipher to be used when generating the MAC. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KEYMGMT\fR\|(3), \fBEVP_PKEY\fR\|(3), \fBprovider\-keymgmt\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_PKEY-ML-DSA.7 b/static/netbsd/man7/EVP_PKEY-ML-DSA.7 new file mode 100644 index 00000000..f2c71c6e --- /dev/null +++ b/static/netbsd/man7/EVP_PKEY-ML-DSA.7 @@ -0,0 +1,354 @@ +.\" $NetBSD: EVP_PKEY-ML-DSA.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY-ML-DSA 7" +.TH EVP_PKEY-ML-DSA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY\-ML\-DSA, EVP_KEYMGMT\-ML\-DSA, +EVP_PKEY\-ML\-DSA\-44, EVP_PKEY\-ML\-DSA\-65, EVP_PKEY\-ML\-DSA\-87 +\&\- EVP_PKEY ML\-DSA keytype and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +ML\-DSA implements the algorithms \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR and \fBML\-DSA\-87\fR. +The key types \fBEVP_PKEY_ML_DSA_44\fR, \fBEVP_PKEY_ML_DSA_65\fR and +\&\fBEVP_PKEY_ML_DSA_87\fR are implemented in OpenSSL\*(Aqs default and FIPS providers. +These implementations support the associated key, containing the public key \fIpub\fR +and the private key \fIpriv\fR. +.PP +Each of the different key types has an associated security category. +This value is one of 2, 3 or 5 for key types \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR +and \fBML\-DSA\-87\fR respectively, which correspond to security strengths of +128, 192 and 256 respectively. +.SS "Keygen Parameters" +.IX Subsection "Keygen Parameters" +.IP """seed"" (\fBOSSL_PKEY_PARAM_ML_DSA_SEED\fR) " 4 +.IX Item """seed"" (OSSL_PKEY_PARAM_ML_DSA_SEED) " +The seed can be used to generate the private and public key components in a +deterministic manner. +The length of the value supplied must be 32 bytes. +When this value is not supplied the seed is generated randomly using a DRBG. +.Sp +Generated keys default to retaining the seed used. +The seed is also by default retained when keys are loaded from \fBPKCS#8\fR files +in the seed format. +When available, the seed parameter is also used during key export and import, +with keys (by default) regenerated from the seed even when also provided on import. +See "Provider configuration parameters" below for related controls. +.Sp +When the seed is retained, it is also available as a \fBgettable\fR parameter, +and private key output to \fBPKCS#8\fR files will by default include the seed. +When the seed was not initially known, or was not retained, \fBPKCS#8\fR private +key files will contain only the private key in FIPS 204 \f(CW\*(C`sk\*(C'\fR format. +.IP """properties"" (\fBOSSL_PKEY_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_PKEY_PARAM_PROPERTIES) " +Sets properties to be used when fetching algorithm implementations used for +ML\-DSA hashing operations. +.PP +Use \fBEVP_PKEY_CTX_set_params\fR\|(3) after calling \fBEVP_PKEY_keygen_init\fR\|(3). +.SS "Common ML\-DSA parameters" +.IX Subsection "Common ML-DSA parameters" +In addition to the common parameters that all keytypes should support (see +"Common Information Parameters" in \fBprovider\-keymgmt\fR\|(7), the implementation of +these key types support the parameters listed below. +These are gettable using +\&\fBEVP_PKEY_get_octet_string_param\fR\|(3) or \fBEVP_PKEY_get_params\fR\|(3). +They can be initialised via \fBEVP_PKEY_fromdata\fR\|(3), and are returned by +\&\fBEVP_PKEY_todata\fR\|(3) given a suitable \fIselection\fR. +Once a public or private key is configured, it can no longer be modified, +nor can another key component be added. +.IP """pub"" (\fBOSSL_PKEY_PARAM_PUB_KEY\fR) " 4 +.IX Item """pub"" (OSSL_PKEY_PARAM_PUB_KEY) " +The encoded public key value of size 1312, 1952 or 2592 bytes depending on the +respective key type of \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR or \fBML\-DSA\-87\fR. +.IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\fR) " 4 +.IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) " +The encoded private key value of size 2560, 4032 or 4896 bytes depending on the +respective key type of \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR or \fBML\-DSA\-87\fR. +.SS "Provider configuration parameters" +.IX Subsection "Provider configuration parameters" +See the description of the \fB\-provparam\fR option in \fBopenssl\fR\|(1) to learn +how to set provider configuration parameters in the command line tools. +See \fBOSSL_PROVIDER_add_conf_parameter\fR\|(3) to learn how to set provider +configuration options programmatically. +.ie n .IP """ml\-dsa.retain_seed"" (\fBOSSL_PKEY_PARAM_ML_DSA_RETAIN_SEED\fR) " 4 +.el .IP "\f(CWml\-dsa.retain_seed\fR (\fBOSSL_PKEY_PARAM_ML_DSA_RETAIN_SEED\fR) " 4 +.IX Item "ml-dsa.retain_seed (OSSL_PKEY_PARAM_ML_DSA_RETAIN_SEED) " +When set to a string representing a false boolean value (see +\&\fBOSSL_PROVIDER_conf_get_bool\fR\|(3)), the seed will not be retained after key +generation or key import from a seed value. +If the resulting key is then written to a PKCS#8 object, it will contain +only the FIPS 204 \f(CW\*(C`sk\*(C'\fR key. +.ie n .IP """ml\-dsa.prefer_seed"" (\fBOSSL_PKEY_PARAM_ML_DSA_PREFER_SEED\fR) " 4 +.el .IP "\f(CWml\-dsa.prefer_seed\fR (\fBOSSL_PKEY_PARAM_ML_DSA_PREFER_SEED\fR) " 4 +.IX Item "ml-dsa.prefer_seed (OSSL_PKEY_PARAM_ML_DSA_PREFER_SEED) " +When decoding PKCS#8 objects that contain both a seed and the FIPS 204 \f(CW\*(C`sk\*(C'\fR +private key, the seed is by default used to regenerate the key, and the +companion private key is ignored. +When this configuration parameter is set to a string representing a false +boolean value (see \fBOSSL_PROVIDER_conf_get_bool\fR\|(3)), the seed is ignored +(neither used to regenerate the key, nor retained), and the companion key is +used instead. +.ie n .IP """ml\-dsa.input_formats"" (\fBOSSL_PKEY_PARAM_ML_DSA_INPUT_FORMATS\fR) " 4 +.el .IP "\f(CWml\-dsa.input_formats\fR (\fBOSSL_PKEY_PARAM_ML_DSA_INPUT_FORMATS\fR) " 4 +.IX Item "ml-dsa.input_formats (OSSL_PKEY_PARAM_ML_DSA_INPUT_FORMATS) " +List of enabled private key input formats when parsing PKCS#8 objects. +List elements are separated by commas, spaces or tabs. +The list of enabled formats can be specified in the configuration file, as seen +in the "EXAMPLES" section below, or the via the \fB\-provparam\fR command\-line +option (see also \fBOSSL_PROVIDER_add_conf_parameter\fR\|(3)). +.Sp +Values specified on the command\-line override any configuration file settings. +By default all the supported formats are enabled. +The supported formats are: +.RS 4 +.ie n .IP """seed\-priv"":" 4 +.el .IP \f(CWseed\-priv\fR: 4 +.IX Item "seed-priv:" +This format represents \fBPKCS#8\fR objects in which both the FIPS 204 32\-byte +\&\fBξ\fR seed and the secret key \fBsk\fR are present in the private key as part of +the DER encoding of the ASN.1 sequence: +.Sp +.Vb 6 +\& ML\-DSA\-PrivateKey ::= CHOICE { +\& seed [0] IMPLICIT OCTET STRING (SIZE (32)), +\& expandedKey OCTET STRING (SIZE (2560 | 4032 | 4896)), +\& both SEQUENCE { +\& seed OCTET STRING (SIZE (32)), +\& expandedKey OCTET STRING (SIZE (2560 | 4032 | 4896)) } } +.Ve +.Sp +If the \f(CW\*(C`seed\-priv\*(C'\fR format is not included in the list, this format will not be +recognised on input. +.ie n .IP """seed\-only"":" 4 +.el .IP \f(CWseed\-only\fR: 4 +.IX Item "seed-only:" +This format represents \fBPKCS#8\fR objects in which only the 32\-byte FIPS 204 +\&\fBξ\fR seed is present in the above sequence. +If the \f(CW\*(C`seed\-only\*(C'\fR format is not included in the list, this format will not be +recognised on input. +.ie n .IP """priv\-only"":" 4 +.el .IP \f(CWpriv\-only\fR: 4 +.IX Item "priv-only:" +This format represents \fBPKCS#8\fR objects in which only the FIPS 204 +private key \fBsk\fR is present in the above sequence. +If the \f(CW\*(C`priv\-only\*(C'\fR format is not included in the list, this format will not be +recognised on input. +.ie n .IP """oqskeypair"":" 4 +.el .IP \f(CWoqskeypair\fR: 4 +.IX Item "oqskeypair:" +This format represents \fBPKCS#8\fR objects in which the private key is a DER +encoding of an octet string containing the concatenaton of the FIPS 204 private +key \fBsk\fR and the public key \fBpk\fR. +This encoding is used in some builds of the \f(CW\*(C`oqsprovider\*(C'\fR. +If the \f(CW\*(C`oqskeypair\*(C'\fR format is not included in the list, this format will not be +recognised on input. +.ie n .IP """bare\-seed"":" 4 +.el .IP \f(CWbare\-seed\fR: 4 +.IX Item "bare-seed:" +This format represents \fBPKCS#8\fR objects in which the private key contains +the 32\-byte FIPS 204 seed \fBξ\fR without any ASN.1 encapsulation. +If the \f(CW\*(C`bare\-seed\*(C'\fR format is not included in the list, this format will not be +recognised on input. +.ie n .IP """bare\-priv"":" 4 +.el .IP \f(CWbare\-priv\fR: 4 +.IX Item "bare-priv:" +This format represents \fBPKCS#8\fR objects in which the private key contains +the FIPS 204 secret key \fBsk\fR without any ASN.1 encapsulation. +If the \f(CW\*(C`bare\-priv\*(C'\fR format is not included in the list, this format will not be +recognised on input. +.RE +.RS 4 +.RE +.ie n .IP """ml\-dsa.output_formats"" (\fBOSSL_PKEY_PARAM_ML_DSA_OUTPUT_FORMATS\fR) " 4 +.el .IP "\f(CWml\-dsa.output_formats\fR (\fBOSSL_PKEY_PARAM_ML_DSA_OUTPUT_FORMATS\fR) " 4 +.IX Item "ml-dsa.output_formats (OSSL_PKEY_PARAM_ML_DSA_OUTPUT_FORMATS) " +Ordered list of enabled private key output formats when writing \fBPKCS#8\fR files. +List elements are separated by commas, spaces or tabs. +The list of enabled formats can be specified in the configuration file, as seen +in the "EXAMPLES" section below, or the via the \fB\-provparam\fR command\-line +option. +.Sp +This supports the same set of formats as described under \f(CW\*(C`ml\-dsa.input_formats\*(C'\fR +above. +The order in which elements are listed is important, the selected format will be +the first one that is possible to output. +If the key seed is known, the first listed format will be selected. +If the key seed is not known, the first format that omits the seed will be selected. +The default order is equivalent to \f(CW\*(C`seed\-priv\*(C'\fR first and \f(CW\*(C`priv\-only\*(C'\fR second, with +both seed and key output when the seed is available, and just the +key otherwise. +If \f(CW\*(C`seed\-only\*(C'\fR is listed first, then the seed will be output without the key +when available, otherwise the output will have just the key. +If \f(CW\*(C`priv\-only\*(C'\fR is listed first, then just the key is output regardless of +whether the seed is present. +The legacy \f(CW\*(C`oqskeypair\*(C'\fR, \f(CW\*(C`bare\-seed\*(C'\fR and \f(CW\*(C`bare\-priv\*(C'\fR formats can also be +output, by listing those first. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP "FIPS 204" 4 +.IX Item "FIPS 204" +.SH EXAMPLES +.IX Header "EXAMPLES" +An \fBEVP_PKEY\fR context can be obtained by calling: +.PP +.Vb 2 +\& EVP_PKEY_CTX *pctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "ML\-DSA\-44", NULL); +.Ve +.PP +An \fBML\-DSA\-44\fR key can be generated like this: +.PP +.Vb 1 +\& pkey = EVP_PKEY_Q_keygen(NULL, NULL, "ML\-DSA\-44"); +.Ve +.PP +The key pair components can be extracted from a key by calling: +.PP +.Vb 3 +\& /* Sizes large enough for ML\-DSA\-87 */ +\& uint8_t pub[2592], priv[4896], seed[32]: +\& size_t priv_len, pub_len, seed_len; +\& +\& EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_ML_DSA_SEED, +\& seed, sizeof(seed), &seed_len); +\& EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PRIV_KEY, +\& priv, sizeof(priv), &priv_len); +\& EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PUB_KEY, +\& pub, sizeof(pub), &pub_len)); +.Ve +.PP +An \fBML\-DSA\fR private key in seed format can be converted to a key in the FIPS +204 \fBsk\fR format by running: +.PP +.Vb 2 +\& $ openssl pkey \-provparam ml\-dsa.retain_seed=no \e +\& \-in seed\-only.pem \-out priv\-only.pem +.Ve +.PP +To generate an, e.g., \fBML\-DSA\-65\fR key, in FIPS 204 \fBsk\fR format, you can run: +.PP +.Vb 2 +\& $ openssl genpkey \-provparam ml\-dsa.retain_seed=no \e +\& \-algorithm ml\-dsa\-65 \-out priv\-only.pem +.Ve +.PP +If you have a \fBPKCS#8\fR file with both a seed and a key, and prefer to import the +companion key rather than the seed, you can run: +.PP +.Vb 2 +\& $ openssl pkey \-provparam ml\-dsa.prefer_seed=no \e +\& \-in seed\-priv.pem \-out priv\-only.pem +.Ve +.PP +In the \fBopenssl.cnf\fR file, this looks like: +.PP +.Vb 1 +\& openssl_conf = openssl_init +\& +\& [openssl_init] +\& providers = providers_sect +\& +\& # Can be referenced in one or more provider sections +\& [ml_dsa_sect] +\& prefer_seed = yes +\& retain_seed = yes +\& # OQS legacy formats disabled +\& input_formats = seed\-priv, seed\-only, priv\-only +\& # Output either the seed alone, or else the key alone +\& output_formats = seed\-only, priv\-only +\& +\& [providers_sect] +\& default = default_sect +\& # Or perhaps just: base = default_sect +\& base = base_sect +\& +\& [default_sect] +\& ml\-dsa = ml_dsa_sect +\& +\& [base_sect] +\& ml\-dsa = ml_dsa_sect +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KEYMGMT\fR\|(3), +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBEVP_PKEY_get_raw_private_key\fR\|(3), +\&\fBEVP_PKEY_get_raw_public_key\fR\|(3), +\&\fBEVP_PKEY_get1_encoded_public_key\fR\|(3), +\&\fBOSSL_PROVIDER_add_conf_parameter\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBEVP_SIGNATURE\-ML\-DSA\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_PKEY-ML-KEM.7 b/static/netbsd/man7/EVP_PKEY-ML-KEM.7 new file mode 100644 index 00000000..6ded73f0 --- /dev/null +++ b/static/netbsd/man7/EVP_PKEY-ML-KEM.7 @@ -0,0 +1,372 @@ +.\" $NetBSD: EVP_PKEY-ML-KEM.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY-ML-KEM 7" +.TH EVP_PKEY-ML-KEM 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY\-ML\-KEM, +EVP_KEYMGMT\-ML\-KEM, +EVP_PKEY\-ML\-KEM\-512, +EVP_PKEY\-ML\-KEM\-768, +EVP_PKEY\-ML\-KEM\-1024, +EVP_KEYMGMT\-ML\-KEM\-512, +EVP_KEYMGMT\-ML\-KEM\-768, +EVP_KEYMGMT\-ML\-KEM\-1024 +\&\- ML\-KEM keytype and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBML\-KEM\-512\fR, \fBML\-KEM\-768\fR, and \fBML\-KEM\-1024\fR keytypes are implemented +in OpenSSL\*(Aqs default and FIPS providers. +.SS "Keygen Parameters" +.IX Subsection "Keygen Parameters" +No mandatory parameters are required for generating a key pair. +To set explicit parameters, use \fBEVP_PKEY_CTX_set_params()\fR after calling +\&\fBEVP_PKEY_keygen_init()\fR. +.IP """seed"" (\fBOSSL_PKEY_PARAM_ML_KEM_SEED\fR) " 4 +.IX Item """seed"" (OSSL_PKEY_PARAM_ML_KEM_SEED) " +Internally, ML\-KEM generates keys using a 64\-byte random value (seed), which is +the concatenation of the 32\-byte \fId\fR and \fIz\fR parameters described in FIPS 203. +This optional parameter can be used to set a pre\-determined seed prior to +keypair generation. +.Sp +Generated keys default to retaining the seed used. +The seed is also by default retained when keys are loaded from \fBPKCS#8\fR files +in the seed format. +When available, the seed parameter is also used during key export and import, +with keys (by default) regenerated from the seed even when also provided on import. +See "Provider configuration parameters" below for related controls. +.Sp +When the seed is retained, it is also available as a \fBgettable\fR parameter, +and private key output to \fBPKCS#8\fR files will by default include the seed. +When the seed was not initially known, or was not retained, \fBPKCS#8\fR private +key files will contain only the private key in FIPS 203 \f(CW\*(C`dk\*(C'\fR format. +.IP """properties"" (\fBOSSL_PKEY_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_PKEY_PARAM_PROPERTIES) " +Sets properties to be used when fetching algorithm implementations used for +ML\-KEM hashing operations. +.Sp +Use \fBEVP_PKEY_CTX_set_params\fR\|(3) after calling \fBEVP_PKEY_keygen_init\fR\|(3). +.SS "Common parameters" +.IX Subsection "Common parameters" +In addition to the common parameters that all keytypes should support (see +"Common Information Parameters" in \fBprovider\-keymgmt\fR\|(7)), \fBML\-KEM\fR keys +keys support the parameters listed below. +These are gettable using +\&\fBEVP_PKEY_get_octet_string_param\fR\|(3) or \fBEVP_PKEY_get_params\fR\|(3). +They can be initialised via \fBEVP_PKEY_fromdata\fR\|(3), and are returned by +\&\fBEVP_PKEY_todata\fR\|(3) given a suitable \fIselection\fR. +Once a public or private key is configured, it can no longer be modified, +nor can another key component be added. +.IP """pub"" (\fBOSSL_PKEY_PARAM_PUB_KEY\fR) " 4 +.IX Item """pub"" (OSSL_PKEY_PARAM_PUB_KEY) " +The public key value. +.Sp +This parameter is used when importing or exporting the public key value with +the \fBEVP_PKEY_fromdata()\fR and \fBEVP_PKEY_todata()\fR functions. +The key length and content is that of the FIPS 203 (Algorithm 16: +\&\fBML\-KEM.KeyGen_internal\fR) \fBek\fR public key for the given ML\-KEM variant. +Initial import aside, this parameter is otherwise only gettable. +.IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\fR) " 4 +.IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) " +The private key value. +.Sp +This parameter is used when importing or exporting the private key value with +the \fBEVP_PKEY_fromdata()\fR and \fBEVP_PKEY_todata()\fR functions. +The key length and content is that of the FIPS 203 (Algorithm 16: +\&\fBML\-KEM.KeyGen_internal\fR) \fBdk\fR private key for the given ML\-KEM variant. +Initial import aside, this parameter is otherwise only gettable. +.IP """encoded\-pub\-key"" (\fBOSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\fR) " 4 +.IX Item """encoded-pub-key"" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) " +Used for getting and setting the encoding of a public key. +The key format is that of \fBek\fR in FIPS 203, Algorithm 16: +\&\fBML\-KEM.KeyGen_internal\fR. +Updates of the public and private key components are only allowed on keys that +are empty. +Once a public or private key component is set, no further changes are allowed. +This parameter is gettable and settable (once only). +.SS "Provider configuration parameters" +.IX Subsection "Provider configuration parameters" +See the description of the \fB\-provparam\fR option in \fBopenssl\fR\|(1) to learn +how to set provider configuration parameters in the command line tools. +See \fBOSSL_PROVIDER_add_conf_parameter\fR\|(3) to learn how to set provider +configuration options programmatically. +.ie n .IP """ml\-kem.import_pct_type"" (\fBOSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE\fR) " 4 +.el .IP "\f(CWml\-kem.import_pct_type\fR (\fBOSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE\fR) " 4 +.IX Item "ml-kem.import_pct_type (OSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE) " +When an \fBML\-KEM\fR key is imported as an explicit FIPS 203 \fBdk\fR decapsulation +key, rather than a seed, a pairwise consistency test (PCT) is optionally +performed. +By default, or when this parameter is set explicitly to \f(CW\*(C`random\*(C'\fR, the PCT +is performed with a random entropy value for the encapsulation step. +Setting the parameter to \f(CW\*(C`fixed\*(C'\fR, still runs the test, but the encapsulation +entropy is a fixed 32 byte value. +Specifying any other value of the parameter, e.g. \f(CW\*(C`none\*(C'\fR, skips the test. +.ie n .IP """ml\-kem.retain_seed"" (\fBOSSL_PKEY_PARAM_ML_KEM_RETAIN_SEED\fR) " 4 +.el .IP "\f(CWml\-kem.retain_seed\fR (\fBOSSL_PKEY_PARAM_ML_KEM_RETAIN_SEED\fR) " 4 +.IX Item "ml-kem.retain_seed (OSSL_PKEY_PARAM_ML_KEM_RETAIN_SEED) " +When set to a string representing a false boolean value (see +\&\fBOSSL_PROVIDER_conf_get_bool\fR\|(3)), the seed will not be retained after key +generation or key import from a seed value. +If the resulting key is then written to a PKCS#8 object, it will contain +only the FIPS 203 \f(CW\*(C`dk\*(C'\fR key. +.ie n .IP """ml\-kem.prefer_seed"" (\fBOSSL_PKEY_PARAM_ML_KEM_PREFER_SEED\fR) " 4 +.el .IP "\f(CWml\-kem.prefer_seed\fR (\fBOSSL_PKEY_PARAM_ML_KEM_PREFER_SEED\fR) " 4 +.IX Item "ml-kem.prefer_seed (OSSL_PKEY_PARAM_ML_KEM_PREFER_SEED) " +When decoding PKCS#8 objects that contain both a seed and the FIPS 203 \f(CW\*(C`dk\*(C'\fR +private key, the seed is by default used to regenerate the key, and the +companion key is ignored. +When this configuration parameter is set to a string representing a false +boolean value (see \fBOSSL_PROVIDER_conf_get_bool\fR\|(3)), the seed is ignored +(neither used to regenerate the key, nor retained), and the companion key is +used instead. +.ie n .IP """ml\-kem.input_formats"" (\fBOSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS\fR) " 4 +.el .IP "\f(CWml\-kem.input_formats\fR (\fBOSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS\fR) " 4 +.IX Item "ml-kem.input_formats (OSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS) " +List of enabled private key input formats when parsing PKCS#8 objects. +List elements are separated by commas and/or spaces or tabs. +The list of enabled formats can be specified in the configuration file, as seen +in the "EXAMPLES" section below, or the via the \fB\-provparam\fR command\-line +option (see also \fBOSSL_PROVIDER_add_conf_parameter\fR\|(3)). +.Sp +Values specified on the command\-line override any configuration file settings. +By default all the supported formats are enabled. +The supported formats are: +.RS 4 +.ie n .IP """seed\-priv"":" 4 +.el .IP \f(CWseed\-priv\fR: 4 +.IX Item "seed-priv:" +This format represents \fBPKCS#8\fR objects in which both the FIPS 203 64\-byte +\&\fB(d, z)\fR seed and the decapsulation key \fBdk\fR are present in the private key +as part of the DER encoding of the ASN.1 sequence: +.Sp +.Vb 6 +\& ML\-KEM\-PrivateKey ::= CHOICE { +\& seed [0] IMPLICIT OCTET STRING (SIZE (64)), +\& expandedKey OCTET STRING (SIZE (1632 | 2400 | 3168)), +\& both SEQUENCE { +\& seed OCTET STRING (SIZE (64)), +\& expandedKey OCTET STRING (SIZE (1632 | 2400 | 3168)) } } +.Ve +.Sp +If the \f(CW\*(C`seed\-priv\*(C'\fR format is not included in the list, this format will not be +recognised on input. +.ie n .IP """seed\-only"":" 4 +.el .IP \f(CWseed\-only\fR: 4 +.IX Item "seed-only:" +This format represents \fBPKCS#8\fR objects in which only the 64\-byte \fB(d, z)\fR +seed is present in the above sequence. +If the \f(CW\*(C`seed\-only\*(C'\fR format is not included in the list, this format will not be +recognised on input. +.ie n .IP """priv\-only"":" 4 +.el .IP \f(CWpriv\-only\fR: 4 +.IX Item "priv-only:" +This format represents \fBPKCS#8\fR objects in which only the FIPS 203 +decapsulation key \fBdk\fR is present in the above sequence. +If the \f(CW\*(C`priv\-only\*(C'\fR format is not included in the list, this format will not be +recognised on input. +.ie n .IP """oqskeypair"":" 4 +.el .IP \f(CWoqskeypair\fR: 4 +.IX Item "oqskeypair:" +This format represents \fBPKCS#8\fR objects in which the private key is a DER +encoding of an octet string containing the concatenaton of the FIPS 203 +decapsulation key \fBdk\fR and the encapsulation key \fBek\fR. +This encoding is used in some builds of the \f(CW\*(C`oqsprovider\*(C'\fR. +If the \f(CW\*(C`oqskeypair\*(C'\fR format is not included in the list, this format will not be +recognised on input. +.ie n .IP """bare\-seed"":" 4 +.el .IP \f(CWbare\-seed\fR: 4 +.IX Item "bare-seed:" +This format represents \fBPKCS#8\fR objects in which the private key contains +the 64\-byte FIPS 204 seed \fB(d, z)\fR without any ASN.1 encapsulation. +If the \f(CW\*(C`bare\-seed\*(C'\fR format is not included in the list, this format will not be +recognised on input. +.ie n .IP """bare\-priv"":" 4 +.el .IP \f(CWbare\-priv\fR: 4 +.IX Item "bare-priv:" +This format represents \fBPKCS#8\fR objects in which the private key contains +the FIPS 204 decapsulation key \fBdk\fR without any ASN.1 encapsulation. +If the \f(CW\*(C`bare\-priv\*(C'\fR format is not included in the list, this format will not be +recognised on input. +.RE +.RS 4 +.RE +.ie n .IP """ml\-kem.output_formats"" (\fBOSSL_PKEY_PARAM_ML_KEM_OUTPUT_FORMATS\fR) " 4 +.el .IP "\f(CWml\-kem.output_formats\fR (\fBOSSL_PKEY_PARAM_ML_KEM_OUTPUT_FORMATS\fR) " 4 +.IX Item "ml-kem.output_formats (OSSL_PKEY_PARAM_ML_KEM_OUTPUT_FORMATS) " +Ordered list of enabled private key output formats when writing \fBPKCS#8\fR files. +List elements are separated by commas, spaces or tabs. +The list of enabled formats can be specified in the configuration file, as seen +in the "EXAMPLES" section below, or the via the \fB\-provparam\fR command\-line +option. +.Sp +This supports the same set of formats as described under \f(CW\*(C`ml\-kem.input_formats\*(C'\fR +above. +The order in which elements are listed is important, the selected format will be +the first one that is possible to output. +If the key seed is known, the first listed format will be selected. +If the key seed is not known, the first format that omits the seed will be selected. +The default order is equivalent to \f(CW\*(C`seed\-priv\*(C'\fR first and \f(CW\*(C`priv\-only\*(C'\fR second, with +both seed and key output when the seed is available, and just the +key otherwise. +If \f(CW\*(C`seed\-only\*(C'\fR is listed first, then the seed will be output without the key +when available, otherwise the output will have just the key. +If \f(CW\*(C`priv\-only\*(C'\fR is listed first, then just the key is output regardless of +whether the seed is present. +The legacy \f(CW\*(C`oqskeypair\*(C'\fR, \f(CW\*(C`bare\-seed\*(C'\fR and \f(CW\*(C`bare\-priv\*(C'\fR formats can also be +output, by listing those first. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP "FIPS 203" 4 +.IX Item "FIPS 203" +.SH EXAMPLES +.IX Header "EXAMPLES" +An \fBEVP_PKEY\fR context can be obtained by calling: +.PP +.Vb 2 +\& EVP_PKEY_CTX *pctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "ML\-KEM\-768", NULL); +.Ve +.PP +An \fBML\-KEM\-768\fR key can be generated like this: +.PP +.Vb 1 +\& pkey = EVP_PKEY_Q_keygen(NULL, NULL, "ML\-KEM\-768"); +.Ve +.PP +An \fBML\-KEM\fR private key in seed format can be converted to a key in the FIPS +203 \fBdk\fR format by running: +.PP +.Vb 2 +\& $ openssl pkey \-provparam ml\-kem.retain_seed=no \e +\& \-in seed\-only.pem \-out priv\-only.pem +.Ve +.PP +To generate an, e.g., \fBML\-KEM\-768\fR key, in FIPS 203 \fBdk\fR format, you can run: +.PP +.Vb 2 +\& $ openssl genpkey \-provparam ml\-kem.retain_seed=no \e +\& \-algorithm ml\-kem\-768 \-out priv\-only.pem +.Ve +.PP +If you have a \fBPKCS#8\fR file with both a seed and a key, and prefer to import the +companion key rather than the seed, you can run: +.PP +.Vb 2 +\& $ openssl pkey \-provparam ml\-kem.prefer_seed=no \e +\& \-in seed\-priv.pem \-out priv\-only.pem +.Ve +.PP +In the \fBopenssl.cnf\fR file, this looks like: +.PP +.Vb 1 +\& openssl_conf = openssl_init +\& +\& [openssl_init] +\& providers = providers_sect +\& +\& # Can be referenced in one or more provider sections +\& [ml_kem_sect] +\& prefer_seed = yes +\& retain_seed = yes +\& # OQS legacy formats disabled +\& input_formats = seed\-priv, seed\-only, priv\-only +\& # Output either the seed alone, or else the key alone +\& output_formats = seed\-only, priv\-only +\& +\& [providers_sect] +\& default = default_sect +\& # Or perhaps just: base = default_sect +\& base = base_sect +\& +\& [default_sect] +\& ml\-kem = ml_kem_sect +\& +\& [base_sect] +\& ml\-kem = ml_kem_sect +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\fR\|(1), +\&\fBopenssl\-pkey\fR\|(1), +\&\fBopenssl\-genpkey\fR\|(1), +\&\fBEVP_KEYMGMT\fR\|(3), +\&\fBEVP_PKEY\fR\|(3), +\&\fBEVP_PKEY_get_raw_private_key\fR\|(3), +\&\fBEVP_PKEY_get_raw_public_key\fR\|(3), +\&\fBEVP_PKEY_get1_encoded_public_key\fR\|(3), +\&\fBOSSL_PROVIDER_add_conf_parameter\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBEVP_KEM\-ML\-KEM\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_PKEY-RSA.7 b/static/netbsd/man7/EVP_PKEY-RSA.7 new file mode 100644 index 00000000..6a40ced9 --- /dev/null +++ b/static/netbsd/man7/EVP_PKEY-RSA.7 @@ -0,0 +1,319 @@ +.\" $NetBSD: EVP_PKEY-RSA.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY-RSA 7" +.TH EVP_PKEY-RSA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY\-RSA, EVP_KEYMGMT\-RSA, RSA +\&\- EVP_PKEY RSA keytype and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBRSA\fR keytype is implemented in OpenSSL\*(Aqs default and FIPS providers. +That implementation supports the basic RSA keys, containing the modulus \fIn\fR, +the public exponent \fIe\fR, the private exponent \fId\fR, and a collection of prime +factors, exponents and coefficient for CRT calculations, of which the first +few are known as \fIp\fR and \fIq\fR, \fIdP\fR and \fIdQ\fR, and \fIqInv\fR. +.SS "Common RSA parameters" +.IX Subsection "Common RSA parameters" +In addition to the common parameters that all keytypes should support (see +"Common parameters" in \fBprovider\-keymgmt\fR\|(7)), the \fBRSA\fR keytype implementation +supports the following. +.IP """n"" (\fBOSSL_PKEY_PARAM_RSA_N\fR) " 4 +.IX Item """n"" (OSSL_PKEY_PARAM_RSA_N) " +The RSA modulus "n" value. +.IP """e"" (\fBOSSL_PKEY_PARAM_RSA_E\fR) " 4 +.IX Item """e"" (OSSL_PKEY_PARAM_RSA_E) " +The RSA public exponent "e" value. +This value must always be set when creating a raw key using \fBEVP_PKEY_fromdata\fR\|(3). +Note that when a decryption operation is performed, that this value is used for +blinding purposes to prevent timing attacks. +.IP """d"" (\fBOSSL_PKEY_PARAM_RSA_D\fR) " 4 +.IX Item """d"" (OSSL_PKEY_PARAM_RSA_D) " +The RSA private exponent "d" value. +.IP """rsa\-factor1"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR1\fR) " 4 +.IX Item """rsa-factor1"" (OSSL_PKEY_PARAM_RSA_FACTOR1) " +.PD 0 +.IP """rsa\-factor2"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR2\fR) " 4 +.IX Item """rsa-factor2"" (OSSL_PKEY_PARAM_RSA_FACTOR2) " +.IP """rsa\-factor3"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR3\fR) " 4 +.IX Item """rsa-factor3"" (OSSL_PKEY_PARAM_RSA_FACTOR3) " +.IP """rsa\-factor4"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR4\fR) " 4 +.IX Item """rsa-factor4"" (OSSL_PKEY_PARAM_RSA_FACTOR4) " +.IP """rsa\-factor5"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR5\fR) " 4 +.IX Item """rsa-factor5"" (OSSL_PKEY_PARAM_RSA_FACTOR5) " +.IP """rsa\-factor6"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR6\fR) " 4 +.IX Item """rsa-factor6"" (OSSL_PKEY_PARAM_RSA_FACTOR6) " +.IP """rsa\-factor7"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR7\fR) " 4 +.IX Item """rsa-factor7"" (OSSL_PKEY_PARAM_RSA_FACTOR7) " +.IP """rsa\-factor8"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR8\fR) " 4 +.IX Item """rsa-factor8"" (OSSL_PKEY_PARAM_RSA_FACTOR8) " +.IP """rsa\-factor9"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR9\fR) " 4 +.IX Item """rsa-factor9"" (OSSL_PKEY_PARAM_RSA_FACTOR9) " +.IP """rsa\-factor10"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR10\fR) " 4 +.IX Item """rsa-factor10"" (OSSL_PKEY_PARAM_RSA_FACTOR10) " +.PD +RSA prime factors. The factors are known as "p", "q" and "r_i" in RFC8017. +Up to eight additional "r_i" prime factors are supported. +.IP """rsa\-exponent1"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT1\fR) " 4 +.IX Item """rsa-exponent1"" (OSSL_PKEY_PARAM_RSA_EXPONENT1) " +.PD 0 +.IP """rsa\-exponent2"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT2\fR) " 4 +.IX Item """rsa-exponent2"" (OSSL_PKEY_PARAM_RSA_EXPONENT2) " +.IP """rsa\-exponent3"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT3\fR) " 4 +.IX Item """rsa-exponent3"" (OSSL_PKEY_PARAM_RSA_EXPONENT3) " +.IP """rsa\-exponent4"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT4\fR) " 4 +.IX Item """rsa-exponent4"" (OSSL_PKEY_PARAM_RSA_EXPONENT4) " +.IP """rsa\-exponent5"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT5\fR) " 4 +.IX Item """rsa-exponent5"" (OSSL_PKEY_PARAM_RSA_EXPONENT5) " +.IP """rsa\-exponent6"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT6\fR) " 4 +.IX Item """rsa-exponent6"" (OSSL_PKEY_PARAM_RSA_EXPONENT6) " +.IP """rsa\-exponent7"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT7\fR) " 4 +.IX Item """rsa-exponent7"" (OSSL_PKEY_PARAM_RSA_EXPONENT7) " +.IP """rsa\-exponent8"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT8\fR) " 4 +.IX Item """rsa-exponent8"" (OSSL_PKEY_PARAM_RSA_EXPONENT8) " +.IP """rsa\-exponent9"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT9\fR) " 4 +.IX Item """rsa-exponent9"" (OSSL_PKEY_PARAM_RSA_EXPONENT9) " +.IP """rsa\-exponent10"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT10\fR) " 4 +.IX Item """rsa-exponent10"" (OSSL_PKEY_PARAM_RSA_EXPONENT10) " +.PD +RSA CRT (Chinese Remainder Theorem) exponents. The exponents are known +as "dP", "dQ" and "d_i" in RFC8017. +Up to eight additional "d_i" exponents are supported. +.IP """rsa\-coefficient1"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT1\fR) " 4 +.IX Item """rsa-coefficient1"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT1) " +.PD 0 +.IP """rsa\-coefficient2"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT2\fR) " 4 +.IX Item """rsa-coefficient2"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT2) " +.IP """rsa\-coefficient3"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT3\fR) " 4 +.IX Item """rsa-coefficient3"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT3) " +.IP """rsa\-coefficient4"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT4\fR) " 4 +.IX Item """rsa-coefficient4"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT4) " +.IP """rsa\-coefficient5"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT5\fR) " 4 +.IX Item """rsa-coefficient5"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT5) " +.IP """rsa\-coefficient6"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT6\fR) " 4 +.IX Item """rsa-coefficient6"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT6) " +.IP """rsa\-coefficient7"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT7\fR) " 4 +.IX Item """rsa-coefficient7"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT7) " +.IP """rsa\-coefficient8"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT8\fR) " 4 +.IX Item """rsa-coefficient8"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT8) " +.IP """rsa\-coefficient9"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT9\fR) " 4 +.IX Item """rsa-coefficient9"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT9) " +.PD +RSA CRT (Chinese Remainder Theorem) coefficients. The coefficients are known as +"qInv" and "t_i". +Up to eight additional "t_i" exponents are supported. +.SS "RSA key generation parameters" +.IX Subsection "RSA key generation parameters" +When generating RSA keys, the following key generation parameters may be used. +.IP """bits"" (\fBOSSL_PKEY_PARAM_RSA_BITS\fR) " 4 +.IX Item """bits"" (OSSL_PKEY_PARAM_RSA_BITS) " +The value should be the cryptographic length for the \fBRSA\fR cryptosystem, in +bits. +.IP """primes"" (\fBOSSL_PKEY_PARAM_RSA_PRIMES\fR) " 4 +.IX Item """primes"" (OSSL_PKEY_PARAM_RSA_PRIMES) " +The value should be the number of primes for the generated \fBRSA\fR key. The +default is 2. It isn\*(Aqt permitted to specify a larger number of primes than +10. Additionally, the number of primes is limited by the length of the key +being generated so the maximum number could be less. +Some providers may only support a value of 2. +.IP """e"" (\fBOSSL_PKEY_PARAM_RSA_E\fR) " 4 +.IX Item """e"" (OSSL_PKEY_PARAM_RSA_E) " +The RSA "e" value. The value may be any odd number greater than or equal to +65537. The default value is 65537. +For legacy reasons a value of 3 is currently accepted but is deprecated. +.IP """rsa\-derive\-from\-pq"" (\fBOSSL_PKEY_PARAM_RSA_DERIVE_FROM_PQ\fR) " 4 +.IX Item """rsa-derive-from-pq"" (OSSL_PKEY_PARAM_RSA_DERIVE_FROM_PQ) " +Indicate that missing parameters not passed in the parameter list should be +derived if not provided. Setting a nonzero value will cause all +needed exponents and coefficients to be derived if not available. Setting this +option requires at least OSSL_PARAM_RSA_FACTOR1, OSSL_PARAM_RSA_FACTOR2, +and OSSL_PARAM_RSA_N to be provided. This option is ignored if +OSSL_KEYMGMT_SELECT_PRIVATE_KEY is not set in the selection parameter. +.SS "RSA key generation parameters for FIPS module testing" +.IX Subsection "RSA key generation parameters for FIPS module testing" +When generating RSA keys, the following additional key generation parameters may +be used for algorithm testing purposes only. Do not use these to generate +RSA keys for a production environment. +.IP """xp"" (\fBOSSL_PKEY_PARAM_RSA_TEST_XP\fR) " 4 +.IX Item """xp"" (OSSL_PKEY_PARAM_RSA_TEST_XP) " +.PD 0 +.IP """xq"" (\fBOSSL_PKEY_PARAM_RSA_TEST_XQ\fR) " 4 +.IX Item """xq"" (OSSL_PKEY_PARAM_RSA_TEST_XQ) " +.PD +These 2 fields are normally randomly generated and are used to generate "p" and +"q". +.IP """xp1"" (\fBOSSL_PKEY_PARAM_RSA_TEST_XP1\fR) " 4 +.IX Item """xp1"" (OSSL_PKEY_PARAM_RSA_TEST_XP1) " +.PD 0 +.IP """xp2"" (\fBOSSL_PKEY_PARAM_RSA_TEST_XP2\fR) " 4 +.IX Item """xp2"" (OSSL_PKEY_PARAM_RSA_TEST_XP2) " +.IP """xq1"" (\fBOSSL_PKEY_PARAM_RSA_TEST_XQ1\fR) " 4 +.IX Item """xq1"" (OSSL_PKEY_PARAM_RSA_TEST_XQ1) " +.IP """xq2"" (\fBOSSL_PKEY_PARAM_RSA_TEST_XQ2\fR) " 4 +.IX Item """xq2"" (OSSL_PKEY_PARAM_RSA_TEST_XQ2) " +.PD +These 4 fields are normally randomly generated. The prime factors "p1", "p2", +"q1" and "q2" are determined from these values. +.SS "RSA key parameters for FIPS module testing" +.IX Subsection "RSA key parameters for FIPS module testing" +The following intermediate values can be retrieved only if the values +specified in "RSA key generation parameters for FIPS module testing" are set. +These should not be accessed in a production environment. +.IP """p1"" (\fBOSSL_PKEY_PARAM_RSA_TEST_P1\fR) " 4 +.IX Item """p1"" (OSSL_PKEY_PARAM_RSA_TEST_P1) " +.PD 0 +.IP """p2"" (\fBOSSL_PKEY_PARAM_RSA_TEST_P2\fR) " 4 +.IX Item """p2"" (OSSL_PKEY_PARAM_RSA_TEST_P2) " +.IP """q1"" (\fBOSSL_PKEY_PARAM_RSA_TEST_Q1\fR) " 4 +.IX Item """q1"" (OSSL_PKEY_PARAM_RSA_TEST_Q1) " +.IP """q2"" (\fBOSSL_PKEY_PARAM_RSA_TEST_Q2\fR) " 4 +.IX Item """q2"" (OSSL_PKEY_PARAM_RSA_TEST_Q2) " +.PD +The auxiliary probable primes. +.SS "RSA key validation" +.IX Subsection "RSA key validation" +For RSA keys, \fBEVP_PKEY_param_check\fR\|(3) and \fBEVP_PKEY_param_check_quick\fR\|(3) +both return 1 unconditionally. +.PP +For RSA keys, \fBEVP_PKEY_public_check\fR\|(3) conforms to the SP800\-56Br1 \fIpublic key +check\fR when the OpenSSL FIPS provider is used. The OpenSSL default provider +performs similar tests but relaxes the keysize restrictions for backwards +compatibility. +.PP +For RSA keys, \fBEVP_PKEY_public_check_quick\fR\|(3) is the same as +\&\fBEVP_PKEY_public_check\fR\|(3). +.PP +For RSA keys, \fBEVP_PKEY_private_check\fR\|(3) conforms to the SP800\-56Br1 +\&\fIprivate key test\fR. +.PP +For RSA keys, \fBEVP_PKEY_pairwise_check\fR\|(3) conforms to the +SP800\-56Br1 \fIKeyPair Validation check\fR for the OpenSSL FIPS provider. The +OpenSSL default provider allows testing of the validity of multi\-primes. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP FIPS186\-4 4 +.IX Item "FIPS186-4" +Section B.3.6 Generation of Probable Primes with Conditions Based on +Auxiliary Probable Primes +.IP "RFC 8017, excluding RSA\-PSS and RSA\-OAEP" 4 +.IX Item "RFC 8017, excluding RSA-PSS and RSA-OAEP" +.SH EXAMPLES +.IX Header "EXAMPLES" +An \fBEVP_PKEY\fR context can be obtained by calling: +.PP +.Vb 2 +\& EVP_PKEY_CTX *pctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL); +.Ve +.PP +An \fBRSA\fR key can be generated simply like this: +.PP +.Vb 1 +\& pkey = EVP_RSA_gen(4096); +.Ve +.PP +or like this: +.PP +.Vb 3 +\& EVP_PKEY *pkey = NULL; +\& EVP_PKEY_CTX *pctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL); +\& +\& EVP_PKEY_keygen_init(pctx); +\& EVP_PKEY_generate(pctx, &pkey); +\& EVP_PKEY_CTX_free(pctx); +.Ve +.PP +An \fBRSA\fR key can be generated with key generation parameters: +.PP +.Vb 5 +\& unsigned int primes = 3; +\& unsigned int bits = 4096; +\& OSSL_PARAM params[3]; +\& EVP_PKEY *pkey = NULL; +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL); +\& +\& EVP_PKEY_keygen_init(pctx); +\& +\& params[0] = OSSL_PARAM_construct_uint("bits", &bits); +\& params[1] = OSSL_PARAM_construct_uint("primes", &primes); +\& params[2] = OSSL_PARAM_construct_end(); +\& EVP_PKEY_CTX_set_params(pctx, params); +\& +\& EVP_PKEY_generate(pctx, &pkey); +\& EVP_PKEY_print_private(bio_out, pkey, 0, NULL); +\& EVP_PKEY_CTX_free(pctx); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_RSA_gen\fR\|(3), \fBEVP_KEYMGMT\fR\|(3), \fBEVP_PKEY\fR\|(3), \fBprovider\-keymgmt\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_PKEY-SLH-DSA.7 b/static/netbsd/man7/EVP_PKEY-SLH-DSA.7 new file mode 100644 index 00000000..a1978dbc --- /dev/null +++ b/static/netbsd/man7/EVP_PKEY-SLH-DSA.7 @@ -0,0 +1,201 @@ +.\" $NetBSD: EVP_PKEY-SLH-DSA.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY-SLH-DSA 7" +.TH EVP_PKEY-SLH-DSA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY\-SLH\-DSA, EVP_KEYMGMT\-SLH\-DSA, +EVP_PKEY\-SLH\-DSA\-SHA2\-128s, EVP_PKEY\-SLH\-DSA\-SHA2\-128f, +EVP_PKEY\-SLH\-DSA\-SHA2\-192s, EVP_PKEY\-SLH\-DSA\-SHA2\-192f, +EVP_PKEY\-SLH\-DSA\-SHA2\-256s, EVP_PKEY\-SLH\-DSA\-SHA2\-256f, +EVP_PKEY\-SLH\-DSA\-SHAKE\-128s, EVP_PKEY\-SLH\-DSA\-SHAKE\-128f, +EVP_PKEY\-SLH\-DSA\-SHAKE\-192s, EVP_PKEY\-SLH\-DSA\-SHAKE\-192f, +EVP_PKEY\-SLH\-DSA\-SHAKE\-256s, EVP_PKEY\-SLH\-DSA\-SHAKE\-256f +\&\- EVP_PKEY SLH\-DSA keytype and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBSLH\-DSA\-SHA2\-128s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHA2\-128f\fR, +\&\fBSLH\-DSA\-SHA2\-192s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHA2\-192f\fR, +\&\fBSLH\-DSA\-SHA2\-256s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHA2\-256f\fR, +\&\fBSLH\-DSA\-SHAKE\-128s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHAKE\-128f\fR, +\&\fBSLH\-DSA\-SHAKE\-192s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHAKE\-192f\fR, +\&\fBSLH\-DSA\-SHAKE\-256s\fR and \fBEVP_PKEY\-SLH\-DSA\-SHAKE\-256f\fR key types are +implemented in OpenSSL\*(Aqs default and FIPS providers. These implementations +support the associated key, containing the public key \fIpub\fR and the +private key \fIpriv\fR. +.PP +SLH\-DSA (Stateless Hash\-based Digital Signature Standard) uses small keys, +but has relatively large signatures and is relatively slow performing all +operations compared to \fBML\-DSA\fR. It does however have proven security proofs, +since it relies only on hash functions. +.PP +Each of the different key types has an associated security parameter \fBn\fR. +This value is one of 16, 24 or 32 for key types \fBSLH\-DSA*128*\fR, \fBSLH\-DSA*192*\fR +and \fBSLH\-DSA*256*\fR, respectively. +.PP +Both the public and private key components contain 2 elements of size \fBn\fR. +Key generation generates the private key elements and one of the public key +elements randomly, and the final public key element is computed from these values. +.PP +The public key has relatively small sizes of 32, 48 or 64 bytes, +corresponding to the algorithm names of 128, 192 and 256 respectively. +.PP +The algorithms ending with \fBs\fR produce smaller signatures, but are much slower +than the faster \fBf\fR variants. +.PP +The signature sizes for the \fBs\fR algorithm variants are 7856, 16224 and 29792 +which correspond to the algorithm names of 128s, 192s and 256s respectively. +The signature sizes for the \fBf\fR algorithm variants are 17088, 35664 and 49856 +which correspond to the algorithm names containing 128f, 192f and 256f respectively. +.PP +Internally there are 7 hash related functions that are used for each algorithm. +For algorithms containing \fBSHAKE\fR in their name \fBSHAKE\-256\fR is used for all +functions. +For the algorithms the functions use , +and . +The remaining algorithms use , , and +. +See FIPS 205 Section 11.1 and 11.2 for more information. +.SS "Keygen Parameters" +.IX Subsection "Keygen Parameters" +.IP """seed"" (\fBOSSL_PKEY_PARAM_SLH_DSA_SEED\fR) " 4 +.IX Item """seed"" (OSSL_PKEY_PARAM_SLH_DSA_SEED) " +Supplies values to use for the private seed, private prf and +public seed instead of generating random values. This is used for testing +purposes only. The length of the value supplied must be 3 * \fBn\fR. +.IP """properties"" (\fBOSSL_PKEY_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_PKEY_PARAM_PROPERTIES) " +Sets properties to be used when fetching algorithm implementations used for +SLH\-DSA hashing operations. +.PP +Use \fBEVP_PKEY_CTX_set_params()\fR after calling \fBEVP_PKEY_keygen_init()\fR. +.SS "Common SLH\-DSA parameters" +.IX Subsection "Common SLH-DSA parameters" +In addition to the common parameters that all keytypes should support (see +"Common Information Parameters" in \fBprovider\-keymgmt\fR\|(7)), the implementation of +these key types support the following. +.PP +The following parameters are gettable using \fBEVP_PKEY_get_octet_string_param()\fR, +and settable when using \fBEVP_PKEY_fromdata()\fR. +.IP """pub"" (\fBOSSL_PKEY_PARAM_PUB_KEY\fR) " 4 +.IX Item """pub"" (OSSL_PKEY_PARAM_PUB_KEY) " +The public key has a size of 2 * \fBn\fR bytes. +i.e. It consists of the concatenation of PK.seed and PK.root +as defined by FIPS 205 Figure 16. +.IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\fR) " 4 +.IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) " +The private key has a size of 4 * \fBn\fR bytes, which includes the public key components. +i.e. It consists of the concatenation of SK.seed, SK.prf, PK.seed and PF.root +as defined by FIPS 205 Figure 15. +.IP """mandatory\-digest"" (\fBOSSL_PKEY_PARAM_MANDATORY_DIGEST\fR) " 4 +.IX Item """mandatory-digest"" (OSSL_PKEY_PARAM_MANDATORY_DIGEST) " +The empty string, signifying that no digest may be specified. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP "FIPS 205" 4 +.IX Item "FIPS 205" +.SH EXAMPLES +.IX Header "EXAMPLES" +An \fBEVP_PKEY\fR context can be obtained by calling: +.PP +.Vb 2 +\& EVP_PKEY_CTX *pctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "SLH\-DSA\-SHA2\-128f", NULL); +.Ve +.PP +An \fBSLH\-DSA\fR key can be generated like this: +.PP +.Vb 1 +\& pkey = EVP_PKEY_Q_keygen(NULL, NULL, "SLH\-DSA\-SHA2\-128f"); +.Ve +.PP +The key pair components can be extracted from a key by calling: +.PP +.Vb 2 +\& uint8_t priv[64], pub[32]; +\& size_t priv_len, pub_len; +\& +\& EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PRIV_KEY, +\& priv, sizeof(priv), &priv_len); +\& EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PUB_KEY, +\& pub, sizeof(pub), &pub_len)); +.Ve +.PP +Similar code can be used for the other key types such as "SLH\-DSA\-SHAKE\-256f". +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KEYMGMT\fR\|(3), \fBEVP_PKEY\fR\|(3), \fBprovider\-keymgmt\fR\|(7), +\&\fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_PKEY-SM2.7 b/static/netbsd/man7/EVP_PKEY-SM2.7 new file mode 100644 index 00000000..e18a1add --- /dev/null +++ b/static/netbsd/man7/EVP_PKEY-SM2.7 @@ -0,0 +1,153 @@ +.\" $NetBSD: EVP_PKEY-SM2.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY-SM2 7" +.TH EVP_PKEY-SM2 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY\-SM2, EVP_KEYMGMT\-SM2, SM2 +\&\- EVP_PKEY keytype support for the Chinese SM2 signature and encryption algorithms +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBSM2\fR algorithm was first defined by the Chinese national standard GM/T +0003\-2012 and was later standardized by ISO as ISO/IEC 14888. \fBSM2\fR is actually +an elliptic curve based algorithm. The current implementation in OpenSSL supports +both signature and encryption schemes via the EVP interface. +.PP +When doing the \fBSM2\fR signature algorithm, it requires a distinguishing identifier +to form the message prefix which is hashed before the real message is hashed. +.SS "Common SM2 parameters" +.IX Subsection "Common SM2 parameters" +SM2 uses the parameters defined in "Common EC parameters" in \fBEVP_PKEY\-EC\fR\|(7). +The following parameters are different: +.IP """cofactor"" (\fBOSSL_PKEY_PARAM_EC_COFACTOR\fR) " 4 +.IX Item """cofactor"" (OSSL_PKEY_PARAM_EC_COFACTOR) " +This parameter is ignored for \fBSM2\fR. +.IP "(\fBOSSL_PKEY_PARAM_DEFAULT_DIGEST\fR) " 4 +.IX Item "(OSSL_PKEY_PARAM_DEFAULT_DIGEST) " +Getter that returns the default digest name. +(Currently returns "SM3" as of OpenSSL 3.0). +.SH NOTES +.IX Header "NOTES" +\&\fBSM2\fR signatures can be generated by using the \*(AqDigestSign\*(Aq series of APIs, for +instance, \fBEVP_DigestSignInit()\fR, \fBEVP_DigestSignUpdate()\fR and \fBEVP_DigestSignFinal()\fR. +Ditto for the verification process by calling the \*(AqDigestVerify\*(Aq series of APIs. +Note that the SM2 algorithm requires the presence of the public key for signatures, +as such the \fBOSSL_PKEY_PARAM_PUB_KEY\fR option must be set on any key used in signature +generation. +.PP +Before computing an \fBSM2\fR signature, an \fBEVP_PKEY_CTX\fR needs to be created, +and an \fBSM2\fR ID must be set for it, like this: +.PP +.Vb 1 +\& EVP_PKEY_CTX_set1_id(pctx, id, id_len); +.Ve +.PP +Before calling the \fBEVP_DigestSignInit()\fR or \fBEVP_DigestVerifyInit()\fR functions, +that \fBEVP_PKEY_CTX\fR should be assigned to the \fBEVP_MD_CTX\fR, like this: +.PP +.Vb 1 +\& EVP_MD_CTX_set_pkey_ctx(mctx, pctx); +.Ve +.PP +There is normally no need to pass a \fBpctx\fR parameter to \fBEVP_DigestSignInit()\fR +or \fBEVP_DigestVerifyInit()\fR in such a scenario. +.PP +SM2 can be tested with the \fBopenssl\-speed\fR\|(1) application since version 3.0. +Currently, the only valid algorithm name is \fBsm2\fR. +.PP +Since version 3.0, SM2 keys can be generated and loaded only when the domain +parameters specify the SM2 elliptic curve. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example demonstrates the calling sequence for using an \fBEVP_PKEY\fR to verify +a message with the SM2 signature algorithm and the SM3 hash algorithm: +.PP +.Vb 1 +\& #include +\& +\& /* obtain an EVP_PKEY using whatever methods... */ +\& mctx = EVP_MD_CTX_new(); +\& pctx = EVP_PKEY_CTX_new(pkey, NULL); +\& EVP_PKEY_CTX_set1_id(pctx, id, id_len); +\& EVP_MD_CTX_set_pkey_ctx(mctx, pctx); +\& EVP_DigestVerifyInit(mctx, NULL, EVP_sm3(), NULL, pkey); +\& EVP_DigestVerifyUpdate(mctx, msg, msg_len); +\& EVP_DigestVerifyFinal(mctx, sig, sig_len) +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_DigestSignInit\fR\|(3), +\&\fBEVP_DigestVerifyInit\fR\|(3), +\&\fBEVP_PKEY_CTX_set1_id\fR\|(3), +\&\fBEVP_MD_CTX_set_pkey_ctx\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_PKEY-X25519.7 b/static/netbsd/man7/EVP_PKEY-X25519.7 new file mode 100644 index 00000000..7d683898 --- /dev/null +++ b/static/netbsd/man7/EVP_PKEY-X25519.7 @@ -0,0 +1,166 @@ +.\" $NetBSD: EVP_PKEY-X25519.7,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY-X25519 7" +.TH EVP_PKEY-X25519 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY\-X25519, EVP_PKEY\-X448, EVP_PKEY\-ED25519, EVP_PKEY\-ED448, +EVP_KEYMGMT\-X25519, EVP_KEYMGMT\-X448, EVP_KEYMGMT\-ED25519, EVP_KEYMGMT\-ED448 +\&\- EVP_PKEY X25519, X448, ED25519 and ED448 keytype and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBX25519\fR, \fBX448\fR, \fBED25519\fR and \fBED448\fR keytypes are +implemented in OpenSSL\*(Aqs default and FIPS providers. These implementations +support the associated key, containing the public key \fIpub\fR and the +private key \fIpriv\fR. +.SS "Keygen Parameters" +.IX Subsection "Keygen Parameters" +.IP """dhkem\-ikm"" (\fBOSSL_PKEY_PARAM_DHKEM_IKM\fR) " 4 +.IX Item """dhkem-ikm"" (OSSL_PKEY_PARAM_DHKEM_IKM) " +DHKEM requires the generation of a keypair using an input key material (seed). +Use this to specify the key material used for generation of the private key. +This value should not be reused for other purposes. +It should have a length of at least 32 for X25519, and 56 for X448. +This is only supported by X25519 and X448. +.IP """fips\-indicator"" (\fBOSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR) " +This getter is only supported by X25519 and X448 for the FIPS provider. +Since X25519 and X448 are unapproved in FIPS 140\-3 this getter return 0. +.Sp +See "Common Information Parameters" in \fBprovider\-keymgmt\fR\|(7) for further information. +.PP +Use \fBEVP_PKEY_CTX_set_params()\fR after calling \fBEVP_PKEY_keygen_init()\fR. +.SS "Common X25519, X448, ED25519 and ED448 parameters" +.IX Subsection "Common X25519, X448, ED25519 and ED448 parameters" +In addition to the common parameters that all keytypes should support (see +"Common parameters" in \fBprovider\-keymgmt\fR\|(7)), the implementation of these keytypes +support the following. +.IP """group"" (\fBOSSL_PKEY_PARAM_GROUP_NAME\fR) " 4 +.IX Item """group"" (OSSL_PKEY_PARAM_GROUP_NAME) " +This is only supported by X25519 and X448. The group name must be "x25519" or +"x448" respectively for those algorithms. This is only present for consistency +with other key exchange algorithms and is typically not needed. +.IP """pub"" (\fBOSSL_PKEY_PARAM_PUB_KEY\fR) " 4 +.IX Item """pub"" (OSSL_PKEY_PARAM_PUB_KEY) " +The public key value. +.IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\fR) " 4 +.IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) " +The private key value. +.IP """encoded\-pub\-key"" (\fBOSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\fR) " 4 +.IX Item """encoded-pub-key"" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) " +Used for getting and setting the encoding of a public key for the \fBX25519\fR and +\&\fBX448\fR key types. Public keys are expected be encoded in a format as defined by +RFC7748. +.SS "ED25519 and ED448 parameters" +.IX Subsection "ED25519 and ED448 parameters" +.IP """mandatory\-digest"" (\fBOSSL_PKEY_PARAM_MANDATORY_DIGEST\fR) " 4 +.IX Item """mandatory-digest"" (OSSL_PKEY_PARAM_MANDATORY_DIGEST) " +The empty string, signifying that no digest may be specified. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP "RFC 8032" 4 +.IX Item "RFC 8032" +.PD 0 +.IP "RFC 8410" 4 +.IX Item "RFC 8410" +.PD +.SH EXAMPLES +.IX Header "EXAMPLES" +An \fBEVP_PKEY\fR context can be obtained by calling: +.PP +.Vb 2 +\& EVP_PKEY_CTX *pctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "X25519", NULL); +\& +\& EVP_PKEY_CTX *pctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "X448", NULL); +\& +\& EVP_PKEY_CTX *pctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "ED25519", NULL); +\& +\& EVP_PKEY_CTX *pctx = +\& EVP_PKEY_CTX_new_from_name(NULL, "ED448", NULL); +.Ve +.PP +An \fBX25519\fR key can be generated like this: +.PP +.Vb 1 +\& pkey = EVP_PKEY_Q_keygen(NULL, NULL, "X25519"); +.Ve +.PP +An \fBX448\fR, \fBED25519\fR, or \fBED448\fR key can be generated likewise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KEYMGMT\fR\|(3), \fBEVP_PKEY\fR\|(3), \fBprovider\-keymgmt\fR\|(7), +\&\fBEVP_KEYEXCH\-X25519\fR\|(7), \fBEVP_KEYEXCH\-X448\fR\|(7), +\&\fBEVP_SIGNATURE\-ED25519\fR\|(7), \fBEVP_SIGNATURE\-ED448\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_RAND-CRNG-TEST.7 b/static/netbsd/man7/EVP_RAND-CRNG-TEST.7 new file mode 100644 index 00000000..2c504be5 --- /dev/null +++ b/static/netbsd/man7/EVP_RAND-CRNG-TEST.7 @@ -0,0 +1,125 @@ +.\" $NetBSD: EVP_RAND-CRNG-TEST.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_RAND-CRNG-TEST 7" +.TH EVP_RAND-CRNG-TEST 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_RAND\-CRNG\-TEST \- The FIPS health testing EVP_RAND filter +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This \fBEVP_RAND\fR object acts as a filter between the entropy source +and its users. It performs CRNG health tests as defined in +SP 800\-90B Section 4 "Health +Tests". Most requests are forwarded to the entropy source, either via +its parent reference or via the provider entropy upcalls. +.SS Identity +.IX Subsection "Identity" +"CRNG\-TEST" is the name for this implementation; it can be used with the +\&\fBEVP_RAND_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +If a parent EVP_RAND is specified on context creation, the parent\*(Aqs +parameters are supported because the request is forwarded to the parent +seed source for processing. +.PP +If no parent EVP_RAND is specified on context creation, the following parameters +are supported: +.IP """state"" (\fBOSSL_RAND_PARAM_STATE\fR) " 4 +.IX Item """state"" (OSSL_RAND_PARAM_STATE) " +.PD 0 +.IP """strength"" (\fBOSSL_RAND_PARAM_STRENGTH\fR) " 4 +.IX Item """strength"" (OSSL_RAND_PARAM_STRENGTH) " +.IP """max_request"" (\fBOSSL_RAND_PARAM_MAX_REQUEST\fR) " 4 +.IX Item """max_request"" (OSSL_RAND_PARAM_MAX_REQUEST) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_RAND\fR\|(3). +.IP """fips\-indicator"" (\fBOSSL_DRBG_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_DRBG_PARAM_FIPS_APPROVED_INDICATOR) " +This parameter works as described in "PARAMETERS" in \fBprovider\-rand\fR\|(7). +.SH NOTES +.IX Header "NOTES" +This EVP_RAND is only implemented by the OpenSSL FIPS provider. +.PP +A context for a health test filter can be obtained by calling: +.PP +.Vb 3 +\& EVP_RAND *parent = ...; +\& EVP_RAND *rand = EVP_RAND_fetch(NULL, "CRNG\-TEST", NULL); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, parent); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_RAND\fR\|(3), \fBOSSL_PROVIDER\-FIPS\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_RAND-CTR-DRBG.7 b/static/netbsd/man7/EVP_RAND-CTR-DRBG.7 new file mode 100644 index 00000000..1629df87 --- /dev/null +++ b/static/netbsd/man7/EVP_RAND-CTR-DRBG.7 @@ -0,0 +1,167 @@ +.\" $NetBSD: EVP_RAND-CTR-DRBG.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_RAND-CTR-DRBG 7" +.TH EVP_RAND-CTR-DRBG 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_RAND\-CTR\-DRBG \- The CTR DRBG EVP_RAND implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for the counter deterministic random bit generator through the +\&\fBEVP_RAND\fR API. +.SS Identity +.IX Subsection "Identity" +"CTR\-DRBG" is the name for this implementation; it can be used with the +\&\fBEVP_RAND_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """state"" (\fBOSSL_RAND_PARAM_STATE\fR) " 4 +.IX Item """state"" (OSSL_RAND_PARAM_STATE) " +.PD 0 +.IP """strength"" (\fBOSSL_RAND_PARAM_STRENGTH\fR) " 4 +.IX Item """strength"" (OSSL_RAND_PARAM_STRENGTH) " +.IP """max_request"" (\fBOSSL_RAND_PARAM_MAX_REQUEST\fR) " 4 +.IX Item """max_request"" (OSSL_RAND_PARAM_MAX_REQUEST) " +.IP """reseed_requests"" (\fBOSSL_DRBG_PARAM_RESEED_REQUESTS\fR) " 4 +.IX Item """reseed_requests"" (OSSL_DRBG_PARAM_RESEED_REQUESTS) " +.IP """reseed_time_interval"" (\fBOSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\fR) " 4 +.IX Item """reseed_time_interval"" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) " +.IP """min_entropylen"" (\fBOSSL_DRBG_PARAM_MIN_ENTROPYLEN\fR) " 4 +.IX Item """min_entropylen"" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) " +.IP """max_entropylen"" (\fBOSSL_DRBG_PARAM_MAX_ENTROPYLEN\fR) " 4 +.IX Item """max_entropylen"" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) " +.IP """min_noncelen"" (\fBOSSL_DRBG_PARAM_MIN_NONCELEN\fR) " 4 +.IX Item """min_noncelen"" (OSSL_DRBG_PARAM_MIN_NONCELEN) " +.IP """max_noncelen"" (\fBOSSL_DRBG_PARAM_MAX_NONCELEN\fR) " 4 +.IX Item """max_noncelen"" (OSSL_DRBG_PARAM_MAX_NONCELEN) " +.IP """max_perslen"" (\fBOSSL_DRBG_PARAM_MAX_PERSLEN\fR) " 4 +.IX Item """max_perslen"" (OSSL_DRBG_PARAM_MAX_PERSLEN) " +.IP """max_adinlen"" (\fBOSSL_DRBG_PARAM_MAX_ADINLEN\fR) " 4 +.IX Item """max_adinlen"" (OSSL_DRBG_PARAM_MAX_ADINLEN) " +.IP """reseed_counter"" (\fBOSSL_DRBG_PARAM_RESEED_COUNTER\fR) " 4 +.IX Item """reseed_counter"" (OSSL_DRBG_PARAM_RESEED_COUNTER) " +.IP """properties"" (\fBOSSL_DRBG_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_DRBG_PARAM_PROPERTIES) " +.IP """cipher"" (\fBOSSL_DRBG_PARAM_CIPHER\fR) " 4 +.IX Item """cipher"" (OSSL_DRBG_PARAM_CIPHER) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_RAND\fR\|(3). +.IP """use_derivation_function"" (\fBOSSL_DRBG_PARAM_USE_DF\fR) " 4 +.IX Item """use_derivation_function"" (OSSL_DRBG_PARAM_USE_DF) " +This Boolean indicates if a derivation function should be used or not. +A nonzero value (the default) uses the derivation function. A zero value +does not. +.SH NOTES +.IX Header "NOTES" +A context for CTR DRBG can be obtained by calling: +.PP +.Vb 2 +\& EVP_RAND *rand = EVP_RAND_fetch(NULL, "CTR\-DRBG", NULL); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL); +.Ve +.PP +The default CTR\-DRBG implementation attempts to fetch the required internal +algorithms from the provider they are built into (eg the default provider) +regardless of the properties provided. Should the provider not implement +the required algorithms then properties will be used to find a different +implementation. +.SH EXAMPLES +.IX Header "EXAMPLES" +.Vb 5 +\& EVP_RAND *rand; +\& EVP_RAND_CTX *rctx; +\& unsigned char bytes[100]; +\& OSSL_PARAM params[2], *p = params; +\& unsigned int strength = 128; +\& +\& rand = EVP_RAND_fetch(NULL, "CTR\-DRBG", NULL); +\& rctx = EVP_RAND_CTX_new(rand, NULL); +\& EVP_RAND_free(rand); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER, +\& SN_aes_256_ctr, 0); +\& *p = OSSL_PARAM_construct_end(); +\& EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params); +\& +\& EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0); +\& +\& EVP_RAND_CTX_free(rctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +NIST SP 800\-90A and SP 800\-90B +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_RAND\fR\|(3), +"PARAMETERS" in \fBEVP_RAND\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_RAND-HASH-DRBG.7 b/static/netbsd/man7/EVP_RAND-HASH-DRBG.7 new file mode 100644 index 00000000..f43bee0d --- /dev/null +++ b/static/netbsd/man7/EVP_RAND-HASH-DRBG.7 @@ -0,0 +1,191 @@ +.\" $NetBSD: EVP_RAND-HASH-DRBG.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_RAND-HASH-DRBG 7" +.TH EVP_RAND-HASH-DRBG 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_RAND\-HASH\-DRBG \- The HASH DRBG EVP_RAND implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for the hash deterministic random bit generator through the +\&\fBEVP_RAND\fR API. +.SS Identity +.IX Subsection "Identity" +"HASH\-DRBG" is the name for this implementation; it can be used with the +\&\fBEVP_RAND_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """state"" (\fBOSSL_RAND_PARAM_STATE\fR) " 4 +.IX Item """state"" (OSSL_RAND_PARAM_STATE) " +.PD 0 +.IP """strength"" (\fBOSSL_RAND_PARAM_STRENGTH\fR) " 4 +.IX Item """strength"" (OSSL_RAND_PARAM_STRENGTH) " +.IP """max_request"" (\fBOSSL_RAND_PARAM_MAX_REQUEST\fR) " 4 +.IX Item """max_request"" (OSSL_RAND_PARAM_MAX_REQUEST) " +.IP """reseed_requests"" (\fBOSSL_DRBG_PARAM_RESEED_REQUESTS\fR) " 4 +.IX Item """reseed_requests"" (OSSL_DRBG_PARAM_RESEED_REQUESTS) " +.IP """reseed_time_interval"" (\fBOSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\fR) " 4 +.IX Item """reseed_time_interval"" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) " +.IP """min_entropylen"" (\fBOSSL_DRBG_PARAM_MIN_ENTROPYLEN\fR) " 4 +.IX Item """min_entropylen"" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) " +.IP """max_entropylen"" (\fBOSSL_DRBG_PARAM_MAX_ENTROPYLEN\fR) " 4 +.IX Item """max_entropylen"" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) " +.IP """min_noncelen"" (\fBOSSL_DRBG_PARAM_MIN_NONCELEN\fR) " 4 +.IX Item """min_noncelen"" (OSSL_DRBG_PARAM_MIN_NONCELEN) " +.IP """max_noncelen"" (\fBOSSL_DRBG_PARAM_MAX_NONCELEN\fR) " 4 +.IX Item """max_noncelen"" (OSSL_DRBG_PARAM_MAX_NONCELEN) " +.IP """max_perslen"" (\fBOSSL_DRBG_PARAM_MAX_PERSLEN\fR) " 4 +.IX Item """max_perslen"" (OSSL_DRBG_PARAM_MAX_PERSLEN) " +.IP """max_adinlen"" (\fBOSSL_DRBG_PARAM_MAX_ADINLEN\fR) " 4 +.IX Item """max_adinlen"" (OSSL_DRBG_PARAM_MAX_ADINLEN) " +.IP """reseed_counter"" (\fBOSSL_DRBG_PARAM_RESEED_COUNTER\fR) " 4 +.IX Item """reseed_counter"" (OSSL_DRBG_PARAM_RESEED_COUNTER) " +.IP """properties"" (\fBOSSL_DRBG_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_DRBG_PARAM_PROPERTIES) " +.IP """digest"" (\fBOSSL_DRBG_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_DRBG_PARAM_DIGEST) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_RAND\fR\|(3). +.IP """fips\-indicator"" (\fBOSSL_DRBG_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_DRBG_PARAM_FIPS_APPROVED_INDICATOR) " +.PD 0 +.IP """digest\-check"" (\fBOSSL_DRBG_PARAM_FIPS_DIGEST_CHECK\fR) " 4 +.IX Item """digest-check"" (OSSL_DRBG_PARAM_FIPS_DIGEST_CHECK) " +.PD +These parameters work as described in "PARAMETERS" in \fBprovider\-rand\fR\|(7). +.SH NOTES +.IX Header "NOTES" +When the FIPS provider is installed using the \fB\-no_drbg_truncated_digests\fR +option to fipsinstall, only these digests are permitted (as per +FIPS 140\-3 IG D.R ): +.PP +The default HASH\-DRBG implementation attempts to fetch the required internal +algorithms from the provider they are built into (eg the default provider) +regardless of the properties provided. Should the provider not implement +the required algorithms then properties will be used to find a different +implementation. +.IP SHA\-1 4 +.IX Item "SHA-1" +.PD 0 +.IP SHA2\-256 4 +.IX Item "SHA2-256" +.IP SHA2\-512 4 +.IX Item "SHA2-512" +.IP SHA3\-256 4 +.IX Item "SHA3-256" +.IP SHA3\-512 4 +.IX Item "SHA3-512" +.PD +.PP +A context for HASH DRBG can be obtained by calling: +.PP +.Vb 2 +\& EVP_RAND *rand = EVP_RAND_fetch(NULL, "HASH\-DRBG", NULL); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL); +.Ve +.SH EXAMPLES +.IX Header "EXAMPLES" +.Vb 5 +\& EVP_RAND *rand; +\& EVP_RAND_CTX *rctx; +\& unsigned char bytes[100]; +\& OSSL_PARAM params[2], *p = params; +\& unsigned int strength = 128; +\& +\& rand = EVP_RAND_fetch(NULL, "HASH\-DRBG", NULL); +\& rctx = EVP_RAND_CTX_new(rand, NULL); +\& EVP_RAND_free(rand); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_DIGEST, SN_sha512, 0); +\& *p = OSSL_PARAM_construct_end(); +\& EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params); +\& +\& EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0); +\& +\& EVP_RAND_CTX_free(rctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +NIST SP 800\-90A and SP 800\-90B +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_RAND\fR\|(3), +"PARAMETERS" in \fBEVP_RAND\fR\|(3), +\&\fBopenssl\-fipsinstall\fR\|(1) +.SH HISTORY +.IX Header "HISTORY" +OpenSSL 3.1.1 introduced the \fB\-no_drbg_truncated_digests\fR option to +fipsinstall which restricts the permitted digests when using the FIPS +provider in a complaint manner. For details refer to +FIPS 140\-3 IG D.R . +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_RAND-HMAC-DRBG.7 b/static/netbsd/man7/EVP_RAND-HMAC-DRBG.7 new file mode 100644 index 00000000..8c4565e3 --- /dev/null +++ b/static/netbsd/man7/EVP_RAND-HMAC-DRBG.7 @@ -0,0 +1,193 @@ +.\" $NetBSD: EVP_RAND-HMAC-DRBG.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_RAND-HMAC-DRBG 7" +.TH EVP_RAND-HMAC-DRBG 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_RAND\-HMAC\-DRBG \- The HMAC DRBG EVP_RAND implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for the HMAC deterministic random bit generator through the +\&\fBEVP_RAND\fR API. +.SS Identity +.IX Subsection "Identity" +"HMAC\-DRBG" is the name for this implementation; it can be used with the +\&\fBEVP_RAND_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """state"" (\fBOSSL_RAND_PARAM_STATE\fR) " 4 +.IX Item """state"" (OSSL_RAND_PARAM_STATE) " +.PD 0 +.IP """strength"" (\fBOSSL_RAND_PARAM_STRENGTH\fR) " 4 +.IX Item """strength"" (OSSL_RAND_PARAM_STRENGTH) " +.IP """max_request"" (\fBOSSL_RAND_PARAM_MAX_REQUEST\fR) " 4 +.IX Item """max_request"" (OSSL_RAND_PARAM_MAX_REQUEST) " +.IP """reseed_requests"" (\fBOSSL_DRBG_PARAM_RESEED_REQUESTS\fR) " 4 +.IX Item """reseed_requests"" (OSSL_DRBG_PARAM_RESEED_REQUESTS) " +.IP """reseed_time_interval"" (\fBOSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\fR) " 4 +.IX Item """reseed_time_interval"" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) " +.IP """min_entropylen"" (\fBOSSL_DRBG_PARAM_MIN_ENTROPYLEN\fR) " 4 +.IX Item """min_entropylen"" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) " +.IP """max_entropylen"" (\fBOSSL_DRBG_PARAM_MAX_ENTROPYLEN\fR) " 4 +.IX Item """max_entropylen"" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) " +.IP """min_noncelen"" (\fBOSSL_DRBG_PARAM_MIN_NONCELEN\fR) " 4 +.IX Item """min_noncelen"" (OSSL_DRBG_PARAM_MIN_NONCELEN) " +.IP """max_noncelen"" (\fBOSSL_DRBG_PARAM_MAX_NONCELEN\fR) " 4 +.IX Item """max_noncelen"" (OSSL_DRBG_PARAM_MAX_NONCELEN) " +.IP """max_perslen"" (\fBOSSL_DRBG_PARAM_MAX_PERSLEN\fR) " 4 +.IX Item """max_perslen"" (OSSL_DRBG_PARAM_MAX_PERSLEN) " +.IP """max_adinlen"" (\fBOSSL_DRBG_PARAM_MAX_ADINLEN\fR) " 4 +.IX Item """max_adinlen"" (OSSL_DRBG_PARAM_MAX_ADINLEN) " +.IP """reseed_counter"" (\fBOSSL_DRBG_PARAM_RESEED_COUNTER\fR) " 4 +.IX Item """reseed_counter"" (OSSL_DRBG_PARAM_RESEED_COUNTER) " +.IP """properties"" (\fBOSSL_DRBG_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_DRBG_PARAM_PROPERTIES) " +.IP """mac"" (\fBOSSL_DRBG_PARAM_MAC\fR) " 4 +.IX Item """mac"" (OSSL_DRBG_PARAM_MAC) " +.IP """digest"" (\fBOSSL_DRBG_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_DRBG_PARAM_DIGEST) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_RAND\fR\|(3). +.IP """fips\-indicator"" (\fBOSSL_DRBG_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_DRBG_PARAM_FIPS_APPROVED_INDICATOR) " +.PD 0 +.IP """digest\-check"" (\fBOSSL_DRBG_PARAM_FIPS_DIGEST_CHECK\fR) " 4 +.IX Item """digest-check"" (OSSL_DRBG_PARAM_FIPS_DIGEST_CHECK) " +.PD +These parameters work as described in "PARAMETERS" in \fBprovider\-rand\fR\|(7). +.SH NOTES +.IX Header "NOTES" +When using the FIPS provider, only these digests are permitted (as per +FIPS 140\-3 IG D.R ): +.PP +The default HMAC\-DRBG implementation attempts to fetch the required internal +algorithms from the provider they are built into (eg the default provider) +regardless of the properties provided. Should the provider not implement +the required algorithms then properties will be used to find a different +implementation. +.IP SHA\-1 4 +.IX Item "SHA-1" +.PD 0 +.IP SHA2\-256 4 +.IX Item "SHA2-256" +.IP SHA2\-512 4 +.IX Item "SHA2-512" +.IP SHA3\-256 4 +.IX Item "SHA3-256" +.IP SHA3\-512 4 +.IX Item "SHA3-512" +.PD +.PP +A context for HMAC DRBG can be obtained by calling: +.PP +.Vb 2 +\& EVP_RAND *rand = EVP_RAND_fetch(NULL, "HMAC\-DRBG", NULL); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL); +.Ve +.SH EXAMPLES +.IX Header "EXAMPLES" +.Vb 5 +\& EVP_RAND *rand; +\& EVP_RAND_CTX *rctx; +\& unsigned char bytes[100]; +\& OSSL_PARAM params[3], *p = params; +\& unsigned int strength = 128; +\& +\& rand = EVP_RAND_fetch(NULL, "HMAC\-DRBG", NULL); +\& rctx = EVP_RAND_CTX_new(rand, NULL); +\& EVP_RAND_free(rand); +\& +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_MAC, SN_hmac, 0); +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_DIGEST, SN_sha256, 0); +\& *p = OSSL_PARAM_construct_end(); +\& EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params); +\& +\& EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0); +\& +\& EVP_RAND_CTX_free(rctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +NIST SP 800\-90A and SP 800\-90B +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_RAND\fR\|(3), +"PARAMETERS" in \fBEVP_RAND\fR\|(3), +\&\fBopenssl\-fipsinstall\fR\|(1) +.SH HISTORY +.IX Header "HISTORY" +OpenSSL 3.1.1 introduced the \fB\-no_drbg_truncated_digests\fR option to +fipsinstall which restricts the permitted digests when using the FIPS +provider in a complaint manner. For details refer to +FIPS 140\-3 IG D.R ). +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_RAND-JITTER.7 b/static/netbsd/man7/EVP_RAND-JITTER.7 new file mode 100644 index 00000000..a1b29da4 --- /dev/null +++ b/static/netbsd/man7/EVP_RAND-JITTER.7 @@ -0,0 +1,158 @@ +.\" $NetBSD: EVP_RAND-JITTER.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_RAND-JITTER 7" +.TH EVP_RAND-JITTER 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_RAND\-JITTER \- The randomness seed source EVP_RAND implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for deterministic random number generator seeding through the +\&\fBEVP_RAND\fR API. +.PP +This software seed source produces randomness based on tiny CPU +"jitter" fluctuations. +.PP +It is available when OpenSSL is compiled with \fBenable\-jitter\fR +option. When available it is listed in \fBopenssl list +\&\-random\-generators\fR and \fBopenssl info \-seeds\fR. +.SS Identity +.IX Subsection "Identity" +"JITTER" is the name for this implementation; it can be used with the +\&\fBEVP_RAND_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """state"" (\fBOSSL_RAND_PARAM_STATE\fR) " 4 +.IX Item """state"" (OSSL_RAND_PARAM_STATE) " +.PD 0 +.IP """strength"" (\fBOSSL_RAND_PARAM_STRENGTH\fR) " 4 +.IX Item """strength"" (OSSL_RAND_PARAM_STRENGTH) " +.IP """max_request"" (\fBOSSL_RAND_PARAM_MAX_REQUEST\fR) " 4 +.IX Item """max_request"" (OSSL_RAND_PARAM_MAX_REQUEST) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_RAND\fR\|(3). +.SH NOTES +.IX Header "NOTES" +A context for the seed source can be obtained by calling: +.PP +.Vb 2 +\& EVP_RAND *rand = EVP_RAND_fetch(NULL, "JITTER", NULL); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL); +.Ve +.PP +The \fBenable\-jitter\fR option was added in OpenSSL 3.4. +.PP +By specifying the \fBenable\-fips\-jitter\fR configuration option, the FIPS +provider will use an internal jitter source for its entropy. Enabling +this option will cause the FIPS provider to operate in a non\-compliant +mode unless an entropy assessment +ESV +and validation through the +CMVP +are additionally conducted. This option was added in OpenSSL 3.5. +.SH EXAMPLES +.IX Header "EXAMPLES" +.Vb 5 +\& EVP_RAND *rand; +\& EVP_RAND_CTX *seed, *rctx; +\& unsigned char bytes[100]; +\& OSSL_PARAM params[2], *p = params; +\& unsigned int strength = 128; +\& +\& /* Create and instantiate a seed source */ +\& rand = EVP_RAND_fetch(NULL, "JITTER", NULL); +\& seed = EVP_RAND_CTX_new(rand, NULL); +\& EVP_RAND_instantiate(seed, strength, 0, NULL, 0, NULL); +\& EVP_RAND_free(rand); +\& +\& /* Feed this into a DRBG */ +\& rand = EVP_RAND_fetch(NULL, "CTR\-DRBG", NULL); +\& rctx = EVP_RAND_CTX_new(rand, seed); +\& EVP_RAND_free(rand); +\& +\& /* Configure the DRBG */ +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER, +\& SN_aes_256_ctr, 0); +\& *p = OSSL_PARAM_construct_end(); +\& EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params); +\& +\& EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0); +\& +\& EVP_RAND_CTX_free(rctx); +\& EVP_RAND_CTX_free(seed); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_RAND\fR\|(3), +"PARAMETERS" in \fBEVP_RAND\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_RAND-SEED-SRC.7 b/static/netbsd/man7/EVP_RAND-SEED-SRC.7 new file mode 100644 index 00000000..0e22ecb0 --- /dev/null +++ b/static/netbsd/man7/EVP_RAND-SEED-SRC.7 @@ -0,0 +1,144 @@ +.\" $NetBSD: EVP_RAND-SEED-SRC.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_RAND-SEED-SRC 7" +.TH EVP_RAND-SEED-SRC 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_RAND\-SEED\-SRC \- The randomness seed source EVP_RAND implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for deterministic random number generator seeding through the +\&\fBEVP_RAND\fR API. +.PP +The seed sources used are specified at the time OpenSSL is configured for +building using the \fB\-\-with\-rand\-seed=\fR option. By default, operating system +randomness sources are used. +.SS Identity +.IX Subsection "Identity" +"SEED\-SRC" is the name for this implementation; it can be used with the +\&\fBEVP_RAND_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """state"" (\fBOSSL_RAND_PARAM_STATE\fR) " 4 +.IX Item """state"" (OSSL_RAND_PARAM_STATE) " +.PD 0 +.IP """strength"" (\fBOSSL_RAND_PARAM_STRENGTH\fR) " 4 +.IX Item """strength"" (OSSL_RAND_PARAM_STRENGTH) " +.IP """max_request"" (\fBOSSL_RAND_PARAM_MAX_REQUEST\fR) " 4 +.IX Item """max_request"" (OSSL_RAND_PARAM_MAX_REQUEST) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_RAND\fR\|(3). +.SH NOTES +.IX Header "NOTES" +A context for the seed source can be obtained by calling: +.PP +.Vb 2 +\& EVP_RAND *rand = EVP_RAND_fetch(NULL, "SEED\-SRC", NULL); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL); +.Ve +.SH EXAMPLES +.IX Header "EXAMPLES" +.Vb 5 +\& EVP_RAND *rand; +\& EVP_RAND_CTX *seed, *rctx; +\& unsigned char bytes[100]; +\& OSSL_PARAM params[2], *p = params; +\& unsigned int strength = 128; +\& +\& /* Create and instantiate a seed source */ +\& rand = EVP_RAND_fetch(NULL, "SEED\-SRC", NULL); +\& seed = EVP_RAND_CTX_new(rand, NULL); +\& EVP_RAND_instantiate(seed, strength, 0, NULL, 0, NULL); +\& EVP_RAND_free(rand); +\& +\& /* Feed this into a DRBG */ +\& rand = EVP_RAND_fetch(NULL, "CTR\-DRBG", NULL); +\& rctx = EVP_RAND_CTX_new(rand, seed); +\& EVP_RAND_free(rand); +\& +\& /* Configure the DRBG */ +\& *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER, +\& SN_aes_256_ctr, 0); +\& *p = OSSL_PARAM_construct_end(); +\& EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params); +\& +\& EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0); +\& +\& EVP_RAND_CTX_free(rctx); +\& EVP_RAND_CTX_free(seed); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_RAND\fR\|(3), +"PARAMETERS" in \fBEVP_RAND\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_RAND-TEST-RAND.7 b/static/netbsd/man7/EVP_RAND-TEST-RAND.7 new file mode 100644 index 00000000..6397275d --- /dev/null +++ b/static/netbsd/man7/EVP_RAND-TEST-RAND.7 @@ -0,0 +1,178 @@ +.\" $NetBSD: EVP_RAND-TEST-RAND.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_RAND-TEST-RAND 7" +.TH EVP_RAND-TEST-RAND 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_RAND\-TEST\-RAND \- The test EVP_RAND implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for a test generator through the \fBEVP_RAND\fR API. This generator is +for test purposes only, it does not generate random numbers. +.SS Identity +.IX Subsection "Identity" +"TEST\-RAND" is the name for this implementation; it can be used with the +\&\fBEVP_RAND_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """state"" (\fBOSSL_RAND_PARAM_STATE\fR) " 4 +.IX Item """state"" (OSSL_RAND_PARAM_STATE) " +.PD 0 +.IP """fips\-indicator"" (\fBOSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR) " +.PD +These parameter works as described in "PARAMETERS" in \fBEVP_RAND\fR\|(3). +.IP """strength"" (\fBOSSL_RAND_PARAM_STRENGTH\fR) " 4 +.IX Item """strength"" (OSSL_RAND_PARAM_STRENGTH) " +.PD 0 +.IP """reseed_requests"" (\fBOSSL_DRBG_PARAM_RESEED_REQUESTS\fR) " 4 +.IX Item """reseed_requests"" (OSSL_DRBG_PARAM_RESEED_REQUESTS) " +.IP """reseed_time_interval"" (\fBOSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\fR) " 4 +.IX Item """reseed_time_interval"" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) " +.IP """max_request"" (\fBOSSL_DRBG_PARAM_RESEED_REQUESTS\fR) " 4 +.IX Item """max_request"" (OSSL_DRBG_PARAM_RESEED_REQUESTS) " +.IP """min_entropylen"" (\fBOSSL_DRBG_PARAM_MIN_ENTROPYLEN\fR) " 4 +.IX Item """min_entropylen"" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) " +.IP """max_entropylen"" (\fBOSSL_DRBG_PARAM_MAX_ENTROPYLEN\fR) " 4 +.IX Item """max_entropylen"" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) " +.IP """min_noncelen"" (\fBOSSL_DRBG_PARAM_MIN_NONCELEN\fR) " 4 +.IX Item """min_noncelen"" (OSSL_DRBG_PARAM_MIN_NONCELEN) " +.IP """max_noncelen"" (\fBOSSL_DRBG_PARAM_MAX_NONCELEN\fR) " 4 +.IX Item """max_noncelen"" (OSSL_DRBG_PARAM_MAX_NONCELEN) " +.IP """max_perslen"" (\fBOSSL_DRBG_PARAM_MAX_PERSLEN\fR) " 4 +.IX Item """max_perslen"" (OSSL_DRBG_PARAM_MAX_PERSLEN) " +.IP """max_adinlen"" (\fBOSSL_DRBG_PARAM_MAX_ADINLEN\fR) " 4 +.IX Item """max_adinlen"" (OSSL_DRBG_PARAM_MAX_ADINLEN) " +.IP """reseed_counter"" (\fBOSSL_DRBG_PARAM_RESEED_COUNTER\fR) " 4 +.IX Item """reseed_counter"" (OSSL_DRBG_PARAM_RESEED_COUNTER) " +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_RAND\fR\|(3), except that +they can all be set as well as read. +.IP """test_entropy"" (\fBOSSL_RAND_PARAM_TEST_ENTROPY\fR) " 4 +.IX Item """test_entropy"" (OSSL_RAND_PARAM_TEST_ENTROPY) " +Sets the bytes returned when the test generator is sent an entropy request. +The current position is remembered across generate calls. +If there are insufficient data present to satisfy a call, an error is returned. +.IP """test_nonce"" (\fBOSSL_RAND_PARAM_TEST_NONCE\fR) " 4 +.IX Item """test_nonce"" (OSSL_RAND_PARAM_TEST_NONCE) " +Sets the bytes returned when the test generator is sent a nonce request. +Each nonce request will return all of the bytes. +.IP """generate"" (\fBOSSL_RAND_PARAM_GENERATE\fR) " 4 +.IX Item """generate"" (OSSL_RAND_PARAM_GENERATE) " +If this parameter is zero, it will only emit the nonce and entropy data +supplied via the aforementioned parameters. Otherwise, low quality +non\-cryptographic pseudorandom output is produced. This parameter defaults +to zero. +.SH NOTES +.IX Header "NOTES" +A context for a test generator can be obtained by calling: +.PP +.Vb 2 +\& EVP_RAND *rand = EVP_RAND_fetch(NULL, "TEST\-RAND", NULL); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL); +.Ve +.SH EXAMPLES +.IX Header "EXAMPLES" +.Vb 7 +\& EVP_RAND *rand; +\& EVP_RAND_CTX *rctx; +\& unsigned char bytes[100]; +\& OSSL_PARAM params[4], *p = params; +\& unsigned char entropy[1000] = { ... }; +\& unsigned char nonce[20] = { ... }; +\& unsigned int strength = 48; +\& +\& rand = EVP_RAND_fetch(NULL, "TEST\-RAND", NULL); +\& rctx = EVP_RAND_CTX_new(rand, NULL); +\& EVP_RAND_free(rand); +\& +\& *p++ = OSSL_PARAM_construct_uint(OSSL_RAND_PARAM_STRENGTH, &strength); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_RAND_PARAM_TEST_ENTROPY, +\& entropy, sizeof(entropy)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_RAND_PARAM_TEST_NONCE, +\& nonce, sizeof(nonce)); +\& *p = OSSL_PARAM_construct_end(); +\& EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params); +\& +\& EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0); +\& +\& EVP_RAND_CTX_free(rctx); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_RAND\fR\|(3), +"PARAMETERS" in \fBEVP_RAND\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_RAND.7 b/static/netbsd/man7/EVP_RAND.7 new file mode 100644 index 00000000..0f9db6ec --- /dev/null +++ b/static/netbsd/man7/EVP_RAND.7 @@ -0,0 +1,334 @@ +.\" $NetBSD: EVP_RAND.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_RAND 7" +.TH EVP_RAND 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_RAND \- the random bit generator +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The default OpenSSL RAND method is based on the EVP_RAND classes to provide +non\-deterministic inputs to other cryptographic algorithms. +.PP +While the RAND API is the \*(Aqfrontend\*(Aq which is intended to be used by +application developers for obtaining random bytes, the EVP_RAND API +serves as the \*(Aqbackend\*(Aq, connecting the former with the operating +systems\*(Aqs entropy sources and providing access to deterministic random +bit generators (DRBG) and their configuration parameters. +A DRBG is a certain type of cryptographically\-secure pseudo\-random +number generator (CSPRNG), which is described in +[NIST SP 800\-90A Rev. 1]. +.SS Disclaimer +.IX Subsection "Disclaimer" +Unless you have very specific requirements for your random generator, +it is in general not necessary to utilize the EVP_RAND API directly. +The usual way to obtain random bytes is to use \fBRAND_bytes\fR\|(3) or +\&\fBRAND_priv_bytes\fR\|(3), see also \fBRAND\fR\|(7). +.SS "Typical Use Cases" +.IX Subsection "Typical Use Cases" +Typical examples for such special use cases are the following: +.IP \(bu 2 +You want to use your own private DRBG instances. +Multiple DRBG instances which are accessed only by a single thread provide +additional security (because their internal states are independent) and +better scalability in multithreaded applications (because they don\*(Aqt need +to be locked). +.IP \(bu 2 +You need to integrate a previously unsupported entropy source. +Refer to \fBprovider\-rand\fR\|(7) for the implementation details to support adding +randomness sources to EVP_RAND. +.IP \(bu 2 +You need to change the default settings of the standard OpenSSL RAND +implementation to meet specific requirements. +.SH "EVP_RAND CHAINING" +.IX Header "EVP_RAND CHAINING" +An EVP_RAND instance can be used as the entropy source of another +EVP_RAND instance, provided it has itself access to a valid entropy source. +The EVP_RAND instance which acts as entropy source is called the \fIparent\fR, +the other instance the \fIchild\fR. Typically, the child will be a DRBG because +it does not make sense for the child to be an entropy source. +.PP +This is called chaining. A chained EVP_RAND instance is created by passing +a pointer to the parent EVP_RAND_CTX as argument to the \fBEVP_RAND_CTX_new()\fR call. +It is possible to create chains of more than two DRBG in a row. +It is also possible to use any EVP_RAND_CTX class as the parent, however, only +a live entropy source may ignore and not use its parent. +.SH "THE THREE SHARED DRBG INSTANCES" +.IX Header "THE THREE SHARED DRBG INSTANCES" +Currently, there are three shared DRBG instances, +the , , and DRBG. +While the DRBG is a single global instance, the and +DRBG are created per thread and accessed through thread\-local storage. +.PP +By default, the functions \fBRAND_bytes\fR\|(3) and \fBRAND_priv_bytes\fR\|(3) use +the thread\-local and DRBG instance, respectively. +.SS "The DRBG instance" +.IX Subsection "The DRBG instance" +The DRBG is not used directly by the application, only for reseeding +the two other two DRBG instances. It reseeds itself by obtaining randomness +either from os entropy sources or by consuming randomness which was added +previously by \fBRAND_add\fR\|(3). +.SS "The DRBG instance" +.IX Subsection "The DRBG instance" +This instance is used per default by \fBRAND_bytes\fR\|(3). +.SS "The DRBG instance" +.IX Subsection "The DRBG instance" +This instance is used per default by \fBRAND_priv_bytes\fR\|(3) +.SH LOCKING +.IX Header "LOCKING" +The DRBG is intended to be accessed concurrently for reseeding +by its child DRBG instances. The necessary locking is done internally. +It is \fInot\fR thread\-safe to access the DRBG directly via the +EVP_RAND interface. +The and DRBG are thread\-local, i.e. there is an +instance of each per thread. So they can safely be accessed without +locking via the EVP_RAND interface. +.PP +Pointers to these DRBG instances can be obtained using +\&\fBRAND_get0_primary()\fR, \fBRAND_get0_public()\fR and \fBRAND_get0_private()\fR, respectively. +Note that it is not allowed to store a pointer to one of the thread\-local +DRBG instances in a variable or other memory location where it will be +accessed and used by multiple threads. +.PP +All other DRBG instances created by an application don\*(Aqt support locking, +because they are intended to be used by a single thread. +Instead of accessing a single DRBG instance concurrently from different +threads, it is recommended to instantiate a separate DRBG instance per +thread. Using the DRBG as entropy source for multiple DRBG +instances on different threads is thread\-safe, because the DRBG instance +will lock the DRBG automatically for obtaining random input. +.SH "THE OVERALL PICTURE" +.IX Header "THE OVERALL PICTURE" +The following picture gives an overview over how the DRBG instances work +together and are being used. +.PP +.Vb 10 +\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\& | os entropy sources | +\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\& | +\& v +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\& RAND_add() ==> <\-| shared DRBG (with locking) | +\& / \e +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\& / \e +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\& <\- | per\-thread DRBG instances | +\& | | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\& v v +\& RAND_bytes() RAND_priv_bytes() +\& | ^ +\& | | +\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\& | general purpose | | used for secrets like session keys | +\& | random generator | | and private keys for certificates | +\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +.Ve +.PP +The usual way to obtain random bytes is to call RAND_bytes(...) or +RAND_priv_bytes(...). These calls are roughly equivalent to calling +EVP_RAND_generate(, ...) and +EVP_RAND_generate(, ...), +respectively. +.SH RESEEDING +.IX Header "RESEEDING" +A DRBG instance seeds itself automatically, pulling random input from +its entropy source. The entropy source can be either a trusted operating +system entropy source, or another DRBG with access to such a source. +.PP +Automatic reseeding occurs after a predefined number of generate requests. +The selection of the trusted entropy sources is configured at build +time using the \-\-with\-rand\-seed option. The following sections explain +the reseeding process in more detail. +.SS "Automatic Reseeding" +.IX Subsection "Automatic Reseeding" +Before satisfying a generate request (\fBEVP_RAND_generate\fR\|(3)), the DRBG +reseeds itself automatically, if one of the following conditions holds: +.PP +\&\- the DRBG was not instantiated (=seeded) yet or has been uninstantiated. +.PP +\&\- the number of generate requests since the last reseeding exceeds a +certain threshold, the so called \fIreseed_interval\fR. +This behaviour can be disabled by setting the \fIreseed_interval\fR to 0. +.PP +\&\- the time elapsed since the last reseeding exceeds a certain time +interval, the so called \fIreseed_time_interval\fR. +This can be disabled by setting the \fIreseed_time_interval\fR to 0. +.PP +\&\- the DRBG is in an error state. +.PP +\&\fBNote\fR: An error state is entered if the entropy source fails while +the DRBG is seeding or reseeding. +The last case ensures that the DRBG automatically recovers +from the error as soon as the entropy source is available again. +.SS "Manual Reseeding" +.IX Subsection "Manual Reseeding" +In addition to automatic reseeding, the caller can request an immediate +reseeding of the DRBG with fresh entropy by setting the +\&\fIprediction resistance\fR parameter to 1 when calling +\&\fBEVP_RAND_generate\fR\|(3). +.PP +The document [NIST SP 800\-90C] describes prediction resistance requests +in detail and imposes strict conditions on the entropy sources that are +approved for providing prediction resistance. +A request for prediction resistance can only be satisfied by pulling fresh +entropy from a live entropy source (section 5.5.2 of [NIST SP 800\-90C]). +It is up to the user to ensure that a live entropy source is configured +and is being used. +.PP +For the three shared DRBGs (and only for these) there is another way to +reseed them manually: +If \fBRAND_add\fR\|(3) is called with a positive \fIrandomness\fR argument +(or \fBRAND_seed\fR\|(3)), then this will immediately reseed the DRBG. +The and DRBG will detect this on their next generate +call and reseed, pulling randomness from . +.PP +The last feature has been added to support the common practice used with +previous OpenSSL versions to call \fBRAND_add()\fR before calling \fBRAND_bytes()\fR. +.SS "Entropy Input and Additional Data" +.IX Subsection "Entropy Input and Additional Data" +The DRBG distinguishes two different types of random input: \fIentropy\fR, +which comes from a trusted source, and \fIadditional input\fR\*(Aq, +which can optionally be added by the user and is considered untrusted. +It is possible to add \fIadditional input\fR not only during reseeding, +but also for every generate request. +.SS "Configuring the Random Seed Source" +.IX Subsection "Configuring the Random Seed Source" +In most cases OpenSSL will automatically choose a suitable seed source +for automatically seeding and reseeding its DRBG. The +default seed source can be configured when OpenSSL is compiled by +setting \fB\-DOPENSSL_DEFAULT_SEED_SRC=SEED\-SRC\fR. If not set then +"SEED\-SRC" is used. One can specify a third\-party provider seed\-source, +or \fB\-DOPENSSL_DEFAULT_SEED_SRC=JITTER\fR if available. +.PP +In some cases however, it will be necessary to explicitly specify a +seed source used by "SEED\-SRC" during configuration, using the +\&\-\-with\-rand\-seed option. For more information, see the INSTALL +instructions. There are also operating systems where no seed source is +available and automatic reseeding is disabled by default. +.PP +The following two sections describe the reseeding process of the primary +DRBG, depending on whether automatic reseeding is available or not. +.SS "Reseeding the primary DRBG with automatic seeding enabled" +.IX Subsection "Reseeding the primary DRBG with automatic seeding enabled" +Calling \fBRAND_poll()\fR or \fBRAND_add()\fR is not necessary, because the DRBG +pulls the necessary entropy from its source automatically. +However, both calls are permitted, and do reseed the RNG. +.PP +\&\fBRAND_add()\fR can be used to add both kinds of random input, depending on the +value of the \fIrandomness\fR argument: +.IP "randomness == 0:" 4 +.IX Item "randomness == 0:" +The random bytes are mixed as additional input into the current state of +the DRBG. +Mixing in additional input is not considered a full reseeding, hence the +reseed counter is not reset. +.IP "randomness > 0:" 4 +.IX Item "randomness > 0:" +The random bytes are used as entropy input for a full reseeding +(resp. reinstantiation) if the DRBG is instantiated +(resp. uninstantiated or in an error state). +The number of random bits required for reseeding is determined by the +security strength of the DRBG. Currently it defaults to 256 bits (32 bytes). +It is possible to provide less randomness than required. +In this case the missing randomness will be obtained by pulling random input +from the trusted entropy sources. +.PP +NOTE: Manual reseeding is *not allowed* in FIPS mode, because +[NIST SP\-800\-90Ar1] mandates that entropy *shall not* be provided by +the consuming application for instantiation (Section 9.1) or +reseeding (Section 9.2). For that reason, the \fIrandomness\fR +argument is ignored and the random bytes provided by the \fBRAND_add\fR\|(3) and +\&\fBRAND_seed\fR\|(3) calls are treated as additional data. +.SS "Reseeding the primary DRBG with automatic seeding disabled" +.IX Subsection "Reseeding the primary DRBG with automatic seeding disabled" +Calling \fBRAND_poll()\fR will always fail. +.PP +\&\fBRAND_add()\fR needs to be called for initial seeding and periodic reseeding. +At least 48 bytes (384 bits) of randomness have to be provided, otherwise +the (re\-)seeding of the DRBG will fail. This corresponds to one and a half +times the security strength of the DRBG. The extra half is used for the +nonce during instantiation. +.PP +More precisely, the number of bytes needed for seeding depend on the +\&\fIsecurity strength\fR of the DRBG, which is set to 256 by default. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRAND\fR\|(7), \fBEVP_RAND\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_SIGNATURE-DSA.7 b/static/netbsd/man7/EVP_SIGNATURE-DSA.7 new file mode 100644 index 00000000..2a57988b --- /dev/null +++ b/static/netbsd/man7/EVP_SIGNATURE-DSA.7 @@ -0,0 +1,173 @@ +.\" $NetBSD: EVP_SIGNATURE-DSA.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_SIGNATURE-DSA 7" +.TH EVP_SIGNATURE-DSA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_SIGNATURE\-DSA +\&\- The EVP_PKEY DSA signature implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing DSA signatures. The signature produced with +\&\fBEVP_PKEY_sign\fR\|(3) is DER encoded ASN.1 in the form described in +RFC 3279, section 2.2.2. +See \fBEVP_PKEY\-DSA\fR\|(7) for information related to DSA keys. +.PP +As part of FIPS 140\-3 DSA is not longer FIPS approved for key generation and +signature validation, but is still allowed for signature verification. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +In this list, names are grouped together to signify that they are the same +algorithm having multiple names. This also includes the OID in canonical +decimal form (which means that they are possible to fetch if the caller has a +mere OID which came out in this form after a call to \fBOBJ_obj2txt\fR\|(3)). +.IP """DSA"", ""dsaEncryption"", ""1.2.840.10040.4.1""" 4 +.IX Item """DSA"", ""dsaEncryption"", ""1.2.840.10040.4.1""" +The base signature algorithm, supported explicitly fetched with +\&\fBEVP_PKEY_sign_init_ex2\fR\|(3), and implicitly fetched (through +EC keys) with \fBEVP_DigestSignInit\fR\|(3) and +\&\fBEVP_DigestVerifyInit\fR\|(3). +.Sp +It can\*(Aqt be used with \fBEVP_PKEY_sign_message_init\fR\|(3) +.IP """DSA\-SHA1"", ""DSA\-SHA\-1"", ""dsaWithSHA1"", ""1.2.840.10040.4.3""" 4 +.IX Item """DSA-SHA1"", ""DSA-SHA-1"", ""dsaWithSHA1"", ""1.2.840.10040.4.3""" +.PD 0 +.IP """DSA\-SHA2\-224"", ""DSA\-SHA224"", ""dsa_with_SHA224"", ""2.16.840.1.101.3.4.3.1""" 4 +.IX Item """DSA-SHA2-224"", ""DSA-SHA224"", ""dsa_with_SHA224"", ""2.16.840.1.101.3.4.3.1""" +.IP """DSA\-SHA2\-256"", ""DSA\-SHA256"", ""dsa_with_SHA256"", ""2.16.840.1.101.3.4.3.2""" 4 +.IX Item """DSA-SHA2-256"", ""DSA-SHA256"", ""dsa_with_SHA256"", ""2.16.840.1.101.3.4.3.2""" +.IP """DSA\-SHA2\-384"", ""DSA\-SHA384"", ""dsa_with_SHA384"", ""id\-dsa\-with\-sha384"", ""1.2.840.1.101.3.4.3.3""" 4 +.IX Item """DSA-SHA2-384"", ""DSA-SHA384"", ""dsa_with_SHA384"", ""id-dsa-with-sha384"", ""1.2.840.1.101.3.4.3.3""" +.IP """DSA\-SHA2\-512"", ""DSA\-SHA512"", ""dsa_with_SHA512"", ""id\-dsa\-with\-sha512"", ""1.2.840.1.101.3.4.3.4""" 4 +.IX Item """DSA-SHA2-512"", ""DSA-SHA512"", ""dsa_with_SHA512"", ""id-dsa-with-sha512"", ""1.2.840.1.101.3.4.3.4""" +.IP """DSA\-SHA3\-224"", ""dsa_with_SHA3\-224"", ""id\-dsa\-with\-sha3\-224"", ""2.16.840.1.101.3.4.3.5""" 4 +.IX Item """DSA-SHA3-224"", ""dsa_with_SHA3-224"", ""id-dsa-with-sha3-224"", ""2.16.840.1.101.3.4.3.5""" +.IP """DSA\-SHA3\-256"", ""dsa_with_SHA3\-256"", ""id\-dsa\-with\-sha3\-256"", ""2.16.840.1.101.3.4.3.6""" 4 +.IX Item """DSA-SHA3-256"", ""dsa_with_SHA3-256"", ""id-dsa-with-sha3-256"", ""2.16.840.1.101.3.4.3.6""" +.IP """DSA\-SHA3\-384"", ""dsa_with_SHA3\-384"", ""id\-dsa\-with\-sha3\-384"", ""2.16.840.1.101.3.4.3.7""" 4 +.IX Item """DSA-SHA3-384"", ""dsa_with_SHA3-384"", ""id-dsa-with-sha3-384"", ""2.16.840.1.101.3.4.3.7""" +.IP """DSA\-SHA3\-512"", ""dsa_with_SHA3\-512"", ""id\-dsa\-with\-sha3\-512"", ""2.16.840.1.101.3.4.3.8""" 4 +.IX Item """DSA-SHA3-512"", ""dsa_with_SHA3-512"", ""id-dsa-with-sha3-512"", ""2.16.840.1.101.3.4.3.8""" +.PD +DSA signature schemes with diverse message digest algorithms. They are all +supported explicitly fetched with \fBEVP_PKEY_sign_init_ex2\fR\|(3) and +\&\fBEVP_PKEY_sign_message_init\fR\|(3). +.SS "Signature Parameters" +.IX Subsection "Signature Parameters" +The following signature parameters can be set using \fBEVP_PKEY_CTX_set_params()\fR. +This may be called after \fBEVP_PKEY_sign_init()\fR or \fBEVP_PKEY_verify_init()\fR, +and before calling \fBEVP_PKEY_sign()\fR or \fBEVP_PKEY_verify()\fR. They may also be set +using \fBEVP_PKEY_sign_init_ex()\fR or \fBEVP_PKEY_verify_init_ex()\fR. +.IP """digest"" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_SIGNATURE_PARAM_DIGEST) " +.PD 0 +.IP """properties"" (\fBOSSL_SIGNATURE_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_SIGNATURE_PARAM_PROPERTIES) " +.PD +These two are not supported with the DSA signature schemes that already +include a message digest algorithm, See "Algorithm Names" above. +.IP """nonce\-type"" (\fBOSSL_SIGNATURE_PARAM_NONCE_TYPE\fR) " 4 +.IX Item """nonce-type"" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) " +.PD 0 +.IP """key\-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK) " +.IP """digest\-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_DIGEST_CHECK\fR) " 4 +.IX Item """digest-check"" (OSSL_SIGNATURE_PARAM_FIPS_DIGEST_CHECK) " +.IP """sign\-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_SIGN_CHECK\fR) " 4 +.IX Item """sign-check"" (OSSL_SIGNATURE_PARAM_FIPS_SIGN_CHECK) " +.PD +The settable parameters are described in \fBprovider\-signature\fR\|(7). +.PP +The following signature parameters can be retrieved using +\&\fBEVP_PKEY_CTX_get_params()\fR. +.IP """algorithm\-id"" (\fBOSSL_SIGNATURE_PARAM_ALGORITHM_ID\fR) " 4 +.IX Item """algorithm-id"" (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) " +.PD 0 +.IP """digest"" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_SIGNATURE_PARAM_DIGEST) " +.IP """nonce\-type"" (\fBOSSL_SIGNATURE_PARAM_NONCE_TYPE\fR) " 4 +.IX Item """nonce-type"" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) " +.IP """fips\-indicator"" (\fBOSSL_SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR) " +.PD +The gettable parameters are described in \fBprovider\-signature\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set_params\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBprovider\-signature\fR\|(7), +.SH HISTORY +.IX Header "HISTORY" +DSA Key generation and signature generation are no longer FIPS approved in +OpenSSL 3.4. See "FIPS indicators" in \fBfips_module\fR\|(7) for more information. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_SIGNATURE-ECDSA.7 b/static/netbsd/man7/EVP_SIGNATURE-ECDSA.7 new file mode 100644 index 00000000..d6d5a912 --- /dev/null +++ b/static/netbsd/man7/EVP_SIGNATURE-ECDSA.7 @@ -0,0 +1,162 @@ +.\" $NetBSD: EVP_SIGNATURE-ECDSA.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_SIGNATURE-ECDSA 7" +.TH EVP_SIGNATURE-ECDSA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_SIGNATURE\-ECDSA \- The EVP_PKEY ECDSA signature implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing ECDSA signatures. +See \fBEVP_PKEY\-EC\fR\|(7) for information related to EC keys. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +In this list, names are grouped together to signify that they are the same +algorithm having multiple names. This also includes the OID in canonical +decimal form (which means that they are possible to fetch if the caller has a +mere OID which came out in this form after a call to \fBOBJ_obj2txt\fR\|(3)). +.IP """ECDSA""" 4 +.IX Item """ECDSA""" +The base signature algorithm, supported explicitly fetched with +\&\fBEVP_PKEY_sign_init_ex2\fR\|(3), and implicitly fetched (through +EC keys) with \fBEVP_DigestSignInit\fR\|(3) and +\&\fBEVP_DigestVerifyInit\fR\|(3). +.Sp +It can\*(Aqt be used with \fBEVP_PKEY_sign_message_init\fR\|(3) +.IP """ECDSA\-SHA1"", ""ECDSA\-SHA\-1"", ""ecdsa\-with\-SHA1"", ""1.2.840.10045.4.1""" 4 +.IX Item """ECDSA-SHA1"", ""ECDSA-SHA-1"", ""ecdsa-with-SHA1"", ""1.2.840.10045.4.1""" +.PD 0 +.IP """ECDSA\-SHA2\-224"", ""ECDSA\-SHA224"", ""ecdsa\-with\-SHA224"", ""1.2.840.10045.4.3.1""" 4 +.IX Item """ECDSA-SHA2-224"", ""ECDSA-SHA224"", ""ecdsa-with-SHA224"", ""1.2.840.10045.4.3.1""" +.IP """ECDSA\-SHA2\-256"", ""ECDSA\-SHA256"", ""ecdsa\-with\-SHA256"", ""1.2.840.10045.4.3.2""" 4 +.IX Item """ECDSA-SHA2-256"", ""ECDSA-SHA256"", ""ecdsa-with-SHA256"", ""1.2.840.10045.4.3.2""" +.IP """ECDSA\-SHA2\-384"", ""ECDSA\-SHA384"", ""ecdsa\-with\-SHA384"", ""1.2.840.10045.4.3.3""" 4 +.IX Item """ECDSA-SHA2-384"", ""ECDSA-SHA384"", ""ecdsa-with-SHA384"", ""1.2.840.10045.4.3.3""" +.IP """ECDSA\-SHA2\-512"", ""ECDSA\-SHA512"", ""ecdsa\-with\-SHA512"", ""1.2.840.10045.4.3.4""" 4 +.IX Item """ECDSA-SHA2-512"", ""ECDSA-SHA512"", ""ecdsa-with-SHA512"", ""1.2.840.10045.4.3.4""" +.IP """ECDSA\-SHA3\-224"", ""ecdsa_with_SHA3\-224"", ""id\-ecdsa\-with\-sha3\-224"", ""2.16.840.1.101.3.4.3.9""" 4 +.IX Item """ECDSA-SHA3-224"", ""ecdsa_with_SHA3-224"", ""id-ecdsa-with-sha3-224"", ""2.16.840.1.101.3.4.3.9""" +.IP """ECDSA\-SHA3\-256"", ""ecdsa_with_SHA3\-256"", ""id\-ecdsa\-with\-sha3\-256"", ""2.16.840.1.101.3.4.3.10""" 4 +.IX Item """ECDSA-SHA3-256"", ""ecdsa_with_SHA3-256"", ""id-ecdsa-with-sha3-256"", ""2.16.840.1.101.3.4.3.10""" +.IP """ECDSA\-SHA3\-384"", ""ecdsa_with_SHA3\-384"", ""id\-ecdsa\-with\-sha3\-384"", ""2.16.840.1.101.3.4.3.11""" 4 +.IX Item """ECDSA-SHA3-384"", ""ecdsa_with_SHA3-384"", ""id-ecdsa-with-sha3-384"", ""2.16.840.1.101.3.4.3.11""" +.IP """ECDSA\-SHA3\-512"", ""ecdsa_with_SHA3\-512"", ""id\-ecdsa\-with\-sha3\-512"", ""2.16.840.1.101.3.4.3.12""" 4 +.IX Item """ECDSA-SHA3-512"", ""ecdsa_with_SHA3-512"", ""id-ecdsa-with-sha3-512"", ""2.16.840.1.101.3.4.3.12""" +.PD +ECDSA signature schemes with diverse message digest algorithms. They are all +supported explicitly fetched with \fBEVP_PKEY_sign_init_ex2\fR\|(3) and +\&\fBEVP_PKEY_sign_message_init\fR\|(3). +.SS "ECDSA Signature Parameters" +.IX Subsection "ECDSA Signature Parameters" +The following signature parameters can be set using \fBEVP_PKEY_CTX_set_params()\fR. +This may be called after \fBEVP_PKEY_sign_init()\fR or \fBEVP_PKEY_verify_init()\fR, +and before calling \fBEVP_PKEY_sign()\fR or \fBEVP_PKEY_verify()\fR. +.IP """digest"" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_SIGNATURE_PARAM_DIGEST) " +.PD 0 +.IP """properties"" (\fBOSSL_SIGNATURE_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_SIGNATURE_PARAM_PROPERTIES) " +.PD +These two are not supported with the ECDSA signature schemes that already +include a message digest algorithm, See "Algorithm Names" above. +.IP """nonce\-type"" (\fBOSSL_SIGNATURE_PARAM_NONCE_TYPE\fR) " 4 +.IX Item """nonce-type"" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) " +.PD 0 +.IP """key\-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK) " +.IP """digest\-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_DIGEST_CHECK\fR) " 4 +.IX Item """digest-check"" (OSSL_SIGNATURE_PARAM_FIPS_DIGEST_CHECK) " +.PD +These parameters are described in \fBprovider\-signature\fR\|(7). +.PP +The following signature parameters can be retrieved using +\&\fBEVP_PKEY_CTX_get_params()\fR. +.IP """algorithm\-id"" (\fBOSSL_SIGNATURE_PARAM_ALGORITHM_ID\fR) " 4 +.IX Item """algorithm-id"" (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) " +.PD 0 +.IP """digest"" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_SIGNATURE_PARAM_DIGEST) " +.IP """nonce\-type"" (\fBOSSL_SIGNATURE_PARAM_NONCE_TYPE\fR) " 4 +.IX Item """nonce-type"" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) " +.IP """fips\-indicator"" (\fBOSSL_SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR) " +.IP """verify\-message"" (\fBOSSL_SIGNATURE_PARAM_FIPS_VERIFY_MESSAGE\fR " 4 +.IX Item """verify-message"" (OSSL_SIGNATURE_PARAM_FIPS_VERIFY_MESSAGE " +.PD +The parameters are described in \fBprovider\-signature\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set_params\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBprovider\-signature\fR\|(7), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_SIGNATURE-ED25519.7 b/static/netbsd/man7/EVP_SIGNATURE-ED25519.7 new file mode 100644 index 00000000..6b6950cd --- /dev/null +++ b/static/netbsd/man7/EVP_SIGNATURE-ED25519.7 @@ -0,0 +1,234 @@ +.\" $NetBSD: EVP_SIGNATURE-ED25519.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_SIGNATURE-ED25519 7" +.TH EVP_SIGNATURE-ED25519 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_SIGNATURE\-ED25519, +EVP_SIGNATURE\-ED448, +Ed25519, +Ed448 +\&\- The EVP_PKEY Ed25519 and Ed448 signature implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBEd25519\fR and \fBEd448\fR EVP_PKEY implementation supports key +generation, one\-shot digest\-sign and digest\-verify using the EdDSA +signature schemes described in RFC 8032. It has associated private and +public key formats compatible with RFC 8410. +.SS "EdDSA Instances" +.IX Subsection "EdDSA Instances" +RFC 8032 describes five EdDSA instances: Ed25519, Ed25519ctx, +Ed25519ph, Ed448, Ed448ph. +.PP +The instances Ed25519, Ed25519ctx, Ed448 are referred to as \fBPureEdDSA\fR +schemes. For these three instances, the sign and verify procedures +require access to the complete message (not a digest of the message). +.PP +The instances Ed25519ph, Ed448ph are referred to as \fBHashEdDSA\fR +schemes. For these two instances, the sign and verify procedures do +not require access to the complete message; they operate on a hash of +the message. For Ed25519ph, the hash function is SHA512. For +Ed448ph, the hash function is SHAKE256 with an output length of 512 +bits. +.PP +The instances Ed25519ctx, Ed25519ph, Ed448, Ed448ph accept an optional +\&\fBcontext\-string\fR as input to sign and verify operations (and for +Ed25519ctx, the context\-string must be nonempty). For the Ed25519 +instance, a nonempty context\-string is not permitted. +.PP +These instances can be specified as signature parameters when using +\&\fBEVP_DigestSignInit\fR\|(3) and \fBEVP_DigestVerifyInit\fR\|(3), see +"ED25519 and ED448 Signature Parameters" below. +.PP +These instances are also explicitly fetchable as algorithms using +\&\fBEVP_SIGNATURE_fetch\fR\|(3), which can be used with +\&\fBEVP_PKEY_sign_init_ex2\fR\|(3), \fBEVP_PKEY_verify_init_ex2\fR\|(3), +\&\fBEVP_PKEY_sign_message_init\fR\|(3) and \fBEVP_PKEY_verify_message_init\fR\|(3). +.SS "ED25519 and ED448 Signature Parameters" +.IX Subsection "ED25519 and ED448 Signature Parameters" +Two parameters can be set during signing or verification: the EdDSA +\&\fBinstance name\fR and the \fBcontext\-string value\fR. They can be set by +passing an OSSL_PARAM array to \fBEVP_DigestSignInit_ex()\fR. +.IP \(bu 4 +"instance" (\fBOSSL_SIGNATURE_PARAM_INSTANCE\fR) +.Sp +One of the five strings "Ed25519", "Ed25519ctx", "Ed25519ph", "Ed448", "Ed448ph". +.Sp +"Ed25519", "Ed25519ctx", "Ed25519ph" are valid only for an Ed25519 EVP_PKEY. +.Sp +"Ed448", "Ed448ph" are valid only for an Ed448 EVP_PKEY. +.IP \(bu 4 +"context\-string" (\fBOSSL_SIGNATURE_PARAM_CONTEXT_STRING\fR) +.Sp +A string of octets with length at most 255. +.PP +Both of these parameters are optional. +.PP +When using \fBEVP_DigestSignInit\fR\|(3) or \fBEVP_DigestVerifyInit\fR\|(3), the +signature algorithm is derived from the key type name. The key type name +("Ed25519" or "Ed448") is also the default for the instance, but this can be +changed with the "instance" parameter. +.PP +Note that a message digest name must \fBNOT\fR be specified when signing +or verifying. +.PP +When using \fBEVP_PKEY_sign_init_ex2\fR\|(3), \fBEVP_PKEY_verify_init_ex2\fR\|(3), +\&\fBEVP_PKEY_sign_message_init\fR\|(3) or \fBEVP_PKEY_verify_message_init\fR\|(3), the +instance is the explicit signature algorithm name, and may not be changed +(trying to give one with the "instance" parameter is therefore an error). +.PP +If a context\-string is not specified, then an empty context\-string is +used. +.PP +See \fBEVP_PKEY\-X25519\fR\|(7) for information related to \fBX25519\fR and \fBX448\fR keys. +.PP +The following signature parameters can be retrieved using +\&\fBEVP_PKEY_CTX_get_params()\fR. +.IP \(bu 4 +"algorithm\-id" (\fBOSSL_SIGNATURE_PARAM_ALGORITHM_ID\fR) +.IP \(bu 4 +"instance" (\fBOSSL_SIGNATURE_PARAM_INSTANCE\fR) +.IP \(bu 4 +"context\-string" (\fBOSSL_SIGNATURE_PARAM_CONTEXT_STRING\fR) +.PP +The parameters are described in \fBprovider\-signature\fR\|(7). +.SH NOTES +.IX Header "NOTES" +The PureEdDSA instances do not support the streaming mechanism of +other signature algorithms using, for example, \fBEVP_DigestUpdate()\fR. +The message to sign or verify must be passed using the one\-shot +\&\fBEVP_DigestSign()\fR and \fBEVP_DigestVerify()\fR functions. +.PP +The HashEdDSA instances do not yet support the streaming mechanisms +(so the one\-shot functions must be used with HashEdDSA as well). +.PP +When calling \fBEVP_DigestSignInit()\fR or \fBEVP_DigestVerifyInit()\fR, the +digest \fItype\fR parameter \fBMUST\fR be set to NULL. +.PP +Applications wishing to sign certificates (or other structures such as +CRLs or certificate requests) using Ed25519 or Ed448 can either use \fBX509_sign()\fR +or \fBX509_sign_ctx()\fR in the usual way. +.PP +Ed25519 or Ed448 private keys can be set directly using +\&\fBEVP_PKEY_new_raw_private_key\fR\|(3) or loaded from a PKCS#8 private key file +using \fBPEM_read_bio_PrivateKey\fR\|(3) (or similar function). Completely new keys +can also be generated (see the example below). Setting a private key also sets +the associated public key. +.PP +Ed25519 or Ed448 public keys can be set directly using +\&\fBEVP_PKEY_new_raw_public_key\fR\|(3) or loaded from a SubjectPublicKeyInfo +structure in a PEM file using \fBPEM_read_bio_PUBKEY\fR\|(3) (or similar function). +.PP +Ed25519 and Ed448 can be tested with the \fBopenssl\-speed\fR\|(1) application +since version 1.1.1. +Valid algorithm names are \fBed25519\fR, \fBed448\fR and \fBeddsa\fR. If \fBeddsa\fR is +specified, then both Ed25519 and Ed448 are benchmarked. +.PP +Since Ed25519ctx is not included in FIPS 186\-5, it is not present +in the FIPS provider. +.SH EXAMPLES +.IX Header "EXAMPLES" +To sign a message using an ED25519 EVP_PKEY structure: +.PP +.Vb 5 +\& void do_sign(EVP_PKEY *ed_key, unsigned char *msg, size_t msg_len) +\& { +\& size_t sig_len; +\& unsigned char *sig = NULL; +\& EVP_MD_CTX *md_ctx = EVP_MD_CTX_new(); +\& +\& const OSSL_PARAM params[] = { +\& OSSL_PARAM_utf8_string ("instance", "Ed25519ctx", 10), +\& OSSL_PARAM_octet_string("context\-string", (unsigned char *)"A protocol defined context string", 33), +\& OSSL_PARAM_END +\& }; +\& +\& /* The input "params" is not needed if default options are acceptable. +\& Use NULL in place of "params" in that case. */ +\& EVP_DigestSignInit_ex(md_ctx, NULL, NULL, NULL, NULL, ed_key, params); +\& /* Calculate the required size for the signature by passing a NULL buffer. */ +\& EVP_DigestSign(md_ctx, NULL, &sig_len, msg, msg_len); +\& sig = OPENSSL_zalloc(sig_len); +\& +\& EVP_DigestSign(md_ctx, sig, &sig_len, msg, msg_len); +\& ... +\& OPENSSL_free(sig); +\& EVP_MD_CTX_free(md_ctx); +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY\-X25519\fR\|(7) +\&\fBprovider\-signature\fR\|(7), +\&\fBEVP_DigestSignInit\fR\|(3), +\&\fBEVP_DigestVerifyInit\fR\|(3), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_SIGNATURE-HMAC.7 b/static/netbsd/man7/EVP_SIGNATURE-HMAC.7 new file mode 100644 index 00000000..957f994b --- /dev/null +++ b/static/netbsd/man7/EVP_SIGNATURE-HMAC.7 @@ -0,0 +1,110 @@ +.\" $NetBSD: EVP_SIGNATURE-HMAC.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_SIGNATURE-HMAC 7" +.TH EVP_SIGNATURE-HMAC 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_SIGNATURE\-HMAC, EVP_SIGNATURE\-Siphash, EVP_SIGNATURE\-Poly1305, +EVP_SIGNATURE\-CMAC +\&\- The legacy EVP_PKEY MAC signature implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The algorithms described here have legacy support for creating MACs using +\&\fBEVP_DigestSignInit\fR\|(3) and related functions. This is not the preferred way of +creating MACs. Instead you should use the newer \fBEVP_MAC_init\fR\|(3) functions. +This mechanism is provided for backwards compatibility with older versions of +OpenSSL. +.PP +The same signature parameters can be set using \fBEVP_PKEY_CTX_set_params()\fR as can +be set via \fBEVP_MAC_CTX_set_params()\fR for the underlying EVP_MAC. See +\&\fBEVP_MAC\-HMAC\fR\|(7), \fBEVP_MAC\-Siphash\fR\|(7), \fBEVP_MAC\-Poly1305\fR\|(7) and +\&\fBEVP_MAC\-CMAC\fR\|(7) for details. +.PP +.Vb 3 +\& See L, L, L or +\& L for details about parameters that are supported during the +\& creation of an EVP_PKEY. +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MAC_init\fR\|(3), +\&\fBEVP_DigestSignInit\fR\|(3), +\&\fBEVP_PKEY\-HMAC\fR\|(7), +\&\fBEVP_PKEY\-Siphash\fR\|(7), +\&\fBEVP_PKEY\-Poly1305\fR\|(7), +\&\fBEVP_PKEY\-CMAC\fR\|(7), +\&\fBEVP_MAC\-HMAC\fR\|(7), +\&\fBEVP_MAC\-Siphash\fR\|(7), +\&\fBEVP_MAC\-Poly1305\fR\|(7), +\&\fBEVP_MAC\-CMAC\fR\|(7), +\&\fBprovider\-signature\fR\|(7), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_SIGNATURE-ML-DSA.7 b/static/netbsd/man7/EVP_SIGNATURE-ML-DSA.7 new file mode 100644 index 00000000..a9ad7d4e --- /dev/null +++ b/static/netbsd/man7/EVP_SIGNATURE-ML-DSA.7 @@ -0,0 +1,185 @@ +.\" $NetBSD: EVP_SIGNATURE-ML-DSA.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_SIGNATURE-ML-DSA 7" +.TH EVP_SIGNATURE-ML-DSA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_SIGNATURE\-ML\-DSA, +EVP_SIGNATURE\-ML\-DSA\-44, EVP_SIGNATURE\-ML\-DSA\-65, EVP_SIGNATURE\-ML\-DSA\-87 +\&\- The EVP_PKEY ML\-DSA signature implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBML\-DSA\-44\fR, \fBML\-DSA\-65\fR and \fBML\-DSA\-87\fR EVP_PKEY implementations +support key generation, and one\-shot sign and verify using the ML\-DSA +signature schemes described in FIPS 204 . +.PP +The different algorithms names correspond to the parameter sets defined in +FIPS 204 Section 4 Table 1. +(The signatures range in size from ~2.5K to ~4.5K depending on the type chosen). +There are 3 different security categories also depending on the type. +.PP +\&\fBEVP_SIGNATURE_fetch\fR\|(3) can be used to explicitly fetch one of the 3 +algorithms which can then be used with \fBEVP_PKEY_sign_message_init\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify_message_init\fR\|(3), and +\&\fBEVP_PKEY_verify\fR\|(3) to perform one\-shot message signing or signature verification. +.PP +The normal signing process (called Pure ML\-DSA Signature Generation) +encodes the message internally as 0x00 || len(ctx) || ctx || message. +where \fBctx\fR is some optional value of size 0x00..0xFF. This process is +defined in FIPS 204 Algorithm 2 +step 10 and Algorithm 3 step 5. +OpenSSL also allows the message to not be encoded which is required for +testing. OpenSSL does not support Pre Hash ML\-DSA Signature Generation, but this +may be done by the user by doing Pre hash encoding externally and then choosing +the option to not encode the message. +.SS "ML\-DSA Signature Parameters" +.IX Subsection "ML-DSA Signature Parameters" +The following parameter can be used for both signing and verification. +it may be set by passing an OSSL_PARAM array to \fBEVP_PKEY_sign_message_init\fR\|(3) +or \fBEVP_PKEY_verify_message_init\fR\|(3) +.IP """context\-string"" (\fBOSSL_SIGNATURE_PARAM_CONTEXT_STRING\fR) " 4 +.IX Item """context-string"" (OSSL_SIGNATURE_PARAM_CONTEXT_STRING) " +A string of octets with length at most 255. By default it is the empty string. +.PP +The following parameters can be used when signing: +They can be set by passing an OSSL_PARAM array to \fBEVP_PKEY_sign_init_ex2\fR\|(3). +.IP """message\-encoding"" (\fBOSSL_SIGNATURE_PARAM_MESSAGE_ENCODING\fR) " 4 +.IX Item """message-encoding"" (OSSL_SIGNATURE_PARAM_MESSAGE_ENCODING) " +The default value of 1 uses \*(AqPure ML\-DSA Signature Generation\*(Aq as described +above. Setting it to 0 does not encode the message, which is used for testing. +The message encoding steps are defined in +FIPS 204 Algorithm 2 step 10 and +Algorithm 3 step 5. +.IP """test\-entropy"" (\fBOSSL_SIGNATURE_PARAM_TEST_ENTROPY\fR) " 4 +.IX Item """test-entropy"" (OSSL_SIGNATURE_PARAM_TEST_ENTROPY) " +Used for testing to pass an optional deterministic per message random value. +If set the size must be 32 bytes. +.IP """deterministic"" (\fBOSSL_SIGNATURE_PARAM_DETERMINISTIC\fR) " 4 +.IX Item """deterministic"" (OSSL_SIGNATURE_PARAM_DETERMINISTIC) " +The default value of 0 causes the per message randomness to be randomly +generated using a DRBG. Setting this to 1 causes the per message randomness +to be set to 32 bytes of zeros. This value is ignored if "test\-entropy" is set. +.IP """mu"" (\fBOSSL_SIGNATURE_PARAM_MU\fR) " 4 +.IX Item """mu"" (OSSL_SIGNATURE_PARAM_MU) " +The default value of 0 causes sign and verify operations to process a raw message. +Setting this to 1 causes those operations to assume the input is the \f(CW\*(C`mu\*(C'\fR value +from FIPS 204 Algorithm 7 step 6 and +Algorithm 8 step 7. +.Sp +Note that the message encoding steps from +FIPS 204 Algorithm 2 step 10 and +Algorithm 3 step 5 are omitted when this setting is 1. +.PP +See \fBEVP_PKEY\-ML\-DSA\fR\|(7) for information related to \fBML\-DSA\fR keys. +.SH NOTES +.IX Header "NOTES" +For backwards compatibility reasons \fBEVP_DigestSignInit_ex()\fR, \fBEVP_DigestSign()\fR, +\&\fBEVP_DigestVerifyInit_ex()\fR and \fBEVP_DigestVerify()\fR may also be used, but the digest +passed in \fImdname\fR must be NULL. +.SH EXAMPLES +.IX Header "EXAMPLES" +To sign a message using an ML\-DSA EVP_PKEY structure: +.PP +.Vb 10 +\& void do_sign(EVP_PKEY *key, unsigned char *msg, size_t msg_len) +\& { +\& size_t sig_len; +\& unsigned char *sig = NULL; +\& const OSSL_PARAM params[] = { +\& OSSL_PARAM_octet_string("context\-string", (unsigned char *)"A context string", 16), +\& OSSL_PARAM_END +\& }; +\& EVP_PKEY_CTX *sctx = EVP_PKEY_CTX_new_from_pkey(NULL, pkey, NULL); +\& EVP_SIGNATURE *sig_alg = EVP_SIGNATURE_fetch(NULL, "ML\-DSA\-65", NULL); +\& +\& EVP_PKEY_sign_message_init(sctx, sig_alg, params); +\& /* Calculate the required size for the signature by passing a NULL buffer. */ +\& EVP_PKEY_sign(sctx, NULL, &sig_len, msg, msg_len); +\& sig = OPENSSL_zalloc(sig_len); +\& EVP_PKEY_sign(sctx, sig, &sig_len, msg, msg_len); +\& ... +\& OPENSSL_free(sig); +\& EVP_SIGNATURE_free(sig_alg); +\& EVP_PKEY_CTX_free(sctx); +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY\-ML\-DSA\fR\|(7) +\&\fBprovider\-signature\fR\|(7), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +FIPS 204 +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2025\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_SIGNATURE-RSA.7 b/static/netbsd/man7/EVP_SIGNATURE-RSA.7 new file mode 100644 index 00000000..29bfef0f --- /dev/null +++ b/static/netbsd/man7/EVP_SIGNATURE-RSA.7 @@ -0,0 +1,239 @@ +.\" $NetBSD: EVP_SIGNATURE-RSA.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_SIGNATURE-RSA 7" +.TH EVP_SIGNATURE-RSA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_SIGNATURE\-RSA +\&\- The EVP_PKEY RSA signature implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing RSA signatures. +See \fBEVP_PKEY\-RSA\fR\|(7) for information related to RSA keys. +.SS "Algorithm Names" +.IX Subsection "Algorithm Names" +In this list, names are grouped together to signify that they are the same +algorithm having multiple names. This also includes the OID in canonical +decimal form (which means that they are possible to fetch if the caller has a +mere OID which came out in this form after a call to \fBOBJ_obj2txt\fR\|(3)). +.IP """RSA"", ""rsaEncryption"", ""1.2.840.113549.1.1.1""" 4 +.IX Item """RSA"", ""rsaEncryption"", ""1.2.840.113549.1.1.1""" +The base signature algorithm, supported explicitly fetched with +\&\fBEVP_PKEY_sign_init_ex2\fR\|(3), and implicitly fetched (through +RSA keys) with \fBEVP_DigestSignInit\fR\|(3) and +\&\fBEVP_DigestVerifyInit\fR\|(3). +.Sp +It can\*(Aqt be used with \fBEVP_PKEY_sign_message_init\fR\|(3) +.IP """RSA\-RIPEMD160"", ""ripemd160WithRSA"", ""1.3.36.3.3.1.2""" 4 +.IX Item """RSA-RIPEMD160"", ""ripemd160WithRSA"", ""1.3.36.3.3.1.2""" +.PD 0 +.IP """RSA\-SHA2\-256"", ""RSA\-SHA256"", ""sha256WithRSAEncryption"", ""1.2.840.113549.1.1.11""" 4 +.IX Item """RSA-SHA2-256"", ""RSA-SHA256"", ""sha256WithRSAEncryption"", ""1.2.840.113549.1.1.11""" +.IP """RSA\-SHA2\-384"", ""RSA\-SHA384"", ""sha384WithRSAEncryption"", ""1.2.840.113549.1.1.12""" 4 +.IX Item """RSA-SHA2-384"", ""RSA-SHA384"", ""sha384WithRSAEncryption"", ""1.2.840.113549.1.1.12""" +.IP """RSA\-SHA2\-512"", ""RSA\-SHA512"", ""sha512WithRSAEncryption"", ""1.2.840.113549.1.1.13""" 4 +.IX Item """RSA-SHA2-512"", ""RSA-SHA512"", ""sha512WithRSAEncryption"", ""1.2.840.113549.1.1.13""" +.IP """RSA\-SHA2\-224"", ""RSA\-SHA224"", ""sha224WithRSAEncryption"", ""1.2.840.113549.1.1.14""" 4 +.IX Item """RSA-SHA2-224"", ""RSA-SHA224"", ""sha224WithRSAEncryption"", ""1.2.840.113549.1.1.14""" +.IP """RSA\-SHA2\-512/224"", ""RSA\-SHA512\-224"", ""sha512\-224WithRSAEncryption"", ""1.2.840.113549.1.1.15""" 4 +.IX Item """RSA-SHA2-512/224"", ""RSA-SHA512-224"", ""sha512-224WithRSAEncryption"", ""1.2.840.113549.1.1.15""" +.IP """RSA\-SHA2\-512/256"", ""RSA\-SHA512\-256"", ""sha512\-256WithRSAEncryption"", ""1.2.840.113549.1.1.16""" 4 +.IX Item """RSA-SHA2-512/256"", ""RSA-SHA512-256"", ""sha512-256WithRSAEncryption"", ""1.2.840.113549.1.1.16""" +.IP """RSA\-SHA3\-224"", ""id\-rsassa\-pkcs1\-v1_5\-with\-sha3\-224"", ""2.16.840.1.101.3.4.3.13""" 4 +.IX Item """RSA-SHA3-224"", ""id-rsassa-pkcs1-v1_5-with-sha3-224"", ""2.16.840.1.101.3.4.3.13""" +.IP """RSA\-SHA3\-256"", ""id\-rsassa\-pkcs1\-v1_5\-with\-sha3\-256"", ""2.16.840.1.101.3.4.3.14""" 4 +.IX Item """RSA-SHA3-256"", ""id-rsassa-pkcs1-v1_5-with-sha3-256"", ""2.16.840.1.101.3.4.3.14""" +.IP """RSA\-SHA3\-384"", ""id\-rsassa\-pkcs1\-v1_5\-with\-sha3\-384"", ""2.16.840.1.101.3.4.3.15""" 4 +.IX Item """RSA-SHA3-384"", ""id-rsassa-pkcs1-v1_5-with-sha3-384"", ""2.16.840.1.101.3.4.3.15""" +.IP """RSA\-SHA3\-512"", ""id\-rsassa\-pkcs1\-v1_5\-with\-sha3\-512"", ""2.16.840.1.101.3.4.3.16""" 4 +.IX Item """RSA-SHA3-512"", ""id-rsassa-pkcs1-v1_5-with-sha3-512"", ""2.16.840.1.101.3.4.3.16""" +.IP """RSA\-SM3"", ""sm3WithRSAEncryption"", ""1.2.156.10197.1.504""" 4 +.IX Item """RSA-SM3"", ""sm3WithRSAEncryption"", ""1.2.156.10197.1.504""" +.PD +PKCS#1 v1.5 RSA signature schemes with diverse message digest algorithms. They +are all supported explicitly fetched with \fBEVP_PKEY_sign_init_ex2\fR\|(3) and +\&\fBEVP_PKEY_sign_message_init\fR\|(3). +They are all pre\-set to use the pad mode "pkcs1". This cannot be changed. +.SS "Signature Parameters" +.IX Subsection "Signature Parameters" +The following signature parameters can be set using \fBEVP_PKEY_CTX_set_params()\fR. +This may be called after \fBEVP_PKEY_sign_init()\fR or \fBEVP_PKEY_verify_init()\fR, +and before calling \fBEVP_PKEY_sign()\fR or \fBEVP_PKEY_verify()\fR. They may also be set +using \fBEVP_PKEY_sign_init_ex()\fR or \fBEVP_PKEY_verify_init_ex()\fR. +.IP """digest"" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_SIGNATURE_PARAM_DIGEST) " +.PD 0 +.IP """properties"" (\fBOSSL_SIGNATURE_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_SIGNATURE_PARAM_PROPERTIES) " +.PD +These are not supported with the RSA signature schemes that already include a +message digest algorithm, See "Algorithm Names" above. +.Sp +These common parameters are described in \fBprovider\-signature\fR\|(7). +.IP """pad\-mode"" (\fBOSSL_SIGNATURE_PARAM_PAD_MODE\fR) " 4 +.IX Item """pad-mode"" (OSSL_SIGNATURE_PARAM_PAD_MODE) " +The type of padding to be used. Its value can be one of the following: +.RS 4 +.IP """none"" (\fBOSSL_PKEY_RSA_PAD_MODE_NONE\fR)" 4 +.IX Item """none"" (OSSL_PKEY_RSA_PAD_MODE_NONE)" +.PD 0 +.IP """pkcs1"" (\fBOSSL_PKEY_RSA_PAD_MODE_PKCSV15\fR)" 4 +.IX Item """pkcs1"" (OSSL_PKEY_RSA_PAD_MODE_PKCSV15)" +.IP """x931"" (\fBOSSL_PKEY_RSA_PAD_MODE_X931\fR)" 4 +.IX Item """x931"" (OSSL_PKEY_RSA_PAD_MODE_X931)" +.PD +This padding mode is no longer supported by the FIPS provider for signature +generation, but may be used for signature verification for legacy use cases. +(This is a FIPS 140\-3 requirement) +.IP """pss"" (\fBOSSL_PKEY_RSA_PAD_MODE_PSS\fR)" 4 +.IX Item """pss"" (OSSL_PKEY_RSA_PAD_MODE_PSS)" +.RE +.RS 4 +.RE +.IP """mgf1\-digest"" (\fBOSSL_SIGNATURE_PARAM_MGF1_DIGEST\fR) " 4 +.IX Item """mgf1-digest"" (OSSL_SIGNATURE_PARAM_MGF1_DIGEST) " +The digest algorithm name to use for the maskGenAlgorithm used by "pss" mode. +.IP """mgf1\-properties"" (\fBOSSL_SIGNATURE_PARAM_MGF1_PROPERTIES\fR) " 4 +.IX Item """mgf1-properties"" (OSSL_SIGNATURE_PARAM_MGF1_PROPERTIES) " +Sets the name of the property query associated with the "mgf1\-digest" algorithm. +NULL is used if this optional value is not set. +.IP """saltlen"" (\fBOSSL_SIGNATURE_PARAM_PSS_SALTLEN\fR) or " 4 +.IX Item """saltlen"" (OSSL_SIGNATURE_PARAM_PSS_SALTLEN) or " +The "pss" mode minimum salt length. The value can either be an integer, +a string value representing a number or one of the following string values: +.RS 4 +.IP """digest"" (\fBOSSL_PKEY_RSA_PSS_SALT_LEN_DIGEST\fR)" 4 +.IX Item """digest"" (OSSL_PKEY_RSA_PSS_SALT_LEN_DIGEST)" +Use the same length as the digest size. +.IP """max"" (\fBOSSL_PKEY_RSA_PSS_SALT_LEN_MAX\fR)" 4 +.IX Item """max"" (OSSL_PKEY_RSA_PSS_SALT_LEN_MAX)" +Use the maximum salt length. +.IP """auto"" (\fBOSSL_PKEY_RSA_PSS_SALT_LEN_AUTO\fR)" 4 +.IX Item """auto"" (OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO)" +Auto detect the salt length. +.IP """auto\-digestmax"" (\fBOSSL_PKEY_RSA_PSS_SALT_LEN_AUTO_DIGEST_MAX\fR)" 4 +.IX Item """auto-digestmax"" (OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO_DIGEST_MAX)" +Auto detect the salt length when verifying. Maximize the salt length up to the +digest size when signing to comply with FIPS 186\-4 section 5.5. +.RE +.RS 4 +.RE +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """key\-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK) " +.PD 0 +.IP """digest\-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_DIGEST_CHECK\fR) " 4 +.IX Item """digest-check"" (OSSL_SIGNATURE_PARAM_FIPS_DIGEST_CHECK) " +.IP """sign\-x931\-pad\-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_SIGN_X931_PAD_CHECK\fR) " 4 +.IX Item """sign-x931-pad-check"" (OSSL_SIGNATURE_PARAM_FIPS_SIGN_X931_PAD_CHECK) " +.PD +These parameters are described in \fBprovider\-signature\fR\|(7). +.IP """rsa\-pss\-saltlen\-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_RSA_PSS_SALTLEN_CHECK\fR) " 4 +.IX Item """rsa-pss-saltlen-check"" (OSSL_SIGNATURE_PARAM_FIPS_RSA_PSS_SALTLEN_CHECK) " +The default value of 1 causes an error during signature generation or +verification if salt length (\fBOSSL_SIGNATURE_PARAM_PSS_SALTLEN\fR) is not between +zero and the output block size of the digest function (inclusive). +Setting this to zero will ignore the error and set the approved "fips\-indicator" +to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.PP +The following signature parameters can be retrieved using +\&\fBEVP_PKEY_CTX_get_params()\fR. +.IP """algorithm\-id"" (\fBOSSL_SIGNATURE_PARAM_ALGORITHM_ID\fR) " 4 +.IX Item """algorithm-id"" (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) " +.PD 0 +.IP """fips\-indicator"" (\fBOSSL_SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR) " +.IP """verify\-message"" (\fBOSSL_SIGNATURE_PARAM_FIPS_VERIFY_MESSAGE\fR " 4 +.IX Item """verify-message"" (OSSL_SIGNATURE_PARAM_FIPS_VERIFY_MESSAGE " +.PD +These common parameter are described in \fBprovider\-signature\fR\|(7). +.IP """digest"" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_SIGNATURE_PARAM_DIGEST) " +.PD 0 +.IP """pad\-mode"" (\fBOSSL_SIGNATURE_PARAM_PAD_MODE\fR) " 4 +.IX Item """pad-mode"" (OSSL_SIGNATURE_PARAM_PAD_MODE) " +.IP """mgf1\-digest"" (\fBOSSL_SIGNATURE_PARAM_MGF1_DIGEST\fR) " 4 +.IX Item """mgf1-digest"" (OSSL_SIGNATURE_PARAM_MGF1_DIGEST) " +.IP """saltlen"" (\fBOSSL_SIGNATURE_PARAM_PSS_SALTLEN\fR) or " 4 +.IX Item """saltlen"" (OSSL_SIGNATURE_PARAM_PSS_SALTLEN) or " +.PD +These parameters are as described above. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set_params\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBprovider\-signature\fR\|(7), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/EVP_SIGNATURE-SLH-DSA.7 b/static/netbsd/man7/EVP_SIGNATURE-SLH-DSA.7 new file mode 100644 index 00000000..d9b9b952 --- /dev/null +++ b/static/netbsd/man7/EVP_SIGNATURE-SLH-DSA.7 @@ -0,0 +1,181 @@ +.\" $NetBSD: EVP_SIGNATURE-SLH-DSA.7,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_SIGNATURE-SLH-DSA 7" +.TH EVP_SIGNATURE-SLH-DSA 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_SIGNATURE\-SLH\-DSA, +EVP_SIGNATURE\-SLH\-DSA\-SHA2\-128s, EVP_SIGNATURE\-SLH\-DSA\-SHA2\-128f, +EVP_SIGNATURE\-SLH\-DSA\-SHA2\-192s, EVP_SIGNATURE\-SLH\-DSA\-SHA2\-192f, +EVP_SIGNATURE\-SLH\-DSA\-SHA2\-256s, EVP_SIGNATURE\-SLH\-DSA\-SHA2\-256f, +EVP_SIGNATURE\-SLH\-DSA\-SHAKE\-128s, EVP_SIGNATURE\-SLH\-DSA\-SHAKE\-128f, +EVP_SIGNATURE\-SLH\-DSA\-SHAKE\-192s, EVP_SIGNATURE\-SLH\-DSA\-SHAKE\-192f, +EVP_SIGNATURE\-SLH\-DSA\-SHAKE\-256s, EVP_SIGNATURE\-SLH\-DSA\-SHAKE\-256f +\&\- The EVP_PKEY SLH\-DSA signature implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBSLH\-DSA\-SHA2\-128s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHA2\-128f\fR, +\&\fBSLH\-DSA\-SHA2\-192s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHA2\-192f\fR, +\&\fBSLH\-DSA\-SHA2\-256s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHA2\-256f\fR, +\&\fBSLH\-DSA\-SHAKE\-128s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHAKE\-128f\fR, +\&\fBSLH\-DSA\-SHAKE\-192s\fR, \fBEVP_PKEY\-SLH\-DSA\-SHAKE\-192f\fR, +\&\fBSLH\-DSA\-SHAKE\-256s\fR and \fBEVP_PKEY\-SLH\-DSA\-SHAKE\-256f\fR EVP_PKEY implementations +supports key generation, one\-shot sign and verify using the SLH\-DSA +signature schemes described in FIPS 205. +.PP +The different algorithms names correspond to the parameter sets defined in +FIPS 205 Section 11 Table 2. +\&\f(CW\*(C`s\*(C'\fR types have smaller signature sizes, and the \f(CW\*(C`f\*(C'\fR variants are faster, +(The signatures range from ~8K to ~50K depending on the type chosen). There are +3 different security categories also depending on the type. +.PP +\&\fBEVP_SIGNATURE_fetch\fR\|(3) can be used to explicitly fetch one of the 12 +algorithms which can then be used with \fBEVP_PKEY_sign_message_init\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify_message_init\fR\|(3), and +\&\fBEVP_PKEY_verify\fR\|(3) to perform one\-shot message signing or verification. +.PP +The normal signing process (called Pure SLH\-DSA Signature Generation) +encodes the message internally as 0x00 || len(ctx) || ctx || message. +where \fBctx\fR is some optional value of size 0x00..0xFF. +OpenSSL also allows the message to not be encoded which is required for +testing. OpenSSL does not support Pre Hash SLH\-DSA Signature Generation, but this +may be done by the user by doing Pre hash encoding externally and then choosing +the option to not encode the message. +.SS "SLH\-DSA Signature Parameters" +.IX Subsection "SLH-DSA Signature Parameters" +The \f(CW\*(C`context\-string\*(C'\fR parameter, described below, can be used for both signing +and verification. +It may be set by passing an OSSL_PARAM array to \fBEVP_PKEY_sign_init_ex2\fR\|(3) or +\&\fBEVP_PKEY_verify_init_ex2\fR\|(3) +.IP """context\-string"" (\fBOSSL_SIGNATURE_PARAM_CONTEXT_STRING\fR) " 4 +.IX Item """context-string"" (OSSL_SIGNATURE_PARAM_CONTEXT_STRING) " +A string of octets with length at most 255. By default it is the empty string. +.PP +The following parameters can be used when signing: +They can be set by passing an OSSL_PARAM array to \fBEVP_PKEY_sign_init_ex2\fR\|(3). +.IP """message\-encoding"" (\fBOSSL_SIGNATURE_PARAM_MESSAGE_ENCODING\fR) " 4 +.IX Item """message-encoding"" (OSSL_SIGNATURE_PARAM_MESSAGE_ENCODING) " +The default value of 1 uses \*(AqPure SLH\-DSA Signature Generation\*(Aq as described +above. Setting it to 0 does not encode the message, which is used for testing, +but can also be used for \*(AqPre Hash SLH\-DSA Signature Generation\*(Aq. +.IP """test\-entropy"" (\fBOSSL_SIGNATURE_PARAM_TEST_ENTROPY " 4 +.IX Item """deterministic"" (OSSL_SIGNATURE_PARAM_DETERMINISTIC) " +The default value of 0 generates a random value (using a DRBG) this is used when +processing the message. Setting this to 1 causes the private key seed to be used +instead. This value is ignored if "test\-entropy" is set. +.PP +See \fBEVP_PKEY\-SLH\-DSA\fR\|(7) for information related to \fBSLH\-DSA\fR keys. +.SH NOTES +.IX Header "NOTES" +For backwards compatibility reasons \fBEVP_DigestSignInit_ex()\fR, \fBEVP_DigestSign()\fR, +\&\fBEVP_DigestVerifyInit_ex()\fR and \fBEVP_DigestVerify()\fR may also be used, but the digest +passed in \fImdname\fR must be NULL. +.SH EXAMPLES +.IX Header "EXAMPLES" +To sign a message using an SLH\-DSA EVP_PKEY structure: +.PP +.Vb 10 +\& void do_sign(EVP_PKEY *key, unsigned char *msg, size_t msg_len) +\& { +\& size_t sig_len; +\& unsigned char *sig = NULL; +\& const OSSL_PARAM params[] = { +\& OSSL_PARAM_octet_string("context\-string", (unsigned char *)"A context string", 33), +\& OSSL_PARAM_END +\& }; +\& EVP_PKEY_CTX *sctx = EVP_PKEY_CTX_new_from_pkey(NULL, pkey, NULL); +\& EVP_SIGNATURE *sig_alg = EVP_SIGNATURE_fetch(NULL, "SLH\-DSA\-SHA2\-128s", NULL); +\& +\& EVP_PKEY_sign_message_init(sctx, sig_alg, params); +\& /* Calculate the required size for the signature by passing a NULL buffer. */ +\& EVP_PKEY_sign(sctx, NULL, &sig_len, msg, msg_len); +\& sig = OPENSSL_zalloc(sig_len); +\& EVP_PKEY_sign(sctx, sig, &sig_len, msg, msg_len); +\& ... +\& OPENSSL_free(sig); +\& EVP_SIGNATURE_free(sig_alg); +\& EVP_PKEY_CTX_free(sctx); +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY\-SLH\-DSA\fR\|(7) +\&\fBprovider\-signature\fR\|(7), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/Ed25519.7 b/static/netbsd/man7/Ed25519.7 new file mode 100644 index 00000000..8543e9bb --- /dev/null +++ b/static/netbsd/man7/Ed25519.7 @@ -0,0 +1,225 @@ +.\" $NetBSD: Ed25519.7,v 1.3 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "ED25519 7" +.TH ED25519 7 "2020-03-22" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +Ed25519, +Ed448 +\&\- EVP_PKEY Ed25519 and Ed448 support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fBEd25519\fR and \fBEd448\fR \s-1EVP_PKEY\s0 implementation supports key generation, +one-shot digest sign and digest verify using PureEdDSA and \fBEd25519\fR or \fBEd448\fR +(see \s-1RFC8032\s0). It has associated private and public key formats compatible with +\&\s-1RFC 8410.\s0 +.PP +No additional parameters can be set during key generation, one-shot signing or +verification. In particular, because PureEdDSA is used, a digest must \fB\s-1NOT\s0\fR be +specified when signing or verifying. +.SH "NOTES" +.IX Header "NOTES" +The PureEdDSA algorithm does not support the streaming mechanism +of other signature algorithms using, for example, \fBEVP_DigestUpdate()\fR. +The message to sign or verify must be passed using the one-shot +\&\fBEVP_DigestSign()\fR and \fBEVP_DigestVerify()\fR functions. +.PP +When calling \fBEVP_DigestSignInit()\fR or \fBEVP_DigestVerifyInit()\fR, the +digest \fBtype\fR parameter \fB\s-1MUST\s0\fR be set to \fB\s-1NULL\s0\fR. +.PP +Applications wishing to sign certificates (or other structures such as +CRLs or certificate requests) using Ed25519 or Ed448 can either use \fBX509_sign()\fR +or \fBX509_sign_ctx()\fR in the usual way. +.PP +A context for the \fBEd25519\fR algorithm can be obtained by calling: +.PP +.Vb 1 +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED25519, NULL); +.Ve +.PP +For the \fBEd448\fR algorithm a context can be obtained by calling: +.PP +.Vb 1 +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED448, NULL); +.Ve +.PP +Ed25519 or Ed448 private keys can be set directly using +\&\fBEVP_PKEY_new_raw_private_key\fR\|(3) or loaded from a PKCS#8 private key file +using \fBPEM_read_bio_PrivateKey\fR\|(3) (or similar function). Completely new keys +can also be generated (see the example below). Setting a private key also sets +the associated public key. +.PP +Ed25519 or Ed448 public keys can be set directly using +\&\fBEVP_PKEY_new_raw_public_key\fR\|(3) or loaded from a SubjectPublicKeyInfo +structure in a \s-1PEM\s0 file using \fBPEM_read_bio_PUBKEY\fR\|(3) (or similar function). +.PP +Ed25519 and Ed448 can be tested within \fBspeed\fR\|(1) application since version 1.1.1. +Valid algorithm names are \fBed25519\fR, \fBed448\fR and \fBeddsa\fR. If \fBeddsa\fR is +specified, then both Ed25519 and Ed448 are benchmarked. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +This example generates an \fB\s-1ED25519\s0\fR private key and writes it to standard +output in \s-1PEM\s0 format: +.PP +.Vb 9 +\& #include +\& #include +\& ... +\& EVP_PKEY *pkey = NULL; +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED25519, NULL); +\& EVP_PKEY_keygen_init(pctx); +\& EVP_PKEY_keygen(pctx, &pkey); +\& EVP_PKEY_CTX_free(pctx); +\& PEM_write_PrivateKey(stdout, pkey, NULL, NULL, 0, NULL, NULL); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_keygen\fR\|(3), +\&\fBEVP_DigestSignInit\fR\|(3), +\&\fBEVP_DigestVerifyInit\fR\|(3), +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man7/OSSL_PROVIDER-FIPS.7 b/static/netbsd/man7/OSSL_PROVIDER-FIPS.7 new file mode 100644 index 00000000..f01e04d9 --- /dev/null +++ b/static/netbsd/man7/OSSL_PROVIDER-FIPS.7 @@ -0,0 +1,608 @@ +.\" $NetBSD: OSSL_PROVIDER-FIPS.7,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_PROVIDER-FIPS 7" +.TH OSSL_PROVIDER-FIPS 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_PROVIDER\-FIPS \- OpenSSL FIPS provider +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The OpenSSL FIPS provider is a special provider that conforms to the Federal +Information Processing Standards (FIPS) specified in FIPS 140\-3. This \*(Aqmodule\*(Aq +contains an approved set of cryptographic algorithms that is validated by an +accredited testing laboratory. +.SS Properties +.IX Subsection "Properties" +The implementations in this provider specifically have these properties +defined for approved algorithms: +.IP """provider=fips""" 4 +.IX Item """provider=fips""" +.PD 0 +.IP """fips=yes""" 4 +.IX Item """fips=yes""" +.PD +.PP +It may be used in a property query string with fetching functions such as +\&\fBEVP_MD_fetch\fR\|(3) or \fBEVP_CIPHER_fetch\fR\|(3), as well as with other +functions that take a property query string, such as +\&\fBEVP_PKEY_CTX_new_from_name\fR\|(3). +.PP +To be FIPS compliant, it is mandatory to include \f(CW\*(C`fips=yes\*(C'\fR as +part of all property queries. This ensures that only FIPS approved +implementations are used for cryptographic operations. The \f(CW\*(C`fips=yes\*(C'\fR +query may also include other non\-crypto support operations that +are not in the FIPS provider, such as asymmetric key encoders, see +"Asymmetric Key Management" in \fBOSSL_PROVIDER\-default\fR\|(7). +.PP +It is not mandatory to include \f(CW\*(C`provider=fips\*(C'\fR as part of your property +query. Including \f(CW\*(C`provider=fips\*(C'\fR in your property query guarantees +that the OpenSSL FIPS provider is used for cryptographic operations +rather than other FIPS capable providers. +.SS "Approved algorithms" +.IX Subsection "Approved algorithms" +Algorithms that are fetched using "fips=yes" may still be unapproved if certain +conditions are not met. See "FIPS indicators" in \fBfips_module\fR\|(7) for additional +information. +.SS "Provider parameters" +.IX Subsection "Provider parameters" +See "Provider parameters" in \fBprovider\-base\fR\|(7) for a list of base parameters. +The OpenSSL FIPS provider also handles FIPS indicator related parameters as +specified by "FIPS indicator options" in \fBfips_config\fR\|(5). +.SH "OPERATIONS AND ALGORITHMS" +.IX Header "OPERATIONS AND ALGORITHMS" +The OpenSSL FIPS provider supports these operations and algorithms: +.SS "Hashing Algorithms / Message Digests" +.IX Subsection "Hashing Algorithms / Message Digests" +.IP "SHA1, see \fBEVP_MD\-SHA1\fR\|(7)" 4 +.IX Item "SHA1, see EVP_MD-SHA1" +.PD 0 +.IP "SHA2, see \fBEVP_MD\-SHA2\fR\|(7)" 4 +.IX Item "SHA2, see EVP_MD-SHA2" +.IP "SHA3, see \fBEVP_MD\-SHA3\fR\|(7)" 4 +.IX Item "SHA3, see EVP_MD-SHA3" +.IP "KECCAK\-KMAC, see \fBEVP_MD\-KECCAK\-KMAC\fR\|(7)" 4 +.IX Item "KECCAK-KMAC, see EVP_MD-KECCAK-KMAC" +.IP "SHAKE, see \fBEVP_MD\-SHAKE\fR\|(7)" 4 +.IX Item "SHAKE, see EVP_MD-SHAKE" +.PD +.SS "Symmetric Ciphers" +.IX Subsection "Symmetric Ciphers" +.IP "AES, see \fBEVP_CIPHER\-AES\fR\|(7)" 4 +.IX Item "AES, see EVP_CIPHER-AES" +.PD 0 +.IP "3DES, see \fBEVP_CIPHER\-DES\fR\|(7)" 4 +.IX Item "3DES, see EVP_CIPHER-DES" +.PD +.SS "Message Authentication Code (MAC)" +.IX Subsection "Message Authentication Code (MAC)" +.IP "CMAC, see \fBEVP_MAC\-CMAC\fR\|(7)" 4 +.IX Item "CMAC, see EVP_MAC-CMAC" +.PD 0 +.IP "GMAC, see \fBEVP_MAC\-GMAC\fR\|(7)" 4 +.IX Item "GMAC, see EVP_MAC-GMAC" +.IP "HMAC, see \fBEVP_MAC\-HMAC\fR\|(7)" 4 +.IX Item "HMAC, see EVP_MAC-HMAC" +.IP "KMAC, see \fBEVP_MAC\-KMAC\fR\|(7)" 4 +.IX Item "KMAC, see EVP_MAC-KMAC" +.PD +.SS "Key Derivation Function (KDF)" +.IX Subsection "Key Derivation Function (KDF)" +.IP "HKDF, see \fBEVP_KDF\-HKDF\fR\|(7)" 4 +.IX Item "HKDF, see EVP_KDF-HKDF" +.PD 0 +.IP "TLS13\-KDF, see \fBEVP_KDF\-TLS13_KDF\fR\|(7)" 4 +.IX Item "TLS13-KDF, see EVP_KDF-TLS13_KDF" +.IP "SSKDF, see \fBEVP_KDF\-SS\fR\|(7)" 4 +.IX Item "SSKDF, see EVP_KDF-SS" +.IP "PBKDF2, see \fBEVP_KDF\-PBKDF2\fR\|(7)" 4 +.IX Item "PBKDF2, see EVP_KDF-PBKDF2" +.IP "SSHKDF, see \fBEVP_KDF\-SSHKDF\fR\|(7)" 4 +.IX Item "SSHKDF, see EVP_KDF-SSHKDF" +.IP "TLS1\-PRF, see \fBEVP_KDF\-TLS1_PRF\fR\|(7)" 4 +.IX Item "TLS1-PRF, see EVP_KDF-TLS1_PRF" +.IP "KBKDF, see \fBEVP_KDF\-KB\fR\|(7)" 4 +.IX Item "KBKDF, see EVP_KDF-KB" +.IP "X942KDF\-ASN1, see \fBEVP_KDF\-X942\-ASN1\fR\|(7)" 4 +.IX Item "X942KDF-ASN1, see EVP_KDF-X942-ASN1" +.IP "X942KDF\-CONCAT, see \fBEVP_KDF\-X942\-CONCAT\fR\|(7)" 4 +.IX Item "X942KDF-CONCAT, see EVP_KDF-X942-CONCAT" +.IP "X963KDF, see \fBEVP_KDF\-X963\fR\|(7)" 4 +.IX Item "X963KDF, see EVP_KDF-X963" +.PD +.SS "Key Exchange" +.IX Subsection "Key Exchange" +.IP "DH, see \fBEVP_KEYEXCH\-DH\fR\|(7)" 4 +.IX Item "DH, see EVP_KEYEXCH-DH" +.PD 0 +.IP "ECDH, see \fBEVP_KEYEXCH\-ECDH\fR\|(7)" 4 +.IX Item "ECDH, see EVP_KEYEXCH-ECDH" +.IP "X25519, see \fBEVP_KEYEXCH\-X25519\fR\|(7)" 4 +.IX Item "X25519, see EVP_KEYEXCH-X25519" +.IP "X448, see \fBEVP_KEYEXCH\-X448\fR\|(7)" 4 +.IX Item "X448, see EVP_KEYEXCH-X448" +.IP "ML\-KEM, see \fBEVP_KEM\-ML\-KEM\fR\|(7)" 4 +.IX Item "ML-KEM, see EVP_KEM-ML-KEM" +.IP TLS1\-PRF 4 +.IX Item "TLS1-PRF" +.IP HKDF 4 +.IX Item "HKDF" +.PD +.SS "Asymmetric Signature" +.IX Subsection "Asymmetric Signature" +.IP "RSA, see \fBEVP_SIGNATURE\-RSA\fR\|(7)" 4 +.IX Item "RSA, see EVP_SIGNATURE-RSA" +The \fBX931\fR padding mode "OSSL_PKEY_RSA_PAD_MODE_X931" is no longer supported +for signature generation, but may be used for verification for legacy use cases. +(This is a FIPS 140\-3 requirement) +.IP "DSA, see \fBEVP_SIGNATURE\-DSA\fR\|(7)" 4 +.IX Item "DSA, see EVP_SIGNATURE-DSA" +.PD 0 +.IP "ED25519, see \fBEVP_SIGNATURE\-ED25519\fR\|(7)" 4 +.IX Item "ED25519, see EVP_SIGNATURE-ED25519" +.IP "ED448, see \fBEVP_SIGNATURE\-ED448\fR\|(7)" 4 +.IX Item "ED448, see EVP_SIGNATURE-ED448" +.IP "ECDSA, see \fBEVP_SIGNATURE\-ECDSA\fR\|(7)" 4 +.IX Item "ECDSA, see EVP_SIGNATURE-ECDSA" +.IP "ML\-DSA\-44, see \fBEVP_SIGNATURE\-ML\-DSA\fR\|(7)" 4 +.IX Item "ML-DSA-44, see EVP_SIGNATURE-ML-DSA" +.IP "ML\-DSA\-65, see \fBEVP_SIGNATURE\-ML\-DSA\fR\|(7)" 4 +.IX Item "ML-DSA-65, see EVP_SIGNATURE-ML-DSA" +.IP "ML\-DSA\-87, see \fBEVP_SIGNATURE\-ML\-DSA\fR\|(7)" 4 +.IX Item "ML-DSA-87, see EVP_SIGNATURE-ML-DSA" +.IP "SLH\-DSA, see \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA, see EVP_SIGNATURE-SLH-DSA" +.IP "HMAC, see \fBEVP_SIGNATURE\-HMAC\fR\|(7)" 4 +.IX Item "HMAC, see EVP_SIGNATURE-HMAC" +.IP "CMAC, see \fBEVP_SIGNATURE\-CMAC\fR\|(7)" 4 +.IX Item "CMAC, see EVP_SIGNATURE-CMAC" +.PD +.SS "Asymmetric Cipher" +.IX Subsection "Asymmetric Cipher" +.IP "RSA, see \fBEVP_ASYM_CIPHER\-RSA\fR\|(7)" 4 +.IX Item "RSA, see EVP_ASYM_CIPHER-RSA" +.SS "Asymmetric Key Encapsulation" +.IX Subsection "Asymmetric Key Encapsulation" +.IP "RSA, see \fBEVP_KEM\-RSA\fR\|(7)" 4 +.IX Item "RSA, see EVP_KEM-RSA" +.SS "Asymmetric Key Management" +.IX Subsection "Asymmetric Key Management" +.IP "DH, see \fBEVP_KEYMGMT\-DH\fR\|(7)" 4 +.IX Item "DH, see EVP_KEYMGMT-DH" +.PD 0 +.IP "DHX, see \fBEVP_KEYMGMT\-DHX\fR\|(7)" 4 +.IX Item "DHX, see EVP_KEYMGMT-DHX" +.IP "DSA, see \fBEVP_KEYMGMT\-DSA\fR\|(7)" 4 +.IX Item "DSA, see EVP_KEYMGMT-DSA" +.IP "RSA, see \fBEVP_KEYMGMT\-RSA\fR\|(7)" 4 +.IX Item "RSA, see EVP_KEYMGMT-RSA" +.IP RSA\-PSS 4 +.IX Item "RSA-PSS" +.IP "EC, see \fBEVP_KEYMGMT\-EC\fR\|(7)" 4 +.IX Item "EC, see EVP_KEYMGMT-EC" +.IP "ED25519, see \fBEVP_KEYMGMT\-ED25519\fR\|(7)" 4 +.IX Item "ED25519, see EVP_KEYMGMT-ED25519" +.IP "ED448, see \fBEVP_KEYMGMT\-ED448\fR\|(7)" 4 +.IX Item "ED448, see EVP_KEYMGMT-ED448" +.IP "X25519, see \fBEVP_KEYMGMT\-X25519\fR\|(7)" 4 +.IX Item "X25519, see EVP_KEYMGMT-X25519" +.PD +This is an unapproved algorithm. +The FIPS 140\-3 IG states that "Curves that are included in SP 800\-186 but not +included in SP 800\-56Arev3 are not approved for key agreement". +.IP "X448, see \fBEVP_KEYMGMT\-X448\fR\|(7)" 4 +.IX Item "X448, see EVP_KEYMGMT-X448" +This is an unapproved algorithm. +The FIPS 140\-3 IG states that "Curves that are included in SP 800\-186 but not" +included in SP 800\-56Arev3 are not approved for key agreement". +.IP TLS1\-PRF 4 +.IX Item "TLS1-PRF" +.PD 0 +.IP HKDF 4 +.IX Item "HKDF" +.IP "HMAC, see \fBEVP_KEYMGMT\-HMAC\fR\|(7)" 4 +.IX Item "HMAC, see EVP_KEYMGMT-HMAC" +.IP "CMAC, see \fBEVP_KEYMGMT\-CMAC\fR\|(7)" 4 +.IX Item "CMAC, see EVP_KEYMGMT-CMAC" +.IP "ML\-DSA\-44, see \fBEVP_KEYMGMT\-ML\-DSA\fR\|(7)" 4 +.IX Item "ML-DSA-44, see EVP_KEYMGMT-ML-DSA" +.IP "ML\-DSA\-65, see \fBEVP_KEYMGMT\-ML\-DSA\fR\|(7)" 4 +.IX Item "ML-DSA-65, see EVP_KEYMGMT-ML-DSA" +.IP "ML\-DSA\-87, see \fBEVP_KEYMGMT\-ML\-DSA\fR\|(7)" 4 +.IX Item "ML-DSA-87, see EVP_KEYMGMT-ML-DSA" +.IP "SLH\-DSA\-SHA2\-128s, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-128s, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-128f, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-128f, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-192s, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-192s, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-192f, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-192f, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-256s, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-256s, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-256f, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-256f, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-128s, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-128s, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-128f, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-128f, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-192s, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-192s, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-192f, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-192f, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-256s, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-256s, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-256f, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-256f, see EVP_KEYMGMT-SLH-DSA" +.PD +.SS "Random Number Generation" +.IX Subsection "Random Number Generation" +.IP "CRNG\-TEST, see \fBEVP_RAND\-CRNG\-TEST\fR\|(7)" 4 +.IX Item "CRNG-TEST, see EVP_RAND-CRNG-TEST" +.PD 0 +.IP "CTR\-DRBG, see \fBEVP_RAND\-CTR\-DRBG\fR\|(7)" 4 +.IX Item "CTR-DRBG, see EVP_RAND-CTR-DRBG" +.IP "HASH\-DRBG, see \fBEVP_RAND\-HASH\-DRBG\fR\|(7)" 4 +.IX Item "HASH-DRBG, see EVP_RAND-HASH-DRBG" +.IP "HMAC\-DRBG, see \fBEVP_RAND\-HMAC\-DRBG\fR\|(7)" 4 +.IX Item "HMAC-DRBG, see EVP_RAND-HMAC-DRBG" +.IP "TEST\-RAND, see \fBEVP_RAND\-TEST\-RAND\fR\|(7)" 4 +.IX Item "TEST-RAND, see EVP_RAND-TEST-RAND" +.PD +TEST\-RAND is an unapproved algorithm. +.SH "SELF TESTING" +.IX Header "SELF TESTING" +A requirement of FIPS modules is to run cryptographic algorithm self tests. +FIPS 140\-3 requires known answer tests to be run on startup as well as +conditional tests that run during cryptographic operations. +.PP +An optional callback mechanism is available to return information to the user using +\&\fBOSSL_SELF_TEST_set_callback\fR\|(3). +.PP +The parameters passed to the callback are described in \fBOSSL_SELF_TEST_new\fR\|(3) +.PP +The OpenSSL FIPS module uses the following mechanism to provide information +about the self tests as they run. +This is useful for debugging if a self test is failing. +The callback also allows forcing any self test to fail, in order to check that +it operates correctly on failure. +Note that all self tests run even if a self test failure occurs. +.PP +The FIPS module passes the following type(s) to \fBOSSL_SELF_TEST_onbegin()\fR. +.IP """Module_Integrity"" (\fBOSSL_SELF_TEST_TYPE_MODULE_INTEGRITY\fR)" 4 +.IX Item """Module_Integrity"" (OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY)" +Uses HMAC SHA256 on the module file to validate that the module has not been +modified. The integrity value is compared to a value written to a configuration +file during installation. +.IP """KAT_Integrity"" (\fBOSSL_SELF_TEST_TYPE_KAT_INTEGRITY\fR)" 4 +.IX Item """KAT_Integrity"" (OSSL_SELF_TEST_TYPE_KAT_INTEGRITY)" +Used during the Module Integrity test to perform a known answer test on +HMAC SHA256 prior to using it. +.IP """KAT_Cipher"" (\fBOSSL_SELF_TEST_TYPE_KAT_CIPHER\fR)" 4 +.IX Item """KAT_Cipher"" (OSSL_SELF_TEST_TYPE_KAT_CIPHER)" +Known answer test for a symmetric cipher. +.IP """KAT_AsymmetricCipher"" (\fBOSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER\fR)" 4 +.IX Item """KAT_AsymmetricCipher"" (OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER)" +Known answer test for a asymmetric cipher. +.IP """KAT_Digest"" (\fBOSSL_SELF_TEST_TYPE_KAT_DIGEST\fR)" 4 +.IX Item """KAT_Digest"" (OSSL_SELF_TEST_TYPE_KAT_DIGEST)" +Known answer test for a digest. +.IP """KAT_AsymmetricKeyGeneration"" (\fBOSSL_SELF_TEST_TYPE_KAT_ASYM_KEYGEN\fR)" 4 +.IX Item """KAT_AsymmetricKeyGeneration"" (OSSL_SELF_TEST_TYPE_KAT_ASYM_KEYGEN)" +Known answer test for asymmetric key generation. +.IP """KAT_Signature"" (\fBOSSL_SELF_TEST_TYPE_KAT_SIGNATURE\fR)" 4 +.IX Item """KAT_Signature"" (OSSL_SELF_TEST_TYPE_KAT_SIGNATURE)" +Known answer test for a signature. +.IP """PCT_Signature"" (\fBOSSL_SELF_TEST_TYPE_PCT_SIGNATURE\fR)" 4 +.IX Item """PCT_Signature"" (OSSL_SELF_TEST_TYPE_PCT_SIGNATURE)" +Pairwise Consistency check for a signature. +.IP """KAT_KDF"" (\fBOSSL_SELF_TEST_TYPE_KAT_KDF\fR)" 4 +.IX Item """KAT_KDF"" (OSSL_SELF_TEST_TYPE_KAT_KDF)" +Known answer test for a key derivation function. +.IP """KAT_KA"" (\fBOSSL_SELF_TEST_TYPE_KAT_KA\fR)" 4 +.IX Item """KAT_KA"" (OSSL_SELF_TEST_TYPE_KAT_KA)" +Known answer test for key agreement. +.IP """KAT_KEM"" (\fBOSSL_SELF_TEST_TYPE_KAT_KEM\fR)" 4 +.IX Item """KAT_KEM"" (OSSL_SELF_TEST_TYPE_KAT_KEM)" +Known answer test for key encapsulation. +.IP """DRBG"" (\fBOSSL_SELF_TEST_TYPE_DRBG\fR)" 4 +.IX Item """DRBG"" (OSSL_SELF_TEST_TYPE_DRBG)" +Known answer test for a Deterministic Random Bit Generator. +.IP """Conditional_PCT"" (\fBOSSL_SELF_TEST_TYPE_PCT\fR)" 4 +.IX Item """Conditional_PCT"" (OSSL_SELF_TEST_TYPE_PCT)" +Conditional test that is run during the generation of key pairs. +.IP """Import_PCT"" (\fBOSSL_SELF_TEST_TYPE_PCT_IMPORT\fR)" 4 +.IX Item """Import_PCT"" (OSSL_SELF_TEST_TYPE_PCT_IMPORT)" +Conditional test that is run during the import of key pairs. +.IP """Conditional_KAT"" (\fBOSSL_SELF_TEST_TYPE_PCT_KAT\fR)" 4 +.IX Item """Conditional_KAT"" (OSSL_SELF_TEST_TYPE_PCT_KAT)" +Conditional test run during generation that derive the public key from the +private key and checks that the public key matches. This is a SP 800\-56A requirement. +.IP """Continuous_RNG_Test"" (\fBOSSL_SELF_TEST_TYPE_CRNG\fR)" 4 +.IX Item """Continuous_RNG_Test"" (OSSL_SELF_TEST_TYPE_CRNG)" +Continuous random number generator test. +.IP """Install_Integrity"" (\fBOSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY\fR)" 4 +.IX Item """Install_Integrity"" (OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY)" +This is deprecated. The option is no longer used since FIPS 140\-3 requires +self tests to always run on startup. Previous FIPS 140\-2 validations allowed +the self tests to be run just once. +.PP +The FIPS module passes the following descriptions(s) to \fBOSSL_SELF_TEST_onbegin()\fR. +.IP """HMAC"" (\fBOSSL_SELF_TEST_DESC_INTEGRITY_HMAC\fR)" 4 +.IX Item """HMAC"" (OSSL_SELF_TEST_DESC_INTEGRITY_HMAC)" +"Module_Integrity" uses this. +.IP """RSA"" (\fBOSSL_SELF_TEST_DESC_PCT_RSA_PKCS1\fR)" 4 +.IX Item """RSA"" (OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1)" +.PD 0 +.IP """RSA"" (\fBOSSL_SELF_TEST_DESC_PCT_RSA\fR)" 4 +.IX Item """RSA"" (OSSL_SELF_TEST_DESC_PCT_RSA)" +.IP """ECDSA"" (\fBOSSL_SELF_TEST_DESC_PCT_ECDSA\fR)" 4 +.IX Item """ECDSA"" (OSSL_SELF_TEST_DESC_PCT_ECDSA)" +.IP """EDDSA"" (\fBOSSL_SELF_TEST_DESC_PCT_EDDSA\fR)" 4 +.IX Item """EDDSA"" (OSSL_SELF_TEST_DESC_PCT_EDDSA)" +.IP """DSA"" (\fBOSSL_SELF_TEST_DESC_PCT_DSA\fR)" 4 +.IX Item """DSA"" (OSSL_SELF_TEST_DESC_PCT_DSA)" +.IP """ML\-DSA"" (\fBOSSL_SELF_TEST_DESC_PCT_ML_DSA\fR)" 4 +.IX Item """ML-DSA"" (OSSL_SELF_TEST_DESC_PCT_ML_DSA)" +.IP """ML\-KEM"" (\fBOSSL_SELF_TEST_DESC_PCT_ML_KEM\fR)" 4 +.IX Item """ML-KEM"" (OSSL_SELF_TEST_DESC_PCT_ML_KEM)" +.IP """SLH\-DSA"" (\fBOSSL_SELF_TEST_DESC_PCT_SLH_DSA\fR)" 4 +.IX Item """SLH-DSA"" (OSSL_SELF_TEST_DESC_PCT_SLH_DSA)" +.PD +Key generation tests used with the "Pairwise_Consistency_Test" type. +.IP """RSA_Encrypt"" (\fBOSSL_SELF_TEST_DESC_ASYM_RSA_ENC\fR)" 4 +.IX Item """RSA_Encrypt"" (OSSL_SELF_TEST_DESC_ASYM_RSA_ENC)" +.PD 0 +.IP """RSA_Decrypt"" (\fBOSSL_SELF_TEST_DESC_ASYM_RSA_DEC\fR)" 4 +.IX Item """RSA_Decrypt"" (OSSL_SELF_TEST_DESC_ASYM_RSA_DEC)" +.PD +"KAT_AsymmetricCipher" uses this to indicate an encrypt or decrypt KAT. +.IP """ML\-DSA"" (\fBOSSL_SELF_TEST_DESC_KEYGEN_ML_DSA\fR)" 4 +.IX Item """ML-DSA"" (OSSL_SELF_TEST_DESC_KEYGEN_ML_DSA)" +.PD 0 +.IP """ML\-KEM"" (\fBOSSL_SELF_TEST_DESC_KEYGEN_ML_KEM\fR)" 4 +.IX Item """ML-KEM"" (OSSL_SELF_TEST_DESC_KEYGEN_ML_KEM)" +.IP """SLH\-DSA"" (\fBOSSL_SELF_TEST_DESC_KEYGEN_SLH_DSA\fR)" 4 +.IX Item """SLH-DSA"" (OSSL_SELF_TEST_DESC_KEYGEN_SLH_DSA)" +.PD +"KAT_AsymmetricKeyGeneration" uses this to indicate a key generation KAT. +.IP """AES_GCM"" (\fBOSSL_SELF_TEST_DESC_CIPHER_AES_GCM\fR)" 4 +.IX Item """AES_GCM"" (OSSL_SELF_TEST_DESC_CIPHER_AES_GCM)" +.PD 0 +.IP """AES_ECB_Decrypt"" (\fBOSSL_SELF_TEST_DESC_CIPHER_AES_ECB\fR)" 4 +.IX Item """AES_ECB_Decrypt"" (OSSL_SELF_TEST_DESC_CIPHER_AES_ECB)" +.IP """TDES"" (\fBOSSL_SELF_TEST_DESC_CIPHER_TDES\fR)" 4 +.IX Item """TDES"" (OSSL_SELF_TEST_DESC_CIPHER_TDES)" +.PD +Symmetric cipher tests used with the "KAT_Cipher" type. +.IP """SHA1"" (\fBOSSL_SELF_TEST_DESC_MD_SHA1\fR)" 4 +.IX Item """SHA1"" (OSSL_SELF_TEST_DESC_MD_SHA1)" +.PD 0 +.IP """SHA2"" (\fBOSSL_SELF_TEST_DESC_MD_SHA2\fR)" 4 +.IX Item """SHA2"" (OSSL_SELF_TEST_DESC_MD_SHA2)" +.IP """SHA3"" (\fBOSSL_SELF_TEST_DESC_MD_SHA3\fR)" 4 +.IX Item """SHA3"" (OSSL_SELF_TEST_DESC_MD_SHA3)" +.PD +Digest tests used with the "KAT_Digest" type. +.IP """DSA"" (\fBOSSL_SELF_TEST_DESC_SIGN_DSA\fR)" 4 +.IX Item """DSA"" (OSSL_SELF_TEST_DESC_SIGN_DSA)" +.PD 0 +.IP """RSA"" (\fBOSSL_SELF_TEST_DESC_SIGN_RSA\fR)" 4 +.IX Item """RSA"" (OSSL_SELF_TEST_DESC_SIGN_RSA)" +.IP """ECDSA"" (\fBOSSL_SELF_TEST_DESC_SIGN_ECDSA\fR)" 4 +.IX Item """ECDSA"" (OSSL_SELF_TEST_DESC_SIGN_ECDSA)" +.IP """EDDSA"" (\fBOSSL_SELF_TEST_DESC_SIGN_EDDSA\fR)" 4 +.IX Item """EDDSA"" (OSSL_SELF_TEST_DESC_SIGN_EDDSA)" +.IP """ML\-DSA"" (\fBOSSL_SELF_TEST_DESC_SIGN_ML_DSA\fR)" 4 +.IX Item """ML-DSA"" (OSSL_SELF_TEST_DESC_SIGN_ML_DSA)" +.IP """SLH\-DSA"" (\fBOSSL_SELF_TEST_DESC_SIGN_SLH_DSA\fR)" 4 +.IX Item """SLH-DSA"" (OSSL_SELF_TEST_DESC_SIGN_SLH_DSA)" +.PD +Signature tests used with the "KAT_Signature" type. +.IP """ECDH"" (\fBOSSL_SELF_TEST_DESC_KA_ECDH\fR)" 4 +.IX Item """ECDH"" (OSSL_SELF_TEST_DESC_KA_ECDH)" +.PD 0 +.IP """DH"" (\fBOSSL_SELF_TEST_DESC_KA_DH\fR)" 4 +.IX Item """DH"" (OSSL_SELF_TEST_DESC_KA_DH)" +.PD +Key agreement tests used with the "KAT_KA" type. +.IP """HKDF"" (\fBOSSL_SELF_TEST_DESC_KDF_HKDF\fR)" 4 +.IX Item """HKDF"" (OSSL_SELF_TEST_DESC_KDF_HKDF)" +.PD 0 +.IP """TLS13_KDF_EXTRACT"" (\fBOSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT\fR)" 4 +.IX Item """TLS13_KDF_EXTRACT"" (OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT)" +.IP """TLS13_KDF_EXPAND"" (\fBOSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND\fR)" 4 +.IX Item """TLS13_KDF_EXPAND"" (OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND)" +.IP """SSKDF"" (\fBOSSL_SELF_TEST_DESC_KDF_SSKDF\fR)" 4 +.IX Item """SSKDF"" (OSSL_SELF_TEST_DESC_KDF_SSKDF)" +.IP """X963KDF"" (\fBOSSL_SELF_TEST_DESC_KDF_X963KDF\fR)" 4 +.IX Item """X963KDF"" (OSSL_SELF_TEST_DESC_KDF_X963KDF)" +.IP """X942KDF"" (\fBOSSL_SELF_TEST_DESC_KDF_X942KDF\fR)" 4 +.IX Item """X942KDF"" (OSSL_SELF_TEST_DESC_KDF_X942KDF)" +.IP """PBKDF2"" (\fBOSSL_SELF_TEST_DESC_KDF_PBKDF2\fR)" 4 +.IX Item """PBKDF2"" (OSSL_SELF_TEST_DESC_KDF_PBKDF2)" +.IP """SSHKDF"" (\fBOSSL_SELF_TEST_DESC_KDF_SSHKDF\fR)" 4 +.IX Item """SSHKDF"" (OSSL_SELF_TEST_DESC_KDF_SSHKDF)" +.IP """TLS12_PRF"" (\fBOSSL_SELF_TEST_DESC_KDF_TLS12_PRF\fR)" 4 +.IX Item """TLS12_PRF"" (OSSL_SELF_TEST_DESC_KDF_TLS12_PRF)" +.IP """KBKDF"" (\fBOSSL_SELF_TEST_DESC_KDF_KBKDF\fR)" 4 +.IX Item """KBKDF"" (OSSL_SELF_TEST_DESC_KDF_KBKDF)" +.PD +Key Encapsulation Function tests used with the "KAT_KEM" type. +.IP """KEM_Encap"" (\fBOSSL_SELF_TEST_DESC_ENCAP_KEM\fR)" 4 +.IX Item """KEM_Encap"" (OSSL_SELF_TEST_DESC_ENCAP_KEM)" +.PD 0 +.IP """KEM_Decap"" (\fBOSSL_SELF_TEST_DESC_DECAP_KEM\fR)" 4 +.IX Item """KEM_Decap"" (OSSL_SELF_TEST_DESC_DECAP_KEM)" +.IP """KEM_Decap_Reject"" (\fBOSSL_SELF_TEST_DESC_DECAP_REJ_KEM\fR)" 4 +.IX Item """KEM_Decap_Reject"" (OSSL_SELF_TEST_DESC_DECAP_REJ_KEM)" +.PD +Key Derivation Function tests used with the "KAT_KDF" type. +.IP """CTR"" (\fBOSSL_SELF_TEST_DESC_DRBG_CTR\fR)" 4 +.IX Item """CTR"" (OSSL_SELF_TEST_DESC_DRBG_CTR)" +.PD 0 +.IP """HASH"" (\fBOSSL_SELF_TEST_DESC_DRBG_HASH\fR)" 4 +.IX Item """HASH"" (OSSL_SELF_TEST_DESC_DRBG_HASH)" +.IP """HMAC"" (\fBOSSL_SELF_TEST_DESC_DRBG_HMAC\fR)" 4 +.IX Item """HMAC"" (OSSL_SELF_TEST_DESC_DRBG_HMAC)" +.PD +DRBG tests used with the "DRBG" type. +.IP """RNG"" (\fBOSSL_SELF_TEST_DESC_RNG\fR)" 4 +.IX Item """RNG"" (OSSL_SELF_TEST_DESC_RNG)" +"Continuous_RNG_Test" uses this. +.SH EXAMPLES +.IX Header "EXAMPLES" +A simple self test callback is shown below for illustrative purposes. +.PP +.Vb 1 +\& #include +\& +\& static OSSL_CALLBACK self_test_cb; +\& +\& static int self_test_cb(const OSSL_PARAM params[], void *arg) +\& { +\& int ret = 0; +\& const OSSL_PARAM *p = NULL; +\& const char *phase = NULL, *type = NULL, *desc = NULL; +\& +\& p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE); +\& if (p == NULL || p\->data_type != OSSL_PARAM_UTF8_STRING) +\& goto err; +\& phase = (const char *)p\->data; +\& +\& p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC); +\& if (p == NULL || p\->data_type != OSSL_PARAM_UTF8_STRING) +\& goto err; +\& desc = (const char *)p\->data; +\& +\& p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE); +\& if (p == NULL || p\->data_type != OSSL_PARAM_UTF8_STRING) +\& goto err; +\& type = (const char *)p\->data; +\& +\& /* Do some logging */ +\& if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0) +\& BIO_printf(bio_out, "%s : (%s) : ", desc, type); +\& if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0 +\& || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0) +\& BIO_printf(bio_out, "%s\en", phase); +\& +\& /* Corrupt the SHA1 self test during the \*(Aqcorrupt\*(Aq phase by returning 0 */ +\& if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0 +\& && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) { +\& BIO_printf(bio_out, "%s %s", phase, desc); +\& return 0; +\& } +\& ret = 1; +\& err: +\& return ret; +\& } +.Ve +.SH NOTES +.IX Header "NOTES" +Some released versions of OpenSSL do not include a validated +FIPS provider. To determine which versions have undergone +the validation process, please refer to the +OpenSSL Downloads page . If you +require FIPS\-approved functionality, it is essential to build your FIPS +provider using one of the validated versions listed there. Normally, +it is possible to utilize a FIPS provider constructed from one of the +validated versions alongside \fIlibcrypto\fR and \fIlibssl\fR compiled from any +release within the same major release series. This flexibility enables +you to address bug fixes and CVEs that fall outside the FIPS boundary. +.PP +You can load the FIPS provider into multiple library contexts as any other +provider. However the following restriction applies. The FIPS provider cannot +be used by multiple copies of OpenSSL libcrypto in a single process. +.PP +As the provider saves core callbacks to the libcrypto obtained in the +\&\fBOSSL_provider_init()\fR call to global data it will fail if subsequent +invocations of its \fBOSSL_provider_init()\fR function yield different addresses +of these callbacks than in the initial call. This happens when different +copies of libcrypto are present in the memory of the process and both try +to load the same FIPS provider. A workaround is to have a different copy +of the FIPS provider loaded for each of the libcrypto instances in the +process. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-fipsinstall\fR\|(1), +\&\fBfips_config\fR\|(5), +\&\fBOSSL_SELF_TEST_set_callback\fR\|(3), +\&\fBOSSL_SELF_TEST_new\fR\|(3), +\&\fBOSSL_PARAM\fR\|(3), +\&\fBopenssl\-core.h\fR\|(7), +\&\fBopenssl\-core_dispatch.h\fR\|(7), +\&\fBprovider\fR\|(7), + +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/OSSL_PROVIDER-base.7 b/static/netbsd/man7/OSSL_PROVIDER-base.7 new file mode 100644 index 00000000..d4900e53 --- /dev/null +++ b/static/netbsd/man7/OSSL_PROVIDER-base.7 @@ -0,0 +1,284 @@ +.\" $NetBSD: OSSL_PROVIDER-base.7,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_PROVIDER-BASE 7" +.TH OSSL_PROVIDER-BASE 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_PROVIDER\-base \- OpenSSL base provider +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The OpenSSL base provider supplies the encoding for OpenSSL\*(Aqs +asymmetric cryptography. +.SS Properties +.IX Subsection "Properties" +The implementations in this provider specifically have this property +defined: +.IP """provider=base""" 4 +.IX Item """provider=base""" +.PP +It may be used in a property query string with fetching functions. +.PP +It isn\*(Aqt mandatory to query for this property, except to make sure to get +implementations of this provider and none other. +.IP """type=parameters""" 4 +.IX Item """type=parameters""" +.PD 0 +.IP """type=private""" 4 +.IX Item """type=private""" +.IP """type=public""" 4 +.IX Item """type=public""" +.PD +.PP +These may be used in a property query string with fetching functions to select +which data are to be encoded. Either the private key material, the public +key material or the domain parameters can be selected. +.IP """format=der""" 4 +.IX Item """format=der""" +.PD 0 +.IP """format=pem""" 4 +.IX Item """format=pem""" +.IP """format=text""" 4 +.IX Item """format=text""" +.PD +.PP +These may be used in a property query string with fetching functions to select +the encoding output format. Either the DER, PEM and plaintext are +currently permitted. +.SH "OPERATIONS AND ALGORITHMS" +.IX Header "OPERATIONS AND ALGORITHMS" +The OpenSSL base provider supports these operations and algorithms: +.SS "Random Number Generation" +.IX Subsection "Random Number Generation" +.IP "SEED\-SRC, see \fBEVP_RAND\-SEED\-SRC\fR\|(7)" 4 +.IX Item "SEED-SRC, see EVP_RAND-SEED-SRC" +.PD 0 +.IP "JITTER, see \fBEVP_RAND\-JITTER\fR\|(7)" 4 +.IX Item "JITTER, see EVP_RAND-JITTER" +.PD +.PP +In addition to this provider, the "SEED\-SRC" and "JITTER" algorithms +are also available in the default provider. +.SS "Asymmetric Key Encoder" +.IX Subsection "Asymmetric Key Encoder" +.IP RSA 4 +.IX Item "RSA" +.PD 0 +.IP RSA\-PSS 4 +.IX Item "RSA-PSS" +.IP DH 4 +.IX Item "DH" +.IP DHX 4 +.IX Item "DHX" +.IP DSA 4 +.IX Item "DSA" +.IP EC 4 +.IX Item "EC" +.IP ED25519 4 +.IX Item "ED25519" +.IP ED448 4 +.IX Item "ED448" +.IP X25519 4 +.IX Item "X25519" +.IP X448 4 +.IX Item "X448" +.IP SM2 4 +.IX Item "SM2" +.IP ML\-DSA\-44 4 +.IX Item "ML-DSA-44" +.IP ML\-DSA\-65 4 +.IX Item "ML-DSA-65" +.IP ML\-DSA\-87 4 +.IX Item "ML-DSA-87" +.IP ML\-KEM\-512 4 +.IX Item "ML-KEM-512" +.IP ML\-KEM\-768 4 +.IX Item "ML-KEM-768" +.IP ML\-KEM\-1024 4 +.IX Item "ML-KEM-1024" +.IP SLH\-DSA\-SHA2\-128s 4 +.IX Item "SLH-DSA-SHA2-128s" +.IP SLH\-DSA\-SHA2\-128f 4 +.IX Item "SLH-DSA-SHA2-128f" +.IP SLH\-DSA\-SHA2\-192s 4 +.IX Item "SLH-DSA-SHA2-192s" +.IP SLH\-DSA\-SHA2\-192f 4 +.IX Item "SLH-DSA-SHA2-192f" +.IP SLH\-DSA\-SHA2\-256s 4 +.IX Item "SLH-DSA-SHA2-256s" +.IP SLH\-DSA\-SHA2\-256f 4 +.IX Item "SLH-DSA-SHA2-256f" +.IP SLH\-DSA\-SHAKE\-128s 4 +.IX Item "SLH-DSA-SHAKE-128s" +.IP SLH\-DSA\-SHAKE\-128f 4 +.IX Item "SLH-DSA-SHAKE-128f" +.IP SLH\-DSA\-SHAKE\-192s 4 +.IX Item "SLH-DSA-SHAKE-192s" +.IP SLH\-DSA\-SHAKE\-192f 4 +.IX Item "SLH-DSA-SHAKE-192f" +.IP SLH\-DSA\-SHAKE\-256s 4 +.IX Item "SLH-DSA-SHAKE-256s" +.IP SLH\-DSA\-SHAKE\-256f 4 +.IX Item "SLH-DSA-SHAKE-256f" +.PD +.PP +In addition to this provider, all of these encoding algorithms are also +available in the default provider. Some of these algorithms may be used in +combination with the FIPS provider. +.SS "Asymmetric Key Decoder" +.IX Subsection "Asymmetric Key Decoder" +.IP RSA 4 +.IX Item "RSA" +.PD 0 +.IP RSA\-PSS 4 +.IX Item "RSA-PSS" +.IP DH 4 +.IX Item "DH" +.IP DHX 4 +.IX Item "DHX" +.IP DSA 4 +.IX Item "DSA" +.IP EC 4 +.IX Item "EC" +.IP ED25519 4 +.IX Item "ED25519" +.IP ED448 4 +.IX Item "ED448" +.IP X25519 4 +.IX Item "X25519" +.IP X448 4 +.IX Item "X448" +.IP SM2 4 +.IX Item "SM2" +.IP DER 4 +.IX Item "DER" +.IP ML\-DSA\-44 4 +.IX Item "ML-DSA-44" +.IP ML\-DSA\-65 4 +.IX Item "ML-DSA-65" +.IP ML\-DSA\-87 4 +.IX Item "ML-DSA-87" +.IP ML\-KEM\-512 4 +.IX Item "ML-KEM-512" +.IP ML\-KEM\-768 4 +.IX Item "ML-KEM-768" +.IP ML\-KEM\-1024 4 +.IX Item "ML-KEM-1024" +.IP SLH\-DSA\-SHA2\-128s 4 +.IX Item "SLH-DSA-SHA2-128s" +.IP SLH\-DSA\-SHA2\-128f 4 +.IX Item "SLH-DSA-SHA2-128f" +.IP SLH\-DSA\-SHA2\-192s 4 +.IX Item "SLH-DSA-SHA2-192s" +.IP SLH\-DSA\-SHA2\-192f 4 +.IX Item "SLH-DSA-SHA2-192f" +.IP SLH\-DSA\-SHA2\-256s 4 +.IX Item "SLH-DSA-SHA2-256s" +.IP SLH\-DSA\-SHA2\-256f 4 +.IX Item "SLH-DSA-SHA2-256f" +.IP SLH\-DSA\-SHAKE\-128s 4 +.IX Item "SLH-DSA-SHAKE-128s" +.IP SLH\-DSA\-SHAKE\-128f 4 +.IX Item "SLH-DSA-SHAKE-128f" +.IP SLH\-DSA\-SHAKE\-192s 4 +.IX Item "SLH-DSA-SHAKE-192s" +.IP SLH\-DSA\-SHAKE\-192f 4 +.IX Item "SLH-DSA-SHAKE-192f" +.IP SLH\-DSA\-SHAKE\-256s 4 +.IX Item "SLH-DSA-SHAKE-256s" +.IP SLH\-DSA\-SHAKE\-256f 4 +.IX Item "SLH-DSA-SHAKE-256f" +.PD +.PP +In addition to this provider, all of these decoding algorithms are also +available in the default provider. Some of these algorithms may be used in +combination with the FIPS provider. +.SS Stores +.IX Subsection "Stores" +.IP file 4 +.IX Item "file" +.PD 0 +.IP "org.openssl.winstore, see \fBOSSL_STORE\-winstore\fR\|(7)" 4 +.IX Item "org.openssl.winstore, see OSSL_STORE-winstore" +.PD +.PP +In addition to this provider, all of these store algorithms are also +available in the default provider. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_PROVIDER\-default\fR\|(7), \fBopenssl\-core.h\fR\|(7), +\&\fBopenssl\-core_dispatch.h\fR\|(7), \fBprovider\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.PP +Support for \fBML\-DSA\fR and was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/OSSL_PROVIDER-default.7 b/static/netbsd/man7/OSSL_PROVIDER-default.7 new file mode 100644 index 00000000..a493fb67 --- /dev/null +++ b/static/netbsd/man7/OSSL_PROVIDER-default.7 @@ -0,0 +1,564 @@ +.\" $NetBSD: OSSL_PROVIDER-default.7,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_PROVIDER-DEFAULT 7" +.TH OSSL_PROVIDER-DEFAULT 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_PROVIDER\-default \- OpenSSL default provider +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The OpenSSL default provider supplies the majority of OpenSSL\*(Aqs diverse +algorithm implementations. If an application doesn\*(Aqt specify anything else +explicitly (e.g. in the application or via config), then this is the +provider that will be used as fallback: It is loaded automatically the +first time that an algorithm is fetched from a provider or a function +acting on providers is called and no other provider has been loaded yet. +.PP +If an attempt to load a provider has already been made (whether successful +or not) then the default provider won\*(Aqt be loaded automatically. Therefore +if the default provider is to be used in conjunction with other providers +then it must be loaded explicitly. Automatic loading of the default +provider only occurs a maximum of once; if the default provider is +explicitly unloaded then the default provider will not be automatically +loaded again. +.SS Properties +.IX Subsection "Properties" +The implementations in this provider specifically have this property +defined: +.IP """provider=default""" 4 +.IX Item """provider=default""" +.PP +It may be used in a property query string with fetching functions such as +\&\fBEVP_MD_fetch\fR\|(3) or \fBEVP_CIPHER_fetch\fR\|(3), as well as with other +functions that take a property query string, such as +\&\fBEVP_PKEY_CTX_new_from_name\fR\|(3). +.PP +It isn\*(Aqt mandatory to query for this property, except to make sure to get +implementations of this provider and none other. +.PP +Some implementations may define additional properties. Exact information is +listed below +.SH "OPERATIONS AND ALGORITHMS" +.IX Header "OPERATIONS AND ALGORITHMS" +The OpenSSL default provider supports these operations and algorithms: +.SS "Hashing Algorithms / Message Digests" +.IX Subsection "Hashing Algorithms / Message Digests" +.IP "SHA1, see \fBEVP_MD\-SHA1\fR\|(7)" 4 +.IX Item "SHA1, see EVP_MD-SHA1" +.PD 0 +.IP "SHA2, see \fBEVP_MD\-SHA2\fR\|(7)" 4 +.IX Item "SHA2, see EVP_MD-SHA2" +.IP "SHA3, see \fBEVP_MD\-SHA3\fR\|(7)" 4 +.IX Item "SHA3, see EVP_MD-SHA3" +.IP "KECCAK, see \fBEVP_MD\-KECCAK\fR\|(7)" 4 +.IX Item "KECCAK, see EVP_MD-KECCAK" +.IP "KECCAK\-KMAC, see \fBEVP_MD\-KECCAK\-KMAC\fR\|(7)" 4 +.IX Item "KECCAK-KMAC, see EVP_MD-KECCAK-KMAC" +.IP "SHAKE, see \fBEVP_MD\-SHAKE\fR\|(7)" 4 +.IX Item "SHAKE, see EVP_MD-SHAKE" +.IP "BLAKE2, see \fBEVP_MD\-BLAKE2\fR\|(7)" 4 +.IX Item "BLAKE2, see EVP_MD-BLAKE2" +.IP "SM3, see \fBEVP_MD\-SM3\fR\|(7)" 4 +.IX Item "SM3, see EVP_MD-SM3" +.IP "MD5, see \fBEVP_MD\-MD5\fR\|(7)" 4 +.IX Item "MD5, see EVP_MD-MD5" +.IP "MD5\-SHA1, see \fBEVP_MD\-MD5\-SHA1\fR\|(7)" 4 +.IX Item "MD5-SHA1, see EVP_MD-MD5-SHA1" +.IP "RIPEMD160, see \fBEVP_MD\-RIPEMD160\fR\|(7)" 4 +.IX Item "RIPEMD160, see EVP_MD-RIPEMD160" +.IP "NULL, see \fBEVP_MD\-NULL\fR\|(7)" 4 +.IX Item "NULL, see EVP_MD-NULL" +.PD +.SS "Symmetric Ciphers" +.IX Subsection "Symmetric Ciphers" +.IP "AES, see \fBEVP_CIPHER\-AES\fR\|(7)" 4 +.IX Item "AES, see EVP_CIPHER-AES" +.PD 0 +.IP "ARIA, see \fBEVP_CIPHER\-ARIA\fR\|(7)" 4 +.IX Item "ARIA, see EVP_CIPHER-ARIA" +.IP "CAMELLIA, see \fBEVP_CIPHER\-CAMELLIA\fR\|(7)" 4 +.IX Item "CAMELLIA, see EVP_CIPHER-CAMELLIA" +.IP "3DES, see \fBEVP_CIPHER\-DES\fR\|(7)" 4 +.IX Item "3DES, see EVP_CIPHER-DES" +.IP "SM4, see \fBEVP_CIPHER\-SM4\fR\|(7)" 4 +.IX Item "SM4, see EVP_CIPHER-SM4" +.IP "ChaCha20, see \fBEVP_CIPHER\-CHACHA\fR\|(7)" 4 +.IX Item "ChaCha20, see EVP_CIPHER-CHACHA" +.IP "ChaCha20\-Poly1305, see \fBEVP_CIPHER\-CHACHA\fR\|(7)" 4 +.IX Item "ChaCha20-Poly1305, see EVP_CIPHER-CHACHA" +.IP "NULL, see \fBEVP_CIPHER\-NULL\fR\|(7)" 4 +.IX Item "NULL, see EVP_CIPHER-NULL" +.PD +.SS "Message Authentication Code (MAC)" +.IX Subsection "Message Authentication Code (MAC)" +.IP "BLAKE2, see \fBEVP_MAC\-BLAKE2\fR\|(7)" 4 +.IX Item "BLAKE2, see EVP_MAC-BLAKE2" +.PD 0 +.IP "CMAC, see \fBEVP_MAC\-CMAC\fR\|(7)" 4 +.IX Item "CMAC, see EVP_MAC-CMAC" +.IP "GMAC, see \fBEVP_MAC\-GMAC\fR\|(7)" 4 +.IX Item "GMAC, see EVP_MAC-GMAC" +.IP "HMAC, see \fBEVP_MAC\-HMAC\fR\|(7)" 4 +.IX Item "HMAC, see EVP_MAC-HMAC" +.IP "KMAC, see \fBEVP_MAC\-KMAC\fR\|(7)" 4 +.IX Item "KMAC, see EVP_MAC-KMAC" +.IP "SIPHASH, see \fBEVP_MAC\-Siphash\fR\|(7)" 4 +.IX Item "SIPHASH, see EVP_MAC-Siphash" +.IP "POLY1305, see \fBEVP_MAC\-Poly1305\fR\|(7)" 4 +.IX Item "POLY1305, see EVP_MAC-Poly1305" +.PD +.SS "Key Derivation Function (KDF)" +.IX Subsection "Key Derivation Function (KDF)" +.IP "HKDF, see \fBEVP_KDF\-HKDF\fR\|(7)" 4 +.IX Item "HKDF, see EVP_KDF-HKDF" +.PD 0 +.IP "TLS13\-KDF, see \fBEVP_KDF\-TLS13_KDF\fR\|(7)" 4 +.IX Item "TLS13-KDF, see EVP_KDF-TLS13_KDF" +.IP "SSKDF, see \fBEVP_KDF\-SS\fR\|(7)" 4 +.IX Item "SSKDF, see EVP_KDF-SS" +.IP "PBKDF2, see \fBEVP_KDF\-PBKDF2\fR\|(7)" 4 +.IX Item "PBKDF2, see EVP_KDF-PBKDF2" +.IP "PKCS12KDF, see \fBEVP_KDF\-PKCS12KDF\fR\|(7)" 4 +.IX Item "PKCS12KDF, see EVP_KDF-PKCS12KDF" +.IP "SSHKDF, see \fBEVP_KDF\-SSHKDF\fR\|(7)" 4 +.IX Item "SSHKDF, see EVP_KDF-SSHKDF" +.IP "TLS1\-PRF, see \fBEVP_KDF\-TLS1_PRF\fR\|(7)" 4 +.IX Item "TLS1-PRF, see EVP_KDF-TLS1_PRF" +.IP "KBKDF, see \fBEVP_KDF\-KB\fR\|(7)" 4 +.IX Item "KBKDF, see EVP_KDF-KB" +.IP "X942KDF\-ASN1, see \fBEVP_KDF\-X942\-ASN1\fR\|(7)" 4 +.IX Item "X942KDF-ASN1, see EVP_KDF-X942-ASN1" +.IP "X942KDF\-CONCAT, see \fBEVP_KDF\-X942\-CONCAT\fR\|(7)" 4 +.IX Item "X942KDF-CONCAT, see EVP_KDF-X942-CONCAT" +.IP "X963KDF, see \fBEVP_KDF\-X963\fR\|(7)" 4 +.IX Item "X963KDF, see EVP_KDF-X963" +.IP "SCRYPT, see \fBEVP_KDF\-SCRYPT\fR\|(7)" 4 +.IX Item "SCRYPT, see EVP_KDF-SCRYPT" +.IP "KRB5KDF, see \fBEVP_KDF\-KRB5KDF\fR\|(7)" 4 +.IX Item "KRB5KDF, see EVP_KDF-KRB5KDF" +.IP "HMAC\-DRBG, see \fBEVP_KDF\-HMAC\-DRBG\fR\|(7)" 4 +.IX Item "HMAC-DRBG, see EVP_KDF-HMAC-DRBG" +.IP "ARGON2, see \fBEVP_KDF\-ARGON2\fR\|(7)" 4 +.IX Item "ARGON2, see EVP_KDF-ARGON2" +.PD +.SS "Key Exchange" +.IX Subsection "Key Exchange" +.IP "DH, see \fBEVP_KEYEXCH\-DH\fR\|(7)" 4 +.IX Item "DH, see EVP_KEYEXCH-DH" +.PD 0 +.IP "ECDH, see \fBEVP_KEYEXCH\-ECDH\fR\|(7)" 4 +.IX Item "ECDH, see EVP_KEYEXCH-ECDH" +.IP "X25519, see \fBEVP_KEYEXCH\-X25519\fR\|(7)" 4 +.IX Item "X25519, see EVP_KEYEXCH-X25519" +.IP "X448, see \fBEVP_KEYEXCH\-X448\fR\|(7)" 4 +.IX Item "X448, see EVP_KEYEXCH-X448" +.IP "ML\-KEM\-512, see \fBEVP_KEM\-ML\-KEM\-512\fR\|(7)" 4 +.IX Item "ML-KEM-512, see EVP_KEM-ML-KEM-512" +.IP "ML\-KEM\-768, see \fBEVP_KEM\-ML\-KEM\-768\fR\|(7)" 4 +.IX Item "ML-KEM-768, see EVP_KEM-ML-KEM-768" +.IP "ML\-KEM\-1024, see \fBEVP_KEM\-ML\-KEM\-1024\fR\|(7)" 4 +.IX Item "ML-KEM-1024, see EVP_KEM-ML-KEM-1024" +.IP TLS1\-PRF 4 +.IX Item "TLS1-PRF" +.IP HKDF 4 +.IX Item "HKDF" +.IP SCRYPT 4 +.IX Item "SCRYPT" +.PD +.SS "Asymmetric Signature" +.IX Subsection "Asymmetric Signature" +.IP "DSA, see \fBEVP_SIGNATURE\-DSA\fR\|(7)" 4 +.IX Item "DSA, see EVP_SIGNATURE-DSA" +.PD 0 +.IP "RSA, see \fBEVP_SIGNATURE\-RSA\fR\|(7)" 4 +.IX Item "RSA, see EVP_SIGNATURE-RSA" +.IP "ED25519, see \fBEVP_SIGNATURE\-ED25519\fR\|(7)" 4 +.IX Item "ED25519, see EVP_SIGNATURE-ED25519" +.IP "ED448, see \fBEVP_SIGNATURE\-ED448\fR\|(7)" 4 +.IX Item "ED448, see EVP_SIGNATURE-ED448" +.IP "ECDSA, see \fBEVP_SIGNATURE\-ECDSA\fR\|(7)" 4 +.IX Item "ECDSA, see EVP_SIGNATURE-ECDSA" +.IP SM2 4 +.IX Item "SM2" +.IP "ML\-DSA\-44, see \fBEVP_SIGNATURE\-ML\-DSA\fR\|(7)" 4 +.IX Item "ML-DSA-44, see EVP_SIGNATURE-ML-DSA" +.IP "ML\-DSA\-65, see \fBEVP_SIGNATURE\-ML\-DSA\fR\|(7)" 4 +.IX Item "ML-DSA-65, see EVP_SIGNATURE-ML-DSA" +.IP "ML\-DSA\-87, see \fBEVP_SIGNATURE\-ML\-DSA\fR\|(7)" 4 +.IX Item "ML-DSA-87, see EVP_SIGNATURE-ML-DSA" +.IP "HMAC, see \fBEVP_SIGNATURE\-HMAC\fR\|(7)" 4 +.IX Item "HMAC, see EVP_SIGNATURE-HMAC" +.IP "SIPHASH, see \fBEVP_SIGNATURE\-Siphash\fR\|(7)" 4 +.IX Item "SIPHASH, see EVP_SIGNATURE-Siphash" +.IP "POLY1305, see \fBEVP_SIGNATURE\-Poly1305\fR\|(7)" 4 +.IX Item "POLY1305, see EVP_SIGNATURE-Poly1305" +.IP "CMAC, see \fBEVP_SIGNATURE\-CMAC\fR\|(7)" 4 +.IX Item "CMAC, see EVP_SIGNATURE-CMAC" +.IP "SLH\-DSA\-SHA2\-128s, see \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-128s, see EVP_SIGNATURE-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-128f, see \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-128f, see EVP_SIGNATURE-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-192s, see \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-192s, see EVP_SIGNATURE-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-192f, see \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-192f, see EVP_SIGNATURE-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-256s, see \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-256s, see EVP_SIGNATURE-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-256f, see \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-256f, see EVP_SIGNATURE-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-128s, see \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-128s, see EVP_SIGNATURE-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-128f, see \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-128f, see EVP_SIGNATURE-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-192s, see \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-192s, see EVP_SIGNATURE-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-192f, see \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-192f, see EVP_SIGNATURE-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-256s, see \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-256s, see EVP_SIGNATURE-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-256f, see \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-256f, see EVP_SIGNATURE-SLH-DSA" +.PD +.SS "Asymmetric Cipher" +.IX Subsection "Asymmetric Cipher" +.IP "RSA, see \fBEVP_ASYM_CIPHER\-RSA\fR\|(7)" 4 +.IX Item "RSA, see EVP_ASYM_CIPHER-RSA" +.PD 0 +.IP "SM2, see \fBEVP_ASYM_CIPHER\-SM2\fR\|(7)" 4 +.IX Item "SM2, see EVP_ASYM_CIPHER-SM2" +.PD +.SS "Asymmetric Key Encapsulation" +.IX Subsection "Asymmetric Key Encapsulation" +.IP "RSA, see \fBEVP_KEM\-RSA\fR\|(7)" 4 +.IX Item "RSA, see EVP_KEM-RSA" +.PD 0 +.IP "X25519, see \fBEVP_KEM\-X25519\fR\|(7)" 4 +.IX Item "X25519, see EVP_KEM-X25519" +.IP "X448, see \fBEVP_KEM\-X448\fR\|(7)" 4 +.IX Item "X448, see EVP_KEM-X448" +.IP "EC, see \fBEVP_KEM\-EC\fR\|(7)" 4 +.IX Item "EC, see EVP_KEM-EC" +.IP "ML\-KEM\-512, see \fBEVP_KEM\-ML\-KEM\-512\fR\|(7)" 4 +.IX Item "ML-KEM-512, see EVP_KEM-ML-KEM-512" +.IP "ML\-KEM\-768, see \fBEVP_KEM\-ML\-KEM\-768\fR\|(7)" 4 +.IX Item "ML-KEM-768, see EVP_KEM-ML-KEM-768" +.IP "ML\-KEM\-1024, see \fBEVP_KEM\-ML\-KEM\-1024\fR\|(7)" 4 +.IX Item "ML-KEM-1024, see EVP_KEM-ML-KEM-1024" +.PD +.SS "Asymmetric Key Management" +.IX Subsection "Asymmetric Key Management" +.IP "DSA, see \fBEVP_KEYMGMT\-DSA\fR\|(7)" 4 +.IX Item "DSA, see EVP_KEYMGMT-DSA" +.PD 0 +.IP "RSA, see \fBEVP_KEYMGMT\-RSA\fR\|(7)" 4 +.IX Item "RSA, see EVP_KEYMGMT-RSA" +.IP RSA\-PSS 4 +.IX Item "RSA-PSS" +.IP "EC, see \fBEVP_KEYMGMT\-EC\fR\|(7)" 4 +.IX Item "EC, see EVP_KEYMGMT-EC" +.IP "ED25519, see \fBEVP_KEYMGMT\-ED25519\fR\|(7)" 4 +.IX Item "ED25519, see EVP_KEYMGMT-ED25519" +.IP "ED448, see \fBEVP_KEYMGMT\-ED448\fR\|(7)" 4 +.IX Item "ED448, see EVP_KEYMGMT-ED448" +.IP "SM2, see \fBEVP_KEYMGMT\-SM2\fR\|(7)" 4 +.IX Item "SM2, see EVP_KEYMGMT-SM2" +.IP "DH, see \fBEVP_KEYMGMT\-DH\fR\|(7)" 4 +.IX Item "DH, see EVP_KEYMGMT-DH" +.IP "DHX, see \fBEVP_KEYMGMT\-DHX\fR\|(7)" 4 +.IX Item "DHX, see EVP_KEYMGMT-DHX" +.IP "X25519, see \fBEVP_KEYMGMT\-X25519\fR\|(7)" 4 +.IX Item "X25519, see EVP_KEYMGMT-X25519" +.IP "X448, see \fBEVP_KEYMGMT\-X448\fR\|(7)" 4 +.IX Item "X448, see EVP_KEYMGMT-X448" +.IP "ML\-DSA\-44, see \fBEVP_KEYMGMT\-ML\-DSA\fR\|(7)" 4 +.IX Item "ML-DSA-44, see EVP_KEYMGMT-ML-DSA" +.IP "ML\-DSA\-65, see \fBEVP_KEYMGMT\-ML\-DSA\fR\|(7)" 4 +.IX Item "ML-DSA-65, see EVP_KEYMGMT-ML-DSA" +.IP "ML\-DSA\-87, see \fBEVP_KEYMGMT\-ML\-DSA\fR\|(7)" 4 +.IX Item "ML-DSA-87, see EVP_KEYMGMT-ML-DSA" +.IP "MK\-KEM\-512, see \fBEVP_KEYMGMT\-ML\-KEM\-512\fR\|(7)" 4 +.IX Item "MK-KEM-512, see EVP_KEYMGMT-ML-KEM-512" +.IP "MK\-KEM\-768, see \fBEVP_KEYMGMT\-ML\-KEM\-768\fR\|(7)" 4 +.IX Item "MK-KEM-768, see EVP_KEYMGMT-ML-KEM-768" +.IP "MK\-KEM\-1024, see \fBEVP_KEYMGMT\-ML\-KEM\-1024\fR\|(7)" 4 +.IX Item "MK-KEM-1024, see EVP_KEYMGMT-ML-KEM-1024" +.IP "SLH\-DSA\-SHA2\-128s, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-128s, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-128f, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-128f, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-192s, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-192s, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-192f, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-192f, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-256s, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-256s, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHA2\-256f, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHA2-256f, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-128s, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-128s, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-128f, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-128f, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-192s, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-192s, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-192f, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-192f, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-256s, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-256s, see EVP_KEYMGMT-SLH-DSA" +.IP "SLH\-DSA\-SHAKE\-256f, see \fBEVP_KEYMGMT\-SLH\-DSA\fR\|(7)" 4 +.IX Item "SLH-DSA-SHAKE-256f, see EVP_KEYMGMT-SLH-DSA" +.IP TLS1\-PRF 4 +.IX Item "TLS1-PRF" +.IP HKDF 4 +.IX Item "HKDF" +.IP SCRYPT 4 +.IX Item "SCRYPT" +.IP "HMAC, see \fBEVP_KEYMGMT\-HMAC\fR\|(7)" 4 +.IX Item "HMAC, see EVP_KEYMGMT-HMAC" +.IP "SIPHASH, see \fBEVP_KEYMGMT\-Siphash\fR\|(7)" 4 +.IX Item "SIPHASH, see EVP_KEYMGMT-Siphash" +.IP "POLY1305, see \fBEVP_KEYMGMT\-Poly1305\fR\|(7)" 4 +.IX Item "POLY1305, see EVP_KEYMGMT-Poly1305" +.IP "CMAC, see \fBEVP_KEYMGMT\-CMAC\fR\|(7)" 4 +.IX Item "CMAC, see EVP_KEYMGMT-CMAC" +.PD +.SS "Random Number Generation" +.IX Subsection "Random Number Generation" +.IP "CTR\-DRBG, see \fBEVP_RAND\-CTR\-DRBG\fR\|(7)" 4 +.IX Item "CTR-DRBG, see EVP_RAND-CTR-DRBG" +.PD 0 +.IP "HASH\-DRBG, see \fBEVP_RAND\-HASH\-DRBG\fR\|(7)" 4 +.IX Item "HASH-DRBG, see EVP_RAND-HASH-DRBG" +.IP "HMAC\-DRBG, see \fBEVP_RAND\-HMAC\-DRBG\fR\|(7)" 4 +.IX Item "HMAC-DRBG, see EVP_RAND-HMAC-DRBG" +.IP "SEED\-SRC, see \fBEVP_RAND\-SEED\-SRC\fR\|(7)" 4 +.IX Item "SEED-SRC, see EVP_RAND-SEED-SRC" +.IP "JITTER, see \fBEVP_RAND\-JITTER\fR\|(7)" 4 +.IX Item "JITTER, see EVP_RAND-JITTER" +.IP "TEST\-RAND, see \fBEVP_RAND\-TEST\-RAND\fR\|(7)" 4 +.IX Item "TEST-RAND, see EVP_RAND-TEST-RAND" +.PD +.PP +In addition to this provider, the "SEED\-SRC" and "JITTER" algorithms +are also available in the base provider. +.SS "Asymmetric Key Encoder" +.IX Subsection "Asymmetric Key Encoder" +.IP RSA 4 +.IX Item "RSA" +.PD 0 +.IP RSA\-PSS 4 +.IX Item "RSA-PSS" +.IP DH 4 +.IX Item "DH" +.IP DHX 4 +.IX Item "DHX" +.IP DSA 4 +.IX Item "DSA" +.IP EC 4 +.IX Item "EC" +.IP ED25519 4 +.IX Item "ED25519" +.IP ED448 4 +.IX Item "ED448" +.IP X25519 4 +.IX Item "X25519" +.IP X448 4 +.IX Item "X448" +.IP SM2 4 +.IX Item "SM2" +.IP ML\-DSA\-44 4 +.IX Item "ML-DSA-44" +.IP ML\-DSA\-65 4 +.IX Item "ML-DSA-65" +.IP ML\-DSA\-87 4 +.IX Item "ML-DSA-87" +.IP ML\-KEM\-512 4 +.IX Item "ML-KEM-512" +.IP ML\-KEM\-768 4 +.IX Item "ML-KEM-768" +.IP ML\-KEM\-1024 4 +.IX Item "ML-KEM-1024" +.IP SLH\-DSA\-SHA2\-128s 4 +.IX Item "SLH-DSA-SHA2-128s" +.IP SLH\-DSA\-SHA2\-128f 4 +.IX Item "SLH-DSA-SHA2-128f" +.IP SLH\-DSA\-SHA2\-192s 4 +.IX Item "SLH-DSA-SHA2-192s" +.IP SLH\-DSA\-SHA2\-192f 4 +.IX Item "SLH-DSA-SHA2-192f" +.IP SLH\-DSA\-SHA2\-256s 4 +.IX Item "SLH-DSA-SHA2-256s" +.IP SLH\-DSA\-SHA2\-256f 4 +.IX Item "SLH-DSA-SHA2-256f" +.IP SLH\-DSA\-SHAKE\-128s 4 +.IX Item "SLH-DSA-SHAKE-128s" +.IP SLH\-DSA\-SHAKE\-128f 4 +.IX Item "SLH-DSA-SHAKE-128f" +.IP SLH\-DSA\-SHAKE\-192s 4 +.IX Item "SLH-DSA-SHAKE-192s" +.IP SLH\-DSA\-SHAKE\-192f 4 +.IX Item "SLH-DSA-SHAKE-192f" +.IP SLH\-DSA\-SHAKE\-256s 4 +.IX Item "SLH-DSA-SHAKE-256s" +.IP SLH\-DSA\-SHAKE\-256f 4 +.IX Item "SLH-DSA-SHAKE-256f" +.PD +.PP +In addition to this provider, all of these encoding algorithms are also +available in the base provider. Some of these algorithms may be used in +combination with the FIPS provider. +.SS "Asymmetric Key Decoder" +.IX Subsection "Asymmetric Key Decoder" +.IP RSA 4 +.IX Item "RSA" +.PD 0 +.IP RSA\-PSS 4 +.IX Item "RSA-PSS" +.IP DH 4 +.IX Item "DH" +.IP DHX 4 +.IX Item "DHX" +.IP DSA 4 +.IX Item "DSA" +.IP EC 4 +.IX Item "EC" +.IP ED25519 4 +.IX Item "ED25519" +.IP ED448 4 +.IX Item "ED448" +.IP X25519 4 +.IX Item "X25519" +.IP X448 4 +.IX Item "X448" +.IP SM2 4 +.IX Item "SM2" +.IP ML\-DSA\-44 4 +.IX Item "ML-DSA-44" +.IP ML\-DSA\-65 4 +.IX Item "ML-DSA-65" +.IP ML\-DSA\-87 4 +.IX Item "ML-DSA-87" +.IP ML\-KEM\-512 4 +.IX Item "ML-KEM-512" +.IP ML\-KEM\-768 4 +.IX Item "ML-KEM-768" +.IP ML\-KEM\-1024 4 +.IX Item "ML-KEM-1024" +.IP SLH\-DSA\-SHA2\-128s 4 +.IX Item "SLH-DSA-SHA2-128s" +.IP SLH\-DSA\-SHA2\-128f 4 +.IX Item "SLH-DSA-SHA2-128f" +.IP SLH\-DSA\-SHA2\-192s 4 +.IX Item "SLH-DSA-SHA2-192s" +.IP SLH\-DSA\-SHA2\-192f 4 +.IX Item "SLH-DSA-SHA2-192f" +.IP SLH\-DSA\-SHA2\-256s 4 +.IX Item "SLH-DSA-SHA2-256s" +.IP SLH\-DSA\-SHA2\-256f 4 +.IX Item "SLH-DSA-SHA2-256f" +.IP SLH\-DSA\-SHAKE\-128s 4 +.IX Item "SLH-DSA-SHAKE-128s" +.IP SLH\-DSA\-SHAKE\-128f 4 +.IX Item "SLH-DSA-SHAKE-128f" +.IP SLH\-DSA\-SHAKE\-192s 4 +.IX Item "SLH-DSA-SHAKE-192s" +.IP SLH\-DSA\-SHAKE\-192f 4 +.IX Item "SLH-DSA-SHAKE-192f" +.IP SLH\-DSA\-SHAKE\-256s 4 +.IX Item "SLH-DSA-SHAKE-256s" +.IP SLH\-DSA\-SHAKE\-256f 4 +.IX Item "SLH-DSA-SHAKE-256f" +.PD +.PP +In addition to this provider, all of these decoding algorithms are also +available in the base provider. Some of these algorithms may be used in +combination with the FIPS provider. +.SS Stores +.IX Subsection "Stores" +.IP file 4 +.IX Item "file" +.PD 0 +.IP "org.openssl.winstore, see \fBOSSL_STORE\-winstore\fR\|(7)" 4 +.IX Item "org.openssl.winstore, see OSSL_STORE-winstore" +.PD +.PP +In addition to this provider, all of these store algorithms are also +available in the base provider. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-core.h\fR\|(7), \fBopenssl\-core_dispatch.h\fR\|(7), \fBprovider\fR\|(7), +\&\fBOSSL_PROVIDER\-base\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The RIPEMD160 digest was added to the default provider in OpenSSL 3.0.7. +.PP +All other functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/OSSL_PROVIDER-legacy.7 b/static/netbsd/man7/OSSL_PROVIDER-legacy.7 new file mode 100644 index 00000000..3557c7bf --- /dev/null +++ b/static/netbsd/man7/OSSL_PROVIDER-legacy.7 @@ -0,0 +1,160 @@ +.\" $NetBSD: OSSL_PROVIDER-legacy.7,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_PROVIDER-LEGACY 7" +.TH OSSL_PROVIDER-LEGACY 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_PROVIDER\-legacy \- OpenSSL legacy provider +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The OpenSSL legacy provider supplies OpenSSL implementations of algorithms +that have been deemed legacy. Such algorithms have commonly fallen out of +use, have been deemed insecure by the cryptography community, or something +similar. +.PP +We can consider this the retirement home of cryptographic algorithms. +.SS Properties +.IX Subsection "Properties" +The implementations in this provider specifically has this property +defined: +.IP """provider=legacy""" 4 +.IX Item """provider=legacy""" +.PP +It may be used in a property query string with fetching functions such as +\&\fBEVP_MD_fetch\fR\|(3) or \fBEVP_CIPHER_fetch\fR\|(3), as well as with other +functions that take a property query string, such as +\&\fBEVP_PKEY_CTX_new_from_name\fR\|(3). +.PP +It isn\*(Aqt mandatory to query for any of these properties, except to +make sure to get implementations of this provider and none other. +.SH "OPERATIONS AND ALGORITHMS" +.IX Header "OPERATIONS AND ALGORITHMS" +The OpenSSL legacy provider supports these operations and algorithms: +.SS "Hashing Algorithms / Message Digests" +.IX Subsection "Hashing Algorithms / Message Digests" +.IP "MD2, see \fBEVP_MD\-MD2\fR\|(7)" 4 +.IX Item "MD2, see EVP_MD-MD2" +Disabled by default. Use \fIenable\-md2\fR config option to enable. +.IP "MD4, see \fBEVP_MD\-MD4\fR\|(7)" 4 +.IX Item "MD4, see EVP_MD-MD4" +.PD 0 +.IP "MDC2, see \fBEVP_MD\-MDC2\fR\|(7)" 4 +.IX Item "MDC2, see EVP_MD-MDC2" +.IP "WHIRLPOOL, see \fBEVP_MD\-WHIRLPOOL\fR\|(7)" 4 +.IX Item "WHIRLPOOL, see EVP_MD-WHIRLPOOL" +.IP "RIPEMD160, see \fBEVP_MD\-RIPEMD160\fR\|(7)" 4 +.IX Item "RIPEMD160, see EVP_MD-RIPEMD160" +.PD +.SS "Symmetric Ciphers" +.IX Subsection "Symmetric Ciphers" +Not all of these symmetric cipher algorithms are enabled by default. +.IP "Blowfish, see \fBEVP_CIPHER\-BLOWFISH\fR\|(7)" 4 +.IX Item "Blowfish, see EVP_CIPHER-BLOWFISH" +.PD 0 +.IP "CAST, see \fBEVP_CIPHER\-CAST\fR\|(7)" 4 +.IX Item "CAST, see EVP_CIPHER-CAST" +.IP "DES, see \fBEVP_CIPHER\-DES\fR\|(7)" 4 +.IX Item "DES, see EVP_CIPHER-DES" +.PD +The algorithm names are: DES_ECB, DES_CBC, DES_OFB, DES_CFB, DES_CFB1, DES_CFB8 +and DESX_CBC. +.IP "IDEA, see \fBEVP_CIPHER\-IDEA\fR\|(7)" 4 +.IX Item "IDEA, see EVP_CIPHER-IDEA" +.PD 0 +.IP "RC2, see \fBEVP_CIPHER\-RC2\fR\|(7)" 4 +.IX Item "RC2, see EVP_CIPHER-RC2" +.IP "RC4, see \fBEVP_CIPHER\-RC4\fR\|(7)" 4 +.IX Item "RC4, see EVP_CIPHER-RC4" +.IP "RC5, see \fBEVP_CIPHER\-RC5\fR\|(7)" 4 +.IX Item "RC5, see EVP_CIPHER-RC5" +.PD +Disabled by default. Use \fIenable\-rc5\fR config option to enable. +.IP "SEED, see \fBEVP_CIPHER\-SEED\fR\|(7)" 4 +.IX Item "SEED, see EVP_CIPHER-SEED" +.SS "Key Derivation Function (KDF)" +.IX Subsection "Key Derivation Function (KDF)" +.IP PBKDF1 4 +.IX Item "PBKDF1" +.PD 0 +.IP PVKKDF 4 +.IX Item "PVKKDF" +.PD +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_PARAM\fR\|(3), +\&\fBopenssl\-core.h\fR\|(7), +\&\fBopenssl\-core_dispatch.h\fR\|(7), +\&\fBprovider\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/OSSL_PROVIDER-null.7 b/static/netbsd/man7/OSSL_PROVIDER-null.7 new file mode 100644 index 00000000..73b22714 --- /dev/null +++ b/static/netbsd/man7/OSSL_PROVIDER-null.7 @@ -0,0 +1,95 @@ +.\" $NetBSD: OSSL_PROVIDER-null.7,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_PROVIDER-NULL 7" +.TH OSSL_PROVIDER-NULL 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_PROVIDER\-null \- OpenSSL null provider +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The OpenSSL null provider supplies no algorithms. +.PP +It can used to guarantee that the default library context and a fallback +provider will not be accidentally accessed. +.SS Properties +.IX Subsection "Properties" +The null provider defines no properties. +.SH "OPERATIONS AND ALGORITHMS" +.IX Header "OPERATIONS AND ALGORITHMS" +The OpenSSL null provider supports no operations and algorithms. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/OSSL_STORE-winstore.7 b/static/netbsd/man7/OSSL_STORE-winstore.7 new file mode 100644 index 00000000..20bb7613 --- /dev/null +++ b/static/netbsd/man7/OSSL_STORE-winstore.7 @@ -0,0 +1,128 @@ +.\" $NetBSD: OSSL_STORE-winstore.7,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_STORE-WINSTORE 7" +.TH OSSL_STORE-WINSTORE 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_STORE\-winstore \- OpenSSL built in OSSL_STORE for Windows +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The OSSL_STORE implementation for Windows provides access to Windows\*(Aq system +\&\f(CW\*(C`ROOT\*(C'\fR certificate store through URIs, using the URI scheme +\&\f(CW\*(C`org.openssl.winstore\*(C'\fR. +.SS "Supported URIs" +.IX Subsection "Supported URIs" +There is only one supported URI: +.PP +.Vb 1 +\& org.openssl.winstore: +.Ve +.PP +No authority (host, etc), no path, no query, no fragment. +.SS "Supported OSSL_STORE_SEARCH operations" +.IX Subsection "Supported OSSL_STORE_SEARCH operations" +.IP \fBOSSL_STORE_SEARCH_by_name\fR\|(3) 4 +.IX Item "OSSL_STORE_SEARCH_by_name" +As a matter of fact, this must be used. It is not possible to enumerate all +available certificates in the store. +.SS "Windows certificate store features" +.IX Subsection "Windows certificate store features" +Apart from diverse constraints present in the certificates themselves, the +Windows certificate store also has the ability to associate additional +constraining properties alongside a certificate in the store. This includes +both documented and undocumented capabilities: +.IP \(bu 4 +The documented capability to override EKU +.IP \(bu 4 +The undocumented capability to add name constraints +.IP \(bu 4 +The undocumented capability to override the certificate expiry date +.PP +\&\fISuch constraints are not checked by this OSSL_STORE implementation, and +thereby not honoured\fR. +.PP +However, once extracted with \fBOSSL_STORE_load\fR\|(3), certificates that have +constraints in their X.509 extensions will go through the usual constraint +checks when used by OpenSSL, and are thereby honoured. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl_store\fR\|(7), \fBOSSL_STORE_open_ex\fR\|(3), \fBOSSL_STORE_SEARCH\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The winstore (\f(CW\*(C`org.openssl.winstore\*(C'\fR) implementation was added in OpenSSL +3.2.0. +.SH NOTES +.IX Header "NOTES" +OpenSSL uses \fBOSSL_DECODER\fR\|(3) implementations under the hood. +To influence what \fBOSSL_DECODER\fR\|(3) implementations are used, it\*(Aqs advisable +to use \fBOSSL_STORE_open_ex\fR\|(3) and set the \fIpropq\fR argument. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/RAND.7 b/static/netbsd/man7/RAND.7 new file mode 100644 index 00000000..c77edb4e --- /dev/null +++ b/static/netbsd/man7/RAND.7 @@ -0,0 +1,148 @@ +.\" $NetBSD: RAND.7,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RAND 7" +.TH RAND 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RAND +\&\- the OpenSSL random generator +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Random numbers are a vital part of cryptography, they are needed to provide +unpredictability for tasks like key generation, creating salts, and many more. +Software\-based generators must be seeded with external randomness before they +can be used as a cryptographically\-secure pseudo\-random number generator +(CSPRNG). +The availability of common hardware with special instructions and +modern operating systems, which may use items such as interrupt jitter +and network packet timings, can be reasonable sources of seeding material. +.PP +OpenSSL comes with a default implementation of the RAND API which is based on +the deterministic random bit generator (DRBG) model as described in +[NIST SP 800\-90A Rev. 1]. The default random generator will initialize +automatically on first use and will be fully functional without having +to be initialized (\*(Aqseeded\*(Aq) explicitly. +It seeds and reseeds itself automatically using trusted random sources +provided by the operating system. +.PP +As a normal application developer, you do not have to worry about any details, +just use \fBRAND_bytes\fR\|(3) to obtain random data. +Having said that, there is one important rule to obey: Always check the error +return value of \fBRAND_bytes\fR\|(3) and do not take randomness for granted. +Although (re\-)seeding is automatic, it can fail because no trusted random source +is available or the trusted source(s) temporarily fail to provide sufficient +random seed material. +In this case the CSPRNG enters an error state and ceases to provide output, +until it is able to recover from the error by reseeding itself. +For more details on reseeding and error recovery, see \fBEVP_RAND\fR\|(7). +.PP +For values that should remain secret, you can use \fBRAND_priv_bytes\fR\|(3) +instead. +This method does not provide \*(Aqbetter\*(Aq randomness, it uses the same type of +CSPRNG. +The intention behind using a dedicated CSPRNG exclusively for private +values is that none of its output should be visible to an attacker (e.g., +used as salt value), in order to reveal as little information as +possible about its internal state, and that a compromise of the "public" +CSPRNG instance will not affect the secrecy of these private values. +.PP +In the rare case where the default implementation does not satisfy your special +requirements, the default RAND internals can be replaced by your own +\&\fBEVP_RAND\fR\|(3) objects. +.PP +Changing the default random generator should be necessary +only in exceptional cases and is not recommended, unless you have a profound +knowledge of cryptographic principles and understand the implications of your +changes. +.PP +Finally, it is possible for a provider to bypass the default RAND setup for +\&\fBRAND_bytes\fR\|(3) and associated functions. A provider can be specified as the +single randomness source via the \fBRAND_set1_random_provider\fR\|(3) function or via +configuration using the \fBrandom_provider\fR option in \fBconfig\fR\|(5). Once specified, +the nominated provider will be used directly when calling the \fBRAND_bytes\fR\|(3) +family of functions. +.SH "DEFAULT SETUP" +.IX Header "DEFAULT SETUP" +The default OpenSSL RAND method is based on the EVP_RAND deterministic random +bit generator (DRBG) classes. +A DRBG is a certain type of cryptographically\-secure pseudo\-random +number generator (CSPRNG), which is described in [NIST SP 800\-90A Rev. 1]. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRAND_bytes\fR\|(3), +\&\fBRAND_priv_bytes\fR\|(3), +\&\fBEVP_RAND\fR\|(3), +\&\fBRAND_get0_primary\fR\|(3), +\&\fBconfig\fR\|(5), +\&\fBEVP_RAND\fR\|(7), +\&\fBRAND_set1_random_provider\fR\|(3). +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/RAND_DRBG.7 b/static/netbsd/man7/RAND_DRBG.7 new file mode 100644 index 00000000..24077214 --- /dev/null +++ b/static/netbsd/man7/RAND_DRBG.7 @@ -0,0 +1,400 @@ +.\" $NetBSD: RAND_DRBG.7,v 1.3 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "RAND_DRBG 7" +.TH RAND_DRBG 7 "2018-12-08" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +RAND_DRBG \- the deterministic random bit generator +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The default OpenSSL \s-1RAND\s0 method is based on the \s-1RAND_DRBG\s0 class, +which implements a deterministic random bit generator (\s-1DRBG\s0). +A \s-1DRBG\s0 is a certain type of cryptographically-secure pseudo-random +number generator (\s-1CSPRNG\s0), which is described in +[\s-1NIST SP 800\-90A\s0 Rev. 1]. +.PP +While the \s-1RAND API\s0 is the 'frontend' which is intended to be used by +application developers for obtaining random bytes, the \s-1RAND_DRBG API\s0 +serves as the 'backend', connecting the former with the operating +systems's entropy sources and providing access to the \s-1DRBG\s0's +configuration parameters. +.SS "Disclaimer" +.IX Subsection "Disclaimer" +Unless you have very specific requirements for your random generator, +it is in general not necessary to utilize the \s-1RAND_DRBG API\s0 directly. +The usual way to obtain random bytes is to use \fBRAND_bytes\fR\|(3) or +\&\fBRAND_priv_bytes\fR\|(3), see also \s-1\fBRAND\s0\fR\|(7). +.SS "Typical Use Cases" +.IX Subsection "Typical Use Cases" +Typical examples for such special use cases are the following: +.IP "\(bu" 2 +You want to use your own private \s-1DRBG\s0 instances. +Multiple \s-1DRBG\s0 instances which are accessed only by a single thread provide +additional security (because their internal states are independent) and +better scalability in multithreaded applications (because they don't need +to be locked). +.IP "\(bu" 2 +You need to integrate a previously unsupported entropy source. +.IP "\(bu" 2 +You need to change the default settings of the standard OpenSSL \s-1RAND\s0 +implementation to meet specific requirements. +.SH "CHAINING" +.IX Header "CHAINING" +A \s-1DRBG\s0 instance can be used as the entropy source of another \s-1DRBG\s0 instance, +provided it has itself access to a valid entropy source. +The \s-1DRBG\s0 instance which acts as entropy source is called the \fIparent\fR \s-1DRBG,\s0 +the other instance the \fIchild\fR \s-1DRBG.\s0 +.PP +This is called chaining. A chained \s-1DRBG\s0 instance is created by passing +a pointer to the parent \s-1DRBG\s0 as argument to the \fBRAND_DRBG_new()\fR call. +It is possible to create chains of more than two \s-1DRBG\s0 in a row. +.SH "THE THREE SHARED DRBG INSTANCES" +.IX Header "THE THREE SHARED DRBG INSTANCES" +Currently, there are three shared \s-1DRBG\s0 instances, +the , , and \s-1DRBG.\s0 +While the \s-1DRBG\s0 is a single global instance, the and +\&\s-1DRBG\s0 are created per thread and accessed through thread-local storage. +.PP +By default, the functions \fBRAND_bytes\fR\|(3) and \fBRAND_priv_bytes\fR\|(3) use +the thread-local and \s-1DRBG\s0 instance, respectively. +.SS "The \s-1DRBG\s0 instance" +.IX Subsection "The DRBG instance" +The \s-1DRBG\s0 is not used directly by the application, only for reseeding +the two other two \s-1DRBG\s0 instances. It reseeds itself by obtaining randomness +either from os entropy sources or by consuming randomness which was added +previously by \fBRAND_add\fR\|(3). +.SS "The \s-1DRBG\s0 instance" +.IX Subsection "The DRBG instance" +This instance is used per default by \fBRAND_bytes\fR\|(3). +.SS "The \s-1DRBG\s0 instance" +.IX Subsection "The DRBG instance" +This instance is used per default by \fBRAND_priv_bytes\fR\|(3) +.SH "LOCKING" +.IX Header "LOCKING" +The \s-1DRBG\s0 is intended to be accessed concurrently for reseeding +by its child \s-1DRBG\s0 instances. The necessary locking is done internally. +It is \fInot\fR thread-safe to access the \s-1DRBG\s0 directly via the +\&\s-1RAND_DRBG\s0 interface. +The and \s-1DRBG\s0 are thread-local, i.e. there is an +instance of each per thread. So they can safely be accessed without +locking via the \s-1RAND_DRBG\s0 interface. +.PP +Pointers to these \s-1DRBG\s0 instances can be obtained using +\&\fBRAND_DRBG_get0_master()\fR, +\&\fBRAND_DRBG_get0_public()\fR, and +\&\fBRAND_DRBG_get0_private()\fR, respectively. +Note that it is not allowed to store a pointer to one of the thread-local +\&\s-1DRBG\s0 instances in a variable or other memory location where it will be +accessed and used by multiple threads. +.PP +All other \s-1DRBG\s0 instances created by an application don't support locking, +because they are intended to be used by a single thread. +Instead of accessing a single \s-1DRBG\s0 instance concurrently from different +threads, it is recommended to instantiate a separate \s-1DRBG\s0 instance per +thread. Using the \s-1DRBG\s0 as entropy source for multiple \s-1DRBG\s0 +instances on different threads is thread-safe, because the \s-1DRBG\s0 instance +will lock the \s-1DRBG\s0 automatically for obtaining random input. +.SH "THE OVERALL PICTURE" +.IX Header "THE OVERALL PICTURE" +The following picture gives an overview over how the \s-1DRBG\s0 instances work +together and are being used. +.PP +.Vb 10 +\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\& | os entropy sources | +\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\& | +\& v +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\& RAND_add() ==> <\-| shared DRBG (with locking) | +\& / \e +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\& / \e +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\& <\- | per\-thread DRBG instances | +\& | | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\& v v +\& RAND_bytes() RAND_priv_bytes() +\& | ^ +\& | | +\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\& | general purpose | | used for secrets like session keys | +\& | random generator | | and private keys for certificates | +\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +.Ve +.PP +The usual way to obtain random bytes is to call RAND_bytes(...) or +RAND_priv_bytes(...). These calls are roughly equivalent to calling +RAND_DRBG_bytes(, ...) and RAND_DRBG_bytes(, ...), +respectively. The method \fBRAND_DRBG_bytes\fR\|(3) is a convenience method +wrapping the \fBRAND_DRBG_generate\fR\|(3) function, which serves the actual +request for random data. +.SH "RESEEDING" +.IX Header "RESEEDING" +A \s-1DRBG\s0 instance seeds itself automatically, pulling random input from +its entropy source. The entropy source can be either a trusted operating +system entropy source, or another \s-1DRBG\s0 with access to such a source. +.PP +Automatic reseeding occurs after a predefined number of generate requests. +The selection of the trusted entropy sources is configured at build +time using the \-\-with\-rand\-seed option. The following sections explain +the reseeding process in more detail. +.SS "Automatic Reseeding" +.IX Subsection "Automatic Reseeding" +Before satisfying a generate request (\fBRAND_DRBG_generate\fR\|(3)), the \s-1DRBG\s0 +reseeds itself automatically, if one of the following conditions holds: +.PP +\&\- the \s-1DRBG\s0 was not instantiated (=seeded) yet or has been uninstantiated. +.PP +\&\- the number of generate requests since the last reseeding exceeds a +certain threshold, the so called \fIreseed_interval\fR. +This behaviour can be disabled by setting the \fIreseed_interval\fR to 0. +.PP +\&\- the time elapsed since the last reseeding exceeds a certain time +interval, the so called \fIreseed_time_interval\fR. +This can be disabled by setting the \fIreseed_time_interval\fR to 0. +.PP +\&\- the \s-1DRBG\s0 is in an error state. +.PP +\&\fBNote\fR: An error state is entered if the entropy source fails while +the \s-1DRBG\s0 is seeding or reseeding. +The last case ensures that the \s-1DRBG\s0 automatically recovers +from the error as soon as the entropy source is available again. +.SS "Manual Reseeding" +.IX Subsection "Manual Reseeding" +In addition to automatic reseeding, the caller can request an immediate +reseeding of the \s-1DRBG\s0 with fresh entropy by setting the +\&\fIprediction resistance\fR parameter to 1 when calling \fBRAND_DRBG_generate\fR\|(3). +.PP +The document [\s-1NIST SP 800\-90C\s0] describes prediction resistance requests +in detail and imposes strict conditions on the entropy sources that are +approved for providing prediction resistance. +Since the default \s-1DRBG\s0 implementation does not have access to such an approved +entropy source, a request for prediction resistance will currently always fail. +In other words, prediction resistance is currently not supported yet by the \s-1DRBG.\s0 +.PP +For the three shared DRBGs (and only for these) there is another way to +reseed them manually: +If \fBRAND_add\fR\|(3) is called with a positive \fIrandomness\fR argument +(or \fBRAND_seed\fR\|(3)), then this will immediately reseed the \s-1DRBG.\s0 +The and \s-1DRBG\s0 will detect this on their next generate +call and reseed, pulling randomness from . +.PP +The last feature has been added to support the common practice used with +previous OpenSSL versions to call \fBRAND_add()\fR before calling \fBRAND_bytes()\fR. +.SS "Entropy Input vs. Additional Data" +.IX Subsection "Entropy Input vs. Additional Data" +The \s-1DRBG\s0 distinguishes two different types of random input: \fIentropy\fR, +which comes from a trusted source, and \fIadditional input\fR', +which can optionally be added by the user and is considered untrusted. +It is possible to add \fIadditional input\fR not only during reseeding, +but also for every generate request. +This is in fact done automatically by \fBRAND_DRBG_bytes\fR\|(3). +.SS "Configuring the Random Seed Source" +.IX Subsection "Configuring the Random Seed Source" +In most cases OpenSSL will automatically choose a suitable seed source +for automatically seeding and reseeding its \s-1DRBG.\s0 In some cases +however, it will be necessary to explicitly specify a seed source during +configuration, using the \-\-with\-rand\-seed option. For more information, +see the \s-1INSTALL\s0 instructions. There are also operating systems where no +seed source is available and automatic reseeding is disabled by default. +.PP +The following two sections describe the reseeding process of the master +\&\s-1DRBG,\s0 depending on whether automatic reseeding is available or not. +.SS "Reseeding the master \s-1DRBG\s0 with automatic seeding enabled" +.IX Subsection "Reseeding the master DRBG with automatic seeding enabled" +Calling \fBRAND_poll()\fR or \fBRAND_add()\fR is not necessary, because the \s-1DRBG\s0 +pulls the necessary entropy from its source automatically. +However, both calls are permitted, and do reseed the \s-1RNG.\s0 +.PP +\&\fBRAND_add()\fR can be used to add both kinds of random input, depending on the +value of the \fBrandomness\fR argument: +.IP "randomness == 0:" 4 +.IX Item "randomness == 0:" +The random bytes are mixed as additional input into the current state of +the \s-1DRBG.\s0 +Mixing in additional input is not considered a full reseeding, hence the +reseed counter is not reset. +.IP "randomness > 0:" 4 +.IX Item "randomness > 0:" +The random bytes are used as entropy input for a full reseeding +(resp. reinstantiation) if the \s-1DRBG\s0 is instantiated +(resp. uninstantiated or in an error state). +The number of random bits required for reseeding is determined by the +security strength of the \s-1DRBG.\s0 Currently it defaults to 256 bits (32 bytes). +It is possible to provide less randomness than required. +In this case the missing randomness will be obtained by pulling random input +from the trusted entropy sources. +.SS "Reseeding the master \s-1DRBG\s0 with automatic seeding disabled" +.IX Subsection "Reseeding the master DRBG with automatic seeding disabled" +Calling \fBRAND_poll()\fR will always fail. +.PP +\&\fBRAND_add()\fR needs to be called for initial seeding and periodic reseeding. +At least 48 bytes (384 bits) of randomness have to be provided, otherwise +the (re\-)seeding of the \s-1DRBG\s0 will fail. This corresponds to one and a half +times the security strength of the \s-1DRBG.\s0 The extra half is used for the +nonce during instantiation. +.PP +More precisely, the number of bytes needed for seeding depend on the +\&\fIsecurity strength\fR of the \s-1DRBG,\s0 which is set to 256 by default. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRAND_DRBG_bytes\fR\|(3), +\&\fBRAND_DRBG_generate\fR\|(3), +\&\fBRAND_DRBG_reseed\fR\|(3), +\&\fBRAND_DRBG_get0_master\fR\|(3), +\&\fBRAND_DRBG_get0_public\fR\|(3), +\&\fBRAND_DRBG_get0_private\fR\|(3), +\&\fBRAND_DRBG_set_reseed_interval\fR\|(3), +\&\fBRAND_DRBG_set_reseed_time_interval\fR\|(3), +\&\fBRAND_DRBG_set_reseed_defaults\fR\|(3), +\&\s-1\fBRAND\s0\fR\|(7), +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man7/RELEASE_NOTES-2.7 b/static/netbsd/man7/RELEASE_NOTES-2.7 new file mode 100644 index 00000000..8632638f --- /dev/null +++ b/static/netbsd/man7/RELEASE_NOTES-2.7 @@ -0,0 +1,175 @@ +The stable Postfix release is called postfix-2.7.x where 2=major +release number, 7=minor release number, x=patchlevel. The stable +release never changes except for patches that address bugs or +emergencies. Patches change the patchlevel and the release date. + +New features are developed in snapshot releases. These are called +postfix-2.8-yyyymmdd where yyyymmdd is the release date (yyyy=year, +mm=month, dd=day). Patches are never issued for snapshot releases; +instead, a new snapshot is released. + +The mail_release_date configuration parameter (format: yyyymmdd) +specifies the release date of a stable release or snapshot release. + +If you upgrade from Postfix 2.5 or earlier, read RELEASE_NOTES-2.6 +before proceeding. + +Major changes - performance +--------------------------- + +[Feature 20100101] Periodic cache cleanup for the verify(8) cache +database. The time between cache cleanup runs is controlled with +the address_verify_cache_cleanup_interval (default: 12h) parameter. +Cache cleanup increases the database access latency, so this should +not be run more often than necessary. + +[Feature 20091109] Improved before-queue filter performance. With +"smtpd_proxy_options = speed_adjust", the Postfix SMTP server +receives the entire message before it connects to a before-queue +content filter. This means you can run more SMTP server processes +with the same number of running content filter processes, and thus, +handle more mail. This feature is off by default until it is proven +to create no new problems. + +This addresses a concern of people in Europe who want to reject all +bad mail with a before-queue filter. The alternative, an after-queue +filter, means they would have to discard bad mail (which is illegal) +or bounce bad mail (which violates good network citizenship). + +NOTE 1: When this feature is turned on, a filter cannot selectively +reject recipients of a multi-recipient message. It is OK to reject +all recipients of the same multi-recipient message, as is deferring +or accepting all recipients of the same multi-recipient message. + +NOTE 2: This feature increases the minimum amount of free queue +space by $message_size_limit. The extra space is needed to save the +message to a temporary file. + +To keep the performance overhead low, the same temporary file is +reused with successive mail transactions (the file is of course +truncated before reuse, so there is no information leakage). + +Major changes - sender reputation +--------------------------------- + +[Feature 20100117] The FILTER action in access maps or header/body_checks +now supports sender reputation schemes that dynamically choose the +SMTP source IP address. Typically, mail is split into classes, and +all mail in class X is sent out from an SMTP client IP address that +is reserved for class X. + +This is implemented by specifying FILTER actions with empty next-hop +destinations in access maps or header/body_checks, and by configuring +in master.cf one Postfix SMTP client for each SMTP source IP address, +where each client has its own "-o myhostname" and "-o smtp_bind_address" +settings. + +[Feature 20091209] sender_dependent_default_transport_maps, a +per-sender override for default_transport. The original motivation +is to use different output channels (with different source IP +addresses) for different sender addresses, in order to keep their +IP-based reputations separate from each other. + +The result value syntax is that of default_transport, not transport_maps. +Thus, sender_dependent_default_transport_maps does not support the +special transport_maps result value syntax for null transport, null +nexthop, or null email address. + +This feature makes sender_dependent_relayhost_maps pretty much +redundant (though sender_dependent_relayhost_maps will often be +easier to use because that is the only thing people want to override). + +Major changes - address verification +------------------------------------ + +[Incompat 20100101] The verify(8) service now uses a persistent +cache by default (address_verify_map = btree:$data_directory/verify_cache). +To disable, specify "address_verify_map =" in main.cf. + +When periodic cache cleanup is enabled (the default), the verify(8) +server now requires that the cache database supports the "delete" +and "sequence" operations. To disable periodic cache cleanup specify +a zero address_verify_cache_cleanup_interval value. + +[Feature 20100101] Periodic cache cleanup for the verify(8) cache +database. The time between cache cleanup runs is controlled with +the address_verify_cache_cleanup_interval (default: 12h) parameter. +Cache cleanup increases the database access latency, so this should +not be run more often than necessary. + +Major changes - content filter +------------------------------ + +[Incompat 20100117] The meaning of an empty filter next-hop destination +has changed (for example, "content_filter = foo:" or "FILTER foo:"). +Postfix now uses the recipient domain, instead of using $myhostname +as in Postfix 2.6 and earlier. To restore the old behavior specify +"default_filter_nexthop = $myhostname", or specify a non-empty +next-hop content filter destination. + +This compatibility option is not needed with SMTP-based content +filters, because these always have an explicit next-hop destination. + +With pipe-based filters that specify no next-hop destination, the +compatibility option restores the FIFO order of deliveries. Without +the compatibility option, the delivery order for filters without +next-hop destination changes to round-robin domain selection. + +[Feature 20100117] The FILTER action in access maps or header/body_checks +now supports sender reputation schemes that dynamically choose the +SMTP source IP address. Typically, mail is split into classes, and +all mail in class X is sent out from an SMTP client IP address that +is reserved for class X. + +This is implemented by specifying FILTER actions with empty next-hop +destinations in access maps or header/body_checks, and by configuring +in master.cf one Postfix SMTP client for each SMTP source IP address, +where each client has its own "-o myhostname" and "-o smtp_bind_address" +settings. + +[Feature 20091109] Improved before-queue filter performance. With +"smtpd_proxy_options = speed_adjust", the Postfix SMTP server +receives the entire message before it connects to a before-queue +content filter. This means you can run more SMTP server processes +with the same number of running content filter processes, and thus, +handle more mail. This feature is off by default until it is proven +to create no new problems. + +This addresses a concern of people in Europe who want to reject all +bad mail with a before-queue filter. The alternative, an after-queue +filter, means they would have to discard bad mail (which is illegal) +or bounce bad mail (which violates good network citizenship). + +NOTE 1: When this feature is turned on, a filter cannot selectively +reject recipients of a multi-recipient message. It is OK to reject +all recipients of the same multi-recipient message, as is deferring +or accepting all recipients of the same multi-recipient message. + +NOTE 2: This feature increases the minimum amount of free queue +space by $message_size_limit. The extra space is needed to save the +message to a temporary file. + +To keep the performance overhead low, the same temporary file is +reused with successive mail transactions (the file is of course +truncated before reuse, so there is no information leakage). + +Major changes - milter +---------------------- + +[Feature 20090606] Support for header checks on Milter-generated +message headers. This can be used, for example, to control mail +flow with Milter-generated headers that carry indicators for badness +or goodness. For details, see the postconf(5) section for +"milter_header_checks". Currently, all header_checks features are +implemented except PREPEND. + +Major changes - multi-instance support +-------------------------------------- + +[Incompat 20090606] The "postmulti -e destroy" command no longer +attempts to remove files that are created AFTER "postmulti -e +create". It still works as expected immediately after creating an +instance by mistake. Trying to automatically remove other files +is too risky because Postfix-owned directories are by design not +trusted. + diff --git a/static/netbsd/man7/RELEASE_NOTES-3.7 b/static/netbsd/man7/RELEASE_NOTES-3.7 new file mode 100644 index 00000000..05ce65ac --- /dev/null +++ b/static/netbsd/man7/RELEASE_NOTES-3.7 @@ -0,0 +1,179 @@ +This is the Postfix 3.7 (stable) release. + +The stable Postfix release is called postfix-3.7.x where 3=major +release number, 7=minor release number, x=patchlevel. The stable +release never changes except for patches that address bugs or +emergencies. Patches change the patchlevel and the release date. + +New features are developed in snapshot releases. These are called +postfix-3.8-yyyymmdd where yyyymmdd is the release date (yyyy=year, +mm=month, dd=day). Patches are never issued for snapshot releases; +instead, a new snapshot is released. + +The mail_release_date configuration parameter (format: yyyymmdd) +specifies the release date of a stable release or snapshot release. + +If you upgrade from Postfix 3.5 or earlier, read RELEASE_NOTES-3.6 +before proceeding. + +License change +--------------- + +This software is distributed with a dual license: in addition to the +historical IBM Public License 1.0, it is now also distributed with the +more recent Eclipse Public License 2.0. Recipients can choose to take +the software under the license of their choice. Those who are more +comfortable with the IPL can continue with that license. + +Major changes - configuration +----------------------------- + +[Feature 20210605] Support to inline the content of small cidr:, +pcre:, and regexp: tables in Postfix parameter values. + +Example: + + smtpd_forbidden_commands = + CONNECT GET POST regexp:{{/^[^A-Z]/ Thrash}} + +This is the new smtpd_forbidden_commands default value. It will +immediately disconnect a remote SMTP client when a command does not +start with a letter (a-z or A-Z). + +The basic syntax is: + +/etc/postfix/main.cf: + parameter = .. map-type:{ { rule-1 }, { rule-2 } .. } .. + +/etc/postfix/master.cf: + .. -o { parameter = .. map-type:{ { rule-1 }, { rule-2 } .. } .. } .. + +where map-type is one of cidr, pcre, or regexp. + +Postfix ignores whitespace after '{' and before '}', and writes each +rule as one text line to a nameless in-memory file: + +in-memory file: + rule-1 + rule-2 + .. + +Postfix parses the result as if it is a file in /etc/postfix. + +Note: if a rule contains $, specify $$ to keep Postfix from trying +to do $name expansion as it evaluates the parameter value. + +Major changes - lmdb support +---------------------------- + +[Feature 20210605] Overhauled the LMDB client's error handling, and +added integration tests for future-proofing. There are no visible +changes in documented behavior. + +Major changes - logging +----------------------- + +[Feature 20210815] To make the maillog_file feature more useful, +the postlog(1) command is now set-gid postdrop, so that unprivileged +programs can use it to write logging through the postlogd(8) daemon. +This required hardening the postlog(1) command against privilege +escalation attacks. DO NOT turn on the set-gid bit with older +postlog(1) implementations. + +Major changes - pcre2 support +----------------------------- + +[Feature 20211127] Support for the pcre2 library (the legacy pcre +library is no longer maintained). The Postfix build procedure +automatically detects if the pcre2 library is installed, and if it +is unavailable, the Postfix build procedure will detect if the +legacy pcre library is installed. See PCRE_README if you need to +build Postfix with a specific library. + +Visible differences: some error messages may have a different text, +and the 'X' pattern flag is no longer supported with pcre2. + +Major changes - security +------------------------ + +[Feature 20220102] Postfix programs now randomize the initial state +of in-memory hash tables, to defend against hash collision attacks +involving a large number of attacker-chosen lookup keys. Presently, +the only known opportunity for such attacks involves remote SMTP +client IPv6 addresses in the anvil(8) service. The attack would +require making hundreds of short-lived connections per second from +thousands of different IP addresses, because the anvil(8) service +drops inactive counters after 100s. Other in-memory hash tables +with attacker-chosen lookup keys are by design limited in size. The +fix is cheap, and therefore implemented for all Postfix in-memory +hash tables. Problem reported by Pascal Junod. + +[Feature 20211030] The postqueue command now sanitizes non-printable +characters (such as newlines) in strings before they are formatted +as json or as legacy output. These outputs are piped into other +programs that are run by administrative users. This closes a +hypothetical opportunity for privilege escalation. + +[Feature 20210815] Updated defense against remote clients or servers +that 'trickle' SMTP or LMTP traffic, based on per-request deadlines +and minimum data rates. + +Per-request deadlines: + +The new {smtpd,smtp,lmtp}_per_request_deadline parameters replace +{smtpd,smtp,lmtp}_per_record_deadline, with backwards compatible +default settings. This defense is enabled by default in the Postfix +SMTP server in case of overload. + +The new smtpd_per_record_deadline parameter limits the combined +time for the Postfix SMTP server to receive a request and to send +a response, while the new {smtp,lmtp}_per_record_deadline parameters +limit the combined time for the Postfix SMTP or LMTP client to send +a request and to receive a response. + +Minimum data rates: + +The new smtpd_min_data_rate parameter enforces a minimum plaintext +data transfer rate for DATA and BDAT requests, but only when +smtpd_per_record_deadline is enabled. After a read operation transfers +N plaintext bytes (possibly after TLS decryption), and after the +DATA or BDAT request deadline is decreased by the elapsed time of +that read operation, the DATA or BDAT request deadline is increased +by N/smtpd_min_data_rate seconds. However, the deadline is never +increased beyond the smtpd_timeout value. The default minimum data +rate is 500 (bytes/second) but is still subject to change. + +The new {smtp,lmtp}_min_data_rate parameters enforce the corresponding +minimum DATA transfer rates for the Postfix SMTP and LMTP client. + +Major changes - tls support +--------------------------- + +[Cleanup 20220121] The new tlsproxy_client_security_level parameter +replaces tlsproxy_client_level, and the new tlsproxy_client_policy_maps +parameter replaces tlsproxy_client_policy. This is for consistent +parameter naming (tlsproxy_client_xxx corresponds to smtp_tls_xxx). +This change was made with backwards-compatible default settings. + +[Feature 20210926] Postfix was updated to support OpenSSL 3.0.0 API +features, and to work around OpenSSL 3.0.0 bit-rot (avoid using +deprecated API features). + +Other code health +----------------- + +[typos] Typo fixes by raf. + +[pre-release checks] Added pre-release checks to detect a) new typos +in documentation and source-code comments, b) missing entries in +the postfix-files file (some documentation would not be installed), +c) missing rules in the postlink script (some text would not have +a hyperlink in documentation), and d) missing map-based $parameter +names in the proxy_read_maps default value (the proxymap daemon +would not automatically authorize some proxied maps). + +[memory stream] Improved support for memory-based streams made it +possible to inline small cidr:, pcre:, and regexp: maps in Postfix +parameter values, and to eliminate some ad-hoc code that converted +tlsproxy(8) protocol data to or from serialized form. + diff --git a/static/netbsd/man7/RSA-PSS.7 b/static/netbsd/man7/RSA-PSS.7 new file mode 100644 index 00000000..7dafd672 --- /dev/null +++ b/static/netbsd/man7/RSA-PSS.7 @@ -0,0 +1,116 @@ +.\" $NetBSD: RSA-PSS.7,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA-PSS 7" +.TH RSA-PSS 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RSA\-PSS \- EVP_PKEY RSA\-PSS algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBRSA\-PSS\fR EVP_PKEY implementation is a restricted version of the RSA +algorithm which only supports signing, verification and key generation +using PSS padding modes with optional parameter restrictions. +.PP +It has associated private key and public key formats. +.PP +This algorithm shares several control operations with the \fBRSA\fR algorithm +but with some restrictions described below. +.SS "Signing and Verification" +.IX Subsection "Signing and Verification" +Signing and verification is similar to the \fBRSA\fR algorithm except the +padding mode is always PSS. If the key in use has parameter restrictions then +the corresponding signature parameters are set to the restrictions: +for example, if the key can only be used with digest SHA256, MGF1 SHA256 +and minimum salt length 32 then the digest, MGF1 digest and salt length +will be set to SHA256, SHA256 and 32 respectively. +.SS "Key Generation" +.IX Subsection "Key Generation" +By default no parameter restrictions are placed on the generated key. +.SH NOTES +.IX Header "NOTES" +The public key format is documented in RFC4055. +.PP +The PKCS#8 private key format used for RSA\-PSS keys is similar to the RSA +format except it uses the \fBid\-RSASSA\-PSS\fR OID and the parameters field, if +present, restricts the key parameters in the same way as the public key. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 4055 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set_rsa_pss_keygen_md\fR\|(3), +\&\fBEVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md\fR\|(3), +\&\fBEVP_PKEY_CTX_set_rsa_pss_keygen_saltlen\fR\|(3), +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/SM2.7 b/static/netbsd/man7/SM2.7 new file mode 100644 index 00000000..6dd6962c --- /dev/null +++ b/static/netbsd/man7/SM2.7 @@ -0,0 +1,219 @@ +.\" $NetBSD: SM2.7,v 1.3 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SM2 7" +.TH SM2 7 "2020-12-10" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SM2 \- Chinese SM2 signature and encryption algorithm support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\s-1SM2\s0\fR algorithm was first defined by the Chinese national standard \s-1GM/T +0003\-2012\s0 and was later standardized by \s-1ISO\s0 as \s-1ISO/IEC 14888.\s0 \fB\s-1SM2\s0\fR is actually +an elliptic curve based algorithm. The current implementation in OpenSSL supports +both signature and encryption schemes via the \s-1EVP\s0 interface. +.PP +When doing the \fB\s-1SM2\s0\fR signature algorithm, it requires a distinguishing identifier +to form the message prefix which is hashed before the real message is hashed. +.SH "NOTES" +.IX Header "NOTES" +\&\fB\s-1SM2\s0\fR signatures can be generated by using the 'DigestSign' series of APIs, for +instance, \fBEVP_DigestSignInit()\fR, \fBEVP_DigestSignUpdate()\fR and \fBEVP_DigestSignFinal()\fR. +Ditto for the verification process by calling the 'DigestVerify' series of APIs. +.PP +There are several special steps that need to be done before computing an \fB\s-1SM2\s0\fR +signature. +.PP +The \fB\s-1EVP_PKEY\s0\fR structure will default to using \s-1ECDSA\s0 for signatures when it is +created. It should be set to \fB\s-1EVP_PKEY_SM2\s0\fR by calling: +.PP +.Vb 1 +\& EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2); +.Ve +.PP +Then an \s-1ID\s0 should be set by calling: +.PP +.Vb 1 +\& EVP_PKEY_CTX_set1_id(pctx, id, id_len); +.Ve +.PP +When calling the \fBEVP_DigestSignInit()\fR or \fBEVP_DigestVerifyInit()\fR functions, a +preallocated \fB\s-1EVP_PKEY_CTX\s0\fR should be assigned to the \fB\s-1EVP_MD_CTX\s0\fR. This is +done by calling: +.PP +.Vb 1 +\& EVP_MD_CTX_set_pkey_ctx(mctx, pctx); +.Ve +.PP +And normally there is no need to pass a \fBpctx\fR parameter to \fBEVP_DigestSignInit()\fR +or \fBEVP_DigestVerifyInit()\fR in such a scenario. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +This example demonstrates the calling sequence for using an \fB\s-1EVP_PKEY\s0\fR to verify +a message with the \s-1SM2\s0 signature algorithm and the \s-1SM3\s0 hash algorithm: +.PP +.Vb 1 +\& #include +\& +\& /* obtain an EVP_PKEY using whatever methods... */ +\& EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2); +\& mctx = EVP_MD_CTX_new(); +\& pctx = EVP_PKEY_CTX_new(pkey, NULL); +\& EVP_PKEY_CTX_set1_id(pctx, id, id_len); +\& EVP_MD_CTX_set_pkey_ctx(mctx, pctx);; +\& EVP_DigestVerifyInit(mctx, NULL, EVP_sm3(), NULL, pkey); +\& EVP_DigestVerifyUpdate(mctx, msg, msg_len); +\& EVP_DigestVerifyFinal(mctx, sig, sig_len) +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_set_alias_type\fR\|(3), +\&\fBEVP_DigestSignInit\fR\|(3), +\&\fBEVP_DigestVerifyInit\fR\|(3), +\&\fBEVP_PKEY_CTX_set1_id\fR\|(3), +\&\fBEVP_MD_CTX_set_pkey_ctx\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2018\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man7/X25519.7 b/static/netbsd/man7/X25519.7 new file mode 100644 index 00000000..dfe004e5 --- /dev/null +++ b/static/netbsd/man7/X25519.7 @@ -0,0 +1,137 @@ +.\" $NetBSD: X25519.7,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X25519 7" +.TH X25519 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X25519, +X448 +\&\- EVP_PKEY X25519 and X448 support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBX25519\fR and \fBX448\fR EVP_PKEY implementation supports key generation and +key derivation using \fBX25519\fR and \fBX448\fR. It has associated private and public +key formats compatible with RFC 8410. +.PP +No additional parameters can be set during key generation. +.PP +The peer public key must be set using \fBEVP_PKEY_derive_set_peer()\fR when +performing key derivation. +.SH NOTES +.IX Header "NOTES" +A context for the \fBX25519\fR algorithm can be obtained by calling: +.PP +.Vb 1 +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X25519, NULL); +.Ve +.PP +For the \fBX448\fR algorithm a context can be obtained by calling: +.PP +.Vb 1 +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X448, NULL); +.Ve +.PP +X25519 or X448 private keys can be set directly using +\&\fBEVP_PKEY_new_raw_private_key\fR\|(3) or loaded from a PKCS#8 private key file +using \fBPEM_read_bio_PrivateKey\fR\|(3) (or similar function). Completely new keys +can also be generated (see the example below). Setting a private key also sets +the associated public key. +.PP +X25519 or X448 public keys can be set directly using +\&\fBEVP_PKEY_new_raw_public_key\fR\|(3) or loaded from a SubjectPublicKeyInfo +structure in a PEM file using \fBPEM_read_bio_PUBKEY\fR\|(3) (or similar function). +.SH EXAMPLES +.IX Header "EXAMPLES" +This example generates an \fBX25519\fR private key and writes it to standard +output in PEM format: +.PP +.Vb 9 +\& #include +\& #include +\& ... +\& EVP_PKEY *pkey = NULL; +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X25519, NULL); +\& EVP_PKEY_keygen_init(pctx); +\& EVP_PKEY_keygen(pctx, &pkey); +\& EVP_PKEY_CTX_free(pctx); +\& PEM_write_PrivateKey(stdout, pkey, NULL, NULL, 0, NULL, NULL); +.Ve +.PP +The key derivation example in \fBEVP_PKEY_derive\fR\|(3) can be used with +\&\fBX25519\fR and \fBX448\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_keygen\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3), +\&\fBEVP_PKEY_derive_set_peer\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/bad.include-toplevel.7 b/static/netbsd/man7/bad.include-toplevel.7 new file mode 100644 index 00000000..386f0166 --- /dev/null +++ b/static/netbsd/man7/bad.include-toplevel.7 @@ -0,0 +1,11 @@ +include-toplevel: include.withclauses.* +include-toplevel: include.withclauses.* +server: + identity: "top 1" + include: include.withoutclauses.* + include-toplevel: include.withclauses.* +include: include.withclauses.* +include-toplevel: include.withclauses.* +server: identity: "top 2" +include-toplevel: include.includetop.withclauses.* +include-toplevel: include.include.withoutclauses.* diff --git a/static/netbsd/man7/bio.7 b/static/netbsd/man7/bio.7 new file mode 100644 index 00000000..a564319a --- /dev/null +++ b/static/netbsd/man7/bio.7 @@ -0,0 +1,168 @@ +.\" $NetBSD: bio.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO 7" +.TH BIO 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +bio \- Basic I/O abstraction +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A BIO is an I/O abstraction, it hides many of the underlying I/O +details from an application. If an application uses a BIO for its +I/O it can transparently handle SSL connections, unencrypted network +connections and file I/O. +.PP +There are two types of BIO, a source/sink BIO and a filter BIO. +.PP +As its name implies a source/sink BIO is a source and/or sink of data, +examples include a socket BIO and a file BIO. +.PP +A filter BIO takes data from one BIO and passes it through to +another, or the application. The data may be left unmodified (for +example a message digest BIO) or translated (for example an +encryption BIO). The effect of a filter BIO may change according +to the I/O operation it is performing: for example an encryption +BIO will encrypt data if it is being written to and decrypt data +if it is being read from. +.PP +BIOs can be joined together to form a chain (a single BIO is a chain +with one component). A chain normally consists of one source/sink +BIO and one or more filter BIOs. Data read from or written to the +first BIO then traverses the chain to the end (normally a source/sink +BIO). +.PP +Some BIOs (such as memory BIOs) can be used immediately after calling +\&\fBBIO_new()\fR. Others (such as file BIOs) need some additional initialization, +and frequently a utility function exists to create and initialize such BIOs. +.PP +If \fBBIO_free()\fR is called on a BIO chain it will only free one BIO resulting +in a memory leak. +.PP +Calling \fBBIO_free_all()\fR on a single BIO has the same effect as calling +\&\fBBIO_free()\fR on it other than the discarded return value. +.PP +Normally the \fItype\fR argument is supplied by a function which returns a +pointer to a BIO_METHOD. There is a naming convention for such functions: +a source/sink BIO typically starts with \fIBIO_s_\fR and +a filter BIO with \fIBIO_f_\fR. +.SS "TCP Fast Open" +.IX Subsection "TCP Fast Open" +TCP Fast Open (RFC7413), abbreviated "TFO", is supported by the BIO +interface since OpenSSL 3.2. TFO is supported in the following operating systems: +.IP \(bu 4 +Linux kernel 3.13 and later, where TFO is enabled by default. +.IP \(bu 4 +Linux kernel 4.11 and later, using TCP_FASTOPEN_CONNECT. +.IP \(bu 4 +FreeBSD 10.3 to 11.4, supports server TFO only. +.IP \(bu 4 +FreeBSD 12.0 and later, supports both client and server TFO. +.IP \(bu 4 +macOS 10.14 and later. +.PP +Each operating system has a slightly different API for TFO. Please +refer to the operating systems\*(Aq API documentation when using +sockets directly. +.SH EXAMPLES +.IX Header "EXAMPLES" +Create a memory BIO: +.PP +.Vb 1 +\& BIO *mem = BIO_new(BIO_s_mem()); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_ctrl\fR\|(3), +\&\fBBIO_f_base64\fR\|(3), \fBBIO_f_buffer\fR\|(3), +\&\fBBIO_f_cipher\fR\|(3), \fBBIO_f_md\fR\|(3), +\&\fBBIO_f_null\fR\|(3), \fBBIO_f_ssl\fR\|(3), +\&\fBBIO_f_readbuffer\fR\|(3), +\&\fBBIO_find_type\fR\|(3), +\&\fBBIO_get_conn_mode\fR\|(3), +\&\fBBIO_new\fR\|(3), +\&\fBBIO_new_bio_pair\fR\|(3), +\&\fBBIO_push\fR\|(3), \fBBIO_read_ex\fR\|(3), +\&\fBBIO_s_accept\fR\|(3), \fBBIO_s_bio\fR\|(3), +\&\fBBIO_s_connect\fR\|(3), \fBBIO_s_fd\fR\|(3), +\&\fBBIO_s_file\fR\|(3), \fBBIO_s_mem\fR\|(3), +\&\fBBIO_s_null\fR\|(3), \fBBIO_s_socket\fR\|(3), +\&\fBBIO_set_callback\fR\|(3), +\&\fBBIO_set_conn_mode\fR\|(3), +\&\fBBIO_set_tfo\fR\|(3), +\&\fBBIO_set_tfo_accept\fR\|(3), +\&\fBBIO_should_retry\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/crypto.7 b/static/netbsd/man7/crypto.7 new file mode 100644 index 00000000..8d233cfa --- /dev/null +++ b/static/netbsd/man7/crypto.7 @@ -0,0 +1,613 @@ +.\" $NetBSD: crypto.7,v 1.9 2025/04/16 15:23:17 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "CRYPTO 7" +.TH CRYPTO 7 2025-02-11 3.0.16 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +crypto \- OpenSSL cryptographic library +.SH SYNOPSIS +.IX Header "SYNOPSIS" +See the individual manual pages for details. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The OpenSSL crypto library (\f(CW\*(C`libcrypto\*(C'\fR) implements a wide range of +cryptographic algorithms used in various Internet standards. The services +provided by this library are used by the OpenSSL implementations of TLS and +CMS, and they have also been used to implement many other third party products +and protocols. +.PP +The functionality includes symmetric encryption, public key cryptography, key +agreement, certificate handling, cryptographic hash functions, cryptographic +pseudo-random number generators, message authentication codes (MACs), key +derivation functions (KDFs), and various utilities. +.SS Algorithms +.IX Subsection "Algorithms" +Cryptographic primitives such as the SHA256 digest, or AES encryption are +referred to in OpenSSL as "algorithms". Each algorithm may have multiple +implementations available for use. For example the RSA algorithm is available as +a "default" implementation suitable for general use, and a "fips" implementation +which has been validated to FIPS standards for situations where that is +important. It is also possible that a third party could add additional +implementations such as in a hardware security module (HSM). +.SS Operations +.IX Subsection "Operations" +Different algorithms can be grouped together by their purpose. For example there +are algorithms for encryption, and different algorithms for digesting data. +These different groups are known as "operations" in OpenSSL. Each operation +has a different set of functions associated with it. For example to perform an +encryption operation using AES (or any other encryption algorithm) you would use +the encryption functions detailed on the \fBEVP_EncryptInit\fR\|(3) page. Or to +perform a digest operation using SHA256 then you would use the digesting +functions on the \fBEVP_DigestInit\fR\|(3) page. +.SS Providers +.IX Subsection "Providers" +A provider in OpenSSL is a component that collects together algorithm +implementations. In order to use an algorithm you must have at least one +provider loaded that contains an implementation of it. OpenSSL comes with a +number of providers and they may also be obtained from third parties. If you +don't load a provider explicitly (either in program code or via config) then the +OpenSSL built-in "default" provider will be automatically loaded. +.SS "Library contexts" +.IX Subsection "Library contexts" +A library context can be thought of as a "scope" within which configuration +options take effect. When a provider is loaded, it is only loaded within the +scope of a given library context. In this way it is possible for different +components of a complex application to each use a different library context and +have different providers loaded with different configuration settings. +.PP +If an application does not explicitly create a library context then the +"default" library context will be used. +.PP +Library contexts are represented by the \fBOSSL_LIB_CTX\fR type. Many OpenSSL API +functions take a library context as a parameter. Applications can always pass +\&\fBNULL\fR for this parameter to just use the default library context. +.PP +The default library context is automatically created the first time it is +needed. This will automatically load any available configuration file and will +initialise OpenSSL for use. Unlike in earlier versions of OpenSSL (prior to +1.1.0) no explicit initialisation steps need to be taken. +.PP +Similarly when the application exits the default library context is +automatically destroyed. No explicit de-initialisation steps need to be taken. +.PP +See \fBOSSL_LIB_CTX\fR\|(3) for more information about library contexts. +See also "ALGORITHM FETCHING". +.SS "Multi-threaded applications" +.IX Subsection "Multi-threaded applications" +As long as OpenSSL has been built with support for threads (the default case +on most platforms) then most OpenSSL \fIfunctions\fR are thread-safe in the sense +that it is safe to call the same function from multiple threads at the same +time. However most OpenSSL \fIdata structures\fR are not thread-safe. For example +the \fBBIO_write\fR\|(3) and \fBBIO_read\fR\|(3) functions are thread safe. However it +would not be thread safe to call \fBBIO_write()\fR from one thread while calling +\&\fBBIO_read()\fR in another where both functions are passed the same \fBBIO\fR object +since both of them may attempt to make changes to the same \fBBIO\fR object. +.PP +There are exceptions to these rules. A small number of functions are not thread +safe at all. Where this is the case this restriction should be noted in the +documentation for the function. Similarly some data structures may be partially +or fully thread safe. For example it is safe to use an \fBOSSL_LIB_CTX\fR in +multiple threads. +.PP +See \fBopenssl\-threads\fR\|(7) for a more detailed discussion on OpenSSL threading +support. +.SH "ALGORITHM FETCHING" +.IX Header "ALGORITHM FETCHING" +In order to use an algorithm an implementation for it must first be "fetched". +Fetching is the process of looking through the available implementations, +applying selection criteria (via a property query string), and finally choosing +the implementation that will be used. +.PP +Two types of fetching are supported by OpenSSL \- explicit fetching and implicit +fetching. +.SS "Property query strings" +.IX Subsection "Property query strings" +When fetching an algorithm it is possible to specify a property query string to +guide the selection process. For example a property query string of +"provider=default" could be used to force the selection to only consider +algorithm implementations in the default provider. +.PP +Property query strings can be specified explicitly as an argument to a function. +It is also possible to specify a default property query string for the whole +library context using the \fBEVP_set_default_properties\fR\|(3) or +\&\fBEVP_default_properties_enable_fips\fR\|(3) functions. Where both +default properties and function specific properties are specified then they are +combined. Function specific properties will override default properties where +there is a conflict. +.PP +See \fBproperty\fR\|(7) for more information about properties. +.SS "Explicit fetching" +.IX Subsection "Explicit fetching" +Users of the OpenSSL libraries never query a provider directly for an algorithm +implementation. Instead, the diverse OpenSSL APIs often have explicit fetching +functions that do the work, and they return an appropriate algorithm object back +to the user. These functions usually have the name \f(CW\*(C`APINAME_fetch\*(C'\fR, where +\&\f(CW\*(C`APINAME\*(C'\fR is the name of the operation. For example \fBEVP_MD_fetch\fR\|(3) can +be used to explicitly fetch a digest algorithm implementation. The user is +responsible for freeing the object returned from the \f(CW\*(C`APINAME_fetch\*(C'\fR function +using \f(CW\*(C`APINAME_free\*(C'\fR when it is no longer needed. +.PP +These fetching functions follow a fairly common pattern, where three +arguments are passed: +.IP "The library context" 4 +.IX Item "The library context" +See \fBOSSL_LIB_CTX\fR\|(3) for a more detailed description. +This may be NULL to signify the default (global) library context, or a +context created by the user. Only providers loaded in this library context (see +\&\fBOSSL_PROVIDER_load\fR\|(3)) will be considered by the fetching function. In case +no provider has been loaded in this library context then the default provider +will be loaded as a fallback (see \fBOSSL_PROVIDER\-default\fR\|(7)). +.IP "An identifier" 4 +.IX Item "An identifier" +For all currently implemented fetching functions this is the algorithm name. +.IP "A property query string" 4 +.IX Item "A property query string" +The property query string used to guide selection of the algorithm +implementation. +.PP +The algorithm implementation that is fetched can then be used with other diverse +functions that use them. For example the \fBEVP_DigestInit_ex\fR\|(3) function takes +as a parameter an \fBEVP_MD\fR object which may have been returned from an earlier +call to \fBEVP_MD_fetch\fR\|(3). +.SS "Implicit fetching" +.IX Subsection "Implicit fetching" +OpenSSL has a number of functions that return an algorithm object with no +associated implementation, such as \fBEVP_sha256\fR\|(3), \fBEVP_aes_128_cbc\fR\|(3), +\&\fBEVP_get_cipherbyname\fR\|(3) or \fBEVP_get_digestbyname\fR\|(3). These are present for +compatibility with OpenSSL before version 3.0 where explicit fetching was not +available. +.PP +When they are used with functions like \fBEVP_DigestInit_ex\fR\|(3) or +\&\fBEVP_CipherInit_ex\fR\|(3), the actual implementation to be used is +fetched implicitly using default search criteria. +.PP +In some cases implicit fetching can also occur when a NULL algorithm parameter +is supplied. In this case an algorithm implementation is implicitly fetched +using default search criteria and an algorithm name that is consistent with +the context in which it is being used. +.PP +Functions that revolve around \fBEVP_PKEY_CTX\fR and \fBEVP_PKEY\fR\|(3), such as +\&\fBEVP_DigestSignInit\fR\|(3) and friends, all fetch the implementations +implicitly. Because these functions involve both an operation type (such as +\&\fBEVP_SIGNATURE\fR\|(3)) and an \fBEVP_KEYMGMT\fR\|(3) for the \fBEVP_PKEY\fR\|(3), they try +the following: +.IP 1. 4 +Fetch the operation type implementation from any provider given a library +context and property string stored in the \fBEVP_PKEY_CTX\fR. +.Sp +If the provider of the operation type implementation is different from the +provider of the \fBEVP_PKEY\fR\|(3)'s \fBEVP_KEYMGMT\fR\|(3) implementation, try to +fetch a \fBEVP_KEYMGMT\fR\|(3) implementation in the same provider as the operation +type implementation and export the \fBEVP_PKEY\fR\|(3) to it (effectively making a +temporary copy of the original key). +.Sp +If anything in this step fails, the next step is used as a fallback. +.IP 2. 4 +As a fallback, try to fetch the operation type implementation from the same +provider as the original \fBEVP_PKEY\fR\|(3)'s \fBEVP_KEYMGMT\fR\|(3), still using the +property string from the \fBEVP_PKEY_CTX\fR. +.SS Performance +.IX Subsection "Performance" +If you perform the same operation many times then it is recommended to use +"Explicit fetching" to prefetch an algorithm once initially, +and then pass this created object to any operations that are currently +using "Implicit fetching". +See an example of Explicit fetching in "USING ALGORITHMS IN APPLICATIONS". +.PP +Prior to OpenSSL 3.0, constant method tables (such as \fBEVP_sha256()\fR) were used +directly to access methods. If you pass one of these convenience functions +to an operation the fixed methods are ignored, and only the name is used to +internally fetch methods from a provider. +.PP +If the prefetched object is not passed to operations, then any implicit +fetch will use the internally cached prefetched object, but it will +still be slower than passing the prefetched object directly. +.PP +Fetching via a provider offers more flexibility, but it is slower than the +old method, since it must search for the algorithm in all loaded providers, +and then populate the method table using provider supplied methods. +Internally OpenSSL caches similar algorithms on the first fetch +(so loading a digest caches all digests). +.PP +The following methods can be used for prefetching: +.IP \fBEVP_MD_fetch\fR\|(3) 4 +.IX Item "EVP_MD_fetch" +.PD 0 +.IP \fBEVP_CIPHER_fetch\fR\|(3) 4 +.IX Item "EVP_CIPHER_fetch" +.IP \fBEVP_KDF_fetch\fR\|(3) 4 +.IX Item "EVP_KDF_fetch" +.IP \fBEVP_MAC_fetch\fR\|(3) 4 +.IX Item "EVP_MAC_fetch" +.IP \fBEVP_KEM_fetch\fR\|(3) 4 +.IX Item "EVP_KEM_fetch" +.IP \fBOSSL_ENCODER_fetch\fR\|(3) 4 +.IX Item "OSSL_ENCODER_fetch" +.IP \fBOSSL_DECODER_fetch\fR\|(3) 4 +.IX Item "OSSL_DECODER_fetch" +.IP \fBEVP_RAND_fetch\fR\|(3) 4 +.IX Item "EVP_RAND_fetch" +.PD +.PP +The following methods are used internally when performing operations: +.IP \fBEVP_KEYMGMT_fetch\fR\|(3) 4 +.IX Item "EVP_KEYMGMT_fetch" +.PD 0 +.IP \fBEVP_KEYEXCH_fetch\fR\|(3) 4 +.IX Item "EVP_KEYEXCH_fetch" +.IP \fBEVP_SIGNATURE_fetch\fR\|(3) 4 +.IX Item "EVP_SIGNATURE_fetch" +.IP \fBOSSL_STORE_LOADER_fetch\fR\|(3) 4 +.IX Item "OSSL_STORE_LOADER_fetch" +.PD +.PP +See \fBOSSL_PROVIDER\-default\fR\|(7), <\fBOSSL_PROVIDER\-fips\fR\|(7)> and +<\fBOSSL_PROVIDER\-legacy\fR\|(7)>for a list of algorithm names that +can be fetched. +.SH "FETCHING EXAMPLES" +.IX Header "FETCHING EXAMPLES" +The following section provides a series of examples of fetching algorithm +implementations. +.PP +Fetch any available implementation of SHA2\-256 in the default context. Note +that some algorithms have aliases. So "SHA256" and "SHA2\-256" are synonymous: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", NULL); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch any available implementation of AES\-128\-CBC in the default context: +.PP +.Vb 3 +\& EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES\-128\-CBC", NULL); +\& ... +\& EVP_CIPHER_free(cipher); +.Ve +.PP +Fetch an implementation of SHA2\-256 from the default provider in the default +context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch an implementation of SHA2\-256 that is not from the default provider in the +default context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider!=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch an implementation of SHA2\-256 from the default provider in the specified +context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(ctx, "SHA2\-256", "provider=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Load the legacy provider into the default context and then fetch an +implementation of WHIRLPOOL from it: +.PP +.Vb 2 +\& /* This only needs to be done once \- usually at application start up */ +\& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); +\& +\& EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Note that in the above example the property string "provider=legacy" is optional +since, assuming no other providers have been loaded, the only implementation of +the "whirlpool" algorithm is in the "legacy" provider. Also note that the +default provider should be explicitly loaded if it is required in addition to +other providers: +.PP +.Vb 3 +\& /* This only needs to be done once \- usually at application start up */ +\& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); +\& OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default"); +\& +\& EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL); +\& EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2\-256", NULL); +\& ... +\& EVP_MD_free(md_whirlpool); +\& EVP_MD_free(md_sha256); +.Ve +.SH "OPENSSL PROVIDERS" +.IX Header "OPENSSL PROVIDERS" +OpenSSL comes with a set of providers. +.PP +The algorithms available in each of these providers may vary due to build time +configuration options. The \fBopenssl\-list\fR\|(1) command can be used to list the +currently available algorithms. +.PP +The names of the algorithms shown from \fBopenssl\-list\fR\|(1) can be used as an +algorithm identifier to the appropriate fetching function. Also see the provider +specific manual pages linked below for further details about using the +algorithms available in each of the providers. +.PP +As well as the OpenSSL providers third parties can also implement providers. +For information on writing a provider see \fBprovider\fR\|(7). +.SS "Default provider" +.IX Subsection "Default provider" +The default provider is built in as part of the \fIlibcrypto\fR library and +contains all of the most commonly used algorithm implementations. Should it be +needed (if other providers are loaded and offer implementations of the same +algorithms), the property query string "provider=default" can be used as a +search criterion for these implementations. The default provider includes all +of the functionality in the base provider below. +.PP +If you don't load any providers at all then the "default" provider will be +automatically loaded. If you explicitly load any provider then the "default" +provider would also need to be explicitly loaded if it is required. +.PP +See \fBOSSL_PROVIDER\-default\fR\|(7). +.SS "Base provider" +.IX Subsection "Base provider" +The base provider is built in as part of the \fIlibcrypto\fR library and contains +algorithm implementations for encoding and decoding for OpenSSL keys. +Should it be needed (if other providers are loaded and offer +implementations of the same algorithms), the property query string +"provider=base" can be used as a search criterion for these implementations. +Some encoding and decoding algorithm implementations are not FIPS algorithm +implementations in themselves but support algorithms from the FIPS provider and +are allowed for use in "FIPS mode". The property query string "fips=yes" can be +used to select such algorithms. +.PP +See \fBOSSL_PROVIDER\-base\fR\|(7). +.SS "FIPS provider" +.IX Subsection "FIPS provider" +The FIPS provider is a dynamically loadable module, and must therefore +be loaded explicitly, either in code or through OpenSSL configuration +(see \fBconfig\fR\|(5)). It contains algorithm implementations that have been +validated according to the FIPS 140\-2 standard. Should it be needed (if other +providers are loaded and offer implementations of the same algorithms), the +property query string "provider=fips" can be used as a search criterion for +these implementations. All approved algorithm implementations in the FIPS +provider can also be selected with the property "fips=yes". The FIPS provider +may also contain non-approved algorithm implementations and these can be +selected with the property "fips=no". +.PP +See \fBOSSL_PROVIDER\-FIPS\fR\|(7) and \fBfips_module\fR\|(7). +.SS "Legacy provider" +.IX Subsection "Legacy provider" +The legacy provider is a dynamically loadable module, and must therefore +be loaded explicitly, either in code or through OpenSSL configuration +(see \fBconfig\fR\|(5)). It contains algorithm implementations that are considered +insecure, or are no longer in common use such as MD2 or RC4. Should it be needed +(if other providers are loaded and offer implementations of the same algorithms), +the property "provider=legacy" can be used as a search criterion for these +implementations. +.PP +See \fBOSSL_PROVIDER\-legacy\fR\|(7). +.SS "Null provider" +.IX Subsection "Null provider" +The null provider is built in as part of the \fIlibcrypto\fR library. It contains +no algorithms in it at all. When fetching algorithms the default provider will +be automatically loaded if no other provider has been explicitly loaded. To +prevent that from happening you can explicitly load the null provider. +.PP +See \fBOSSL_PROVIDER\-null\fR\|(7). +.SH "USING ALGORITHMS IN APPLICATIONS" +.IX Header "USING ALGORITHMS IN APPLICATIONS" +Cryptographic algorithms are made available to applications through use of the +"EVP" APIs. Each of the various operations such as encryption, digesting, +message authentication codes, etc., have a set of EVP function calls that can +be invoked to use them. See the \fBevp\fR\|(7) page for further details. +.PP +Most of these follow a common pattern. A "context" object is first created. For +example for a digest operation you would use an \fBEVP_MD_CTX\fR, and for an +encryption/decryption operation you would use an \fBEVP_CIPHER_CTX\fR. The +operation is then initialised ready for use via an "init" function \- optionally +passing in a set of parameters (using the \fBOSSL_PARAM\fR\|(3) type) to configure how +the operation should behave. Next data is fed into the operation in a series of +"update" calls. The operation is finalised using a "final" call which will +typically provide some kind of output. Finally the context is cleaned up and +freed. +.PP +The following shows a complete example for doing this process for digesting +data using SHA256. The process is similar for other operations such as +encryption/decryption, signatures, message authentication codes, etc. +.PP +.Vb 4 +\& #include +\& #include +\& #include +\& #include +\& +\& int main(void) +\& { +\& EVP_MD_CTX *ctx = NULL; +\& EVP_MD *sha256 = NULL; +\& const unsigned char msg[] = { +\& 0x00, 0x01, 0x02, 0x03 +\& }; +\& unsigned int len = 0; +\& unsigned char *outdigest = NULL; +\& int ret = 1; +\& +\& /* Create a context for the digest operation */ +\& ctx = EVP_MD_CTX_new(); +\& if (ctx == NULL) +\& goto err; +\& +\& /* +\& * Fetch the SHA256 algorithm implementation for doing the digest. We\*(Aqre +\& * using the "default" library context here (first NULL parameter), and +\& * we\*(Aqre not supplying any particular search criteria for our SHA256 +\& * implementation (second NULL parameter). Any SHA256 implementation will +\& * do. +\& * In a larger application this fetch would just be done once, and could +\& * be used for multiple calls to other operations such as EVP_DigestInit_ex(). +\& */ +\& sha256 = EVP_MD_fetch(NULL, "SHA256", NULL); +\& if (sha256 == NULL) +\& goto err; +\& +\& /* Initialise the digest operation */ +\& if (!EVP_DigestInit_ex(ctx, sha256, NULL)) +\& goto err; +\& +\& /* +\& * Pass the message to be digested. This can be passed in over multiple +\& * EVP_DigestUpdate calls if necessary +\& */ +\& if (!EVP_DigestUpdate(ctx, msg, sizeof(msg))) +\& goto err; +\& +\& /* Allocate the output buffer */ +\& outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256)); +\& if (outdigest == NULL) +\& goto err; +\& +\& /* Now calculate the digest itself */ +\& if (!EVP_DigestFinal_ex(ctx, outdigest, &len)) +\& goto err; +\& +\& /* Print out the digest result */ +\& BIO_dump_fp(stdout, outdigest, len); +\& +\& ret = 0; +\& +\& err: +\& /* Clean up all the resources we allocated */ +\& OPENSSL_free(outdigest); +\& EVP_MD_free(sha256); +\& EVP_MD_CTX_free(ctx); +\& if (ret != 0) +\& ERR_print_errors_fp(stderr); +\& return ret; +\& } +.Ve +.SH CONFIGURATION +.IX Header "CONFIGURATION" +By default OpenSSL will load a configuration file when it is first used. This +will set up various configuration settings within the default library context. +Applications that create their own library contexts may optionally configure +them with a config file using the \fBOSSL_LIB_CTX_load_config\fR\|(3) function. +.PP +The configuration file can be used to automatically load providers and set up +default property query strings. +.PP +For information on the OpenSSL configuration file format see \fBconfig\fR\|(5). +.SH "ENCODING AND DECODING KEYS" +.IX Header "ENCODING AND DECODING KEYS" +Many algorithms require the use of a key. Keys can be generated dynamically +using the EVP APIs (for example see \fBEVP_PKEY_Q_keygen\fR\|(3)). However it is often +necessary to save or load keys (or their associated parameters) to or from some +external format such as PEM or DER (see \fBopenssl\-glossary\fR\|(7)). OpenSSL uses +encoders and decoders to perform this task. +.PP +Encoders and decoders are just algorithm implementations in the same way as +any other algorithm implementation in OpenSSL. They are implemented by +providers. The OpenSSL encoders and decoders are available in the default +provider. They are also duplicated in the base provider. +.PP +For information about encoders see \fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3). For +information about decoders see \fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3). +.SH "LIBRARY CONVENTIONS" +.IX Header "LIBRARY CONVENTIONS" +Many OpenSSL functions that "get" or "set" a value follow a naming convention +using the numbers \fB0\fR and \fB1\fR, i.e. "get0", "get1", "set0" and "set1". This +can also apply to some functions that "add" a value to an existing set, i.e. +"add0" and "add1". +.PP +For example the functions: +.PP +.Vb 2 +\& int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); +\& int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj); +.Ve +.PP +In the \fB0\fR version the ownership of the object is passed to (for an add or set) +or retained by (for a get) the parent object. For example after calling the +\&\fBX509_CRL_add0_revoked()\fR function above, ownership of the \fIrev\fR object is passed +to the \fIcrl\fR object. Therefore, after calling this function \fIrev\fR should not +be freed directly. It will be freed implicitly when \fIcrl\fR is freed. +.PP +In the \fB1\fR version the ownership of the object is not passed to or retained by +the parent object. Instead a copy or "up ref" of the object is performed. So +after calling the \fBX509_add1_trust_object()\fR function above the application will +still be responsible for freeing the \fIobj\fR value where appropriate. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\fR\|(1), \fBssl\fR\|(7), \fBevp\fR\|(7), \fBOSSL_LIB_CTX\fR\|(3), \fBopenssl\-threads\fR\|(7), +\&\fBproperty\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-base\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7), \fBOSSL_PROVIDER\-null\fR\|(7), +\&\fBopenssl\-glossary\fR\|(7), \fBprovider\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ct.7 b/static/netbsd/man7/ct.7 new file mode 100644 index 00000000..d032e673 --- /dev/null +++ b/static/netbsd/man7/ct.7 @@ -0,0 +1,112 @@ +.\" $NetBSD: ct.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CT 7" +.TH CT 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ct \- Certificate Transparency +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This library implements Certificate Transparency (CT) verification for TLS +clients, as defined in RFC 6962. This verification can provide some confidence +that a certificate has been publicly logged in a set of CT logs. +.PP +By default, these checks are disabled. They can be enabled using +\&\fBSSL_CTX_enable_ct\fR\|(3) or \fBSSL_enable_ct\fR\|(3). +.PP +This library can also be used to parse and examine CT data structures, such as +Signed Certificate Timestamps (SCTs), or to read a list of CT logs. There are +functions for: +\&\- decoding and encoding SCTs in DER and TLS wire format. +\&\- printing SCTs. +\&\- verifying the authenticity of SCTs. +\&\- loading a CT log list from a CONF file. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_SCT_LIST\fR\|(3), +\&\fBCTLOG_STORE_new\fR\|(3), +\&\fBCTLOG_STORE_get0_log_by_id\fR\|(3), +\&\fBSCT_new\fR\|(3), +\&\fBSCT_print\fR\|(3), +\&\fBSCT_validate\fR\|(3), +\&\fBSCT_validate\fR\|(3), +\&\fBCT_POLICY_EVAL_CTX_new\fR\|(3), +\&\fBSSL_CTX_set_ct_validation_callback\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The ct library was added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/des_modes.7 b/static/netbsd/man7/des_modes.7 new file mode 100644 index 00000000..d2662fd9 --- /dev/null +++ b/static/netbsd/man7/des_modes.7 @@ -0,0 +1,222 @@ +.\" $NetBSD: des_modes.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DES_MODES 7" +.TH DES_MODES 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +des_modes \- the variants of DES and other crypto algorithms of OpenSSL +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Several crypto algorithms for OpenSSL can be used in a number of modes. Those +are used for using block ciphers in a way similar to stream ciphers, among +other things. +.SH OVERVIEW +.IX Header "OVERVIEW" +.SS "Electronic Codebook Mode (ECB)" +.IX Subsection "Electronic Codebook Mode (ECB)" +Normally, this is found as the function \fIalgorithm\fR\fB_ecb_encrypt()\fR. +.IP \(bu 2 +64 bits are enciphered at a time. +.IP \(bu 2 +The order of the blocks can be rearranged without detection. +.IP \(bu 2 +The same plaintext block always produces the same ciphertext block +(for the same key) making it vulnerable to a \*(Aqdictionary attack\*(Aq. +.IP \(bu 2 +An error will only affect one ciphertext block. +.SS "Cipher Block Chaining Mode (CBC)" +.IX Subsection "Cipher Block Chaining Mode (CBC)" +Normally, this is found as the function \fIalgorithm\fR\fB_cbc_encrypt()\fR. +Be aware that \fBdes_cbc_encrypt()\fR is not really DES CBC (it does +not update the IV); use \fBdes_ncbc_encrypt()\fR instead. +.IP \(bu 2 +a multiple of 64 bits are enciphered at a time. +.IP \(bu 2 +The CBC mode produces the same ciphertext whenever the same +plaintext is encrypted using the same key and starting variable. +.IP \(bu 2 +The chaining operation makes the ciphertext blocks dependent on the +current and all preceding plaintext blocks and therefore blocks can not +be rearranged. +.IP \(bu 2 +The use of different starting variables prevents the same plaintext +enciphering to the same ciphertext. +.IP \(bu 2 +An error will affect the current and the following ciphertext blocks. +.SS "Cipher Feedback Mode (CFB)" +.IX Subsection "Cipher Feedback Mode (CFB)" +Normally, this is found as the function \fIalgorithm\fR\fB_cfb_encrypt()\fR. +.IP \(bu 2 +a number of bits (j) <= 64 are enciphered at a time. +.IP \(bu 2 +The CFB mode produces the same ciphertext whenever the same +plaintext is encrypted using the same key and starting variable. +.IP \(bu 2 +The chaining operation makes the ciphertext variables dependent on the +current and all preceding variables and therefore j\-bit variables are +chained together and can not be rearranged. +.IP \(bu 2 +The use of different starting variables prevents the same plaintext +enciphering to the same ciphertext. +.IP \(bu 2 +The strength of the CFB mode depends on the size of k (maximal if +j == k). In my implementation this is always the case. +.IP \(bu 2 +Selection of a small value for j will require more cycles through +the encipherment algorithm per unit of plaintext and thus cause +greater processing overheads. +.IP \(bu 2 +Only multiples of j bits can be enciphered. +.IP \(bu 2 +An error will affect the current and the following ciphertext variables. +.SS "Output Feedback Mode (OFB)" +.IX Subsection "Output Feedback Mode (OFB)" +Normally, this is found as the function \fIalgorithm\fR\fB_ofb_encrypt()\fR. +.IP \(bu 2 +a number of bits (j) <= 64 are enciphered at a time. +.IP \(bu 2 +The OFB mode produces the same ciphertext whenever the same +plaintext enciphered using the same key and starting variable. More +over, in the OFB mode the same key stream is produced when the same +key and start variable are used. Consequently, for security reasons +a specific start variable should be used only once for a given key. +.IP \(bu 2 +The absence of chaining makes the OFB more vulnerable to specific attacks. +.IP \(bu 2 +The use of different start variables values prevents the same +plaintext enciphering to the same ciphertext, by producing different +key streams. +.IP \(bu 2 +Selection of a small value for j will require more cycles through +the encipherment algorithm per unit of plaintext and thus cause +greater processing overheads. +.IP \(bu 2 +Only multiples of j bits can be enciphered. +.IP \(bu 2 +OFB mode of operation does not extend ciphertext errors in the +resultant plaintext output. Every bit error in the ciphertext causes +only one bit to be in error in the deciphered plaintext. +.IP \(bu 2 +OFB mode is not self\-synchronizing. If the two operation of +encipherment and decipherment get out of synchronism, the system needs +to be re\-initialized. +.IP \(bu 2 +Each re\-initialization should use a value of the start variable +different from the start variable values used before with the same +key. The reason for this is that an identical bit stream would be +produced each time from the same parameters. This would be +susceptible to a \*(Aqknown plaintext\*(Aq attack. +.SS "Triple ECB Mode" +.IX Subsection "Triple ECB Mode" +Normally, this is found as the function \fIalgorithm\fR\fB_ecb3_encrypt()\fR. +.IP \(bu 2 +Encrypt with key1, decrypt with key2 and encrypt with key3 again. +.IP \(bu 2 +As for ECB encryption but increases the key length to 168 bits. +There are theoretic attacks that can be used that make the effective +key length 112 bits, but this attack also requires 2^56 blocks of +memory, not very likely, even for the NSA. +.IP \(bu 2 +If both keys are the same it is equivalent to encrypting once with +just one key. +.IP \(bu 2 +If the first and last key are the same, the key length is 112 bits. +There are attacks that could reduce the effective key strength +to only slightly more than 56 bits, but these require a lot of memory. +.IP \(bu 2 +If all 3 keys are the same, this is effectively the same as normal +ecb mode. +.SS "Triple CBC Mode" +.IX Subsection "Triple CBC Mode" +Normally, this is found as the function \fIalgorithm\fR\fB_ede3_cbc_encrypt()\fR. +.IP \(bu 2 +Encrypt with key1, decrypt with key2 and then encrypt with key3. +.IP \(bu 2 +As for CBC encryption but increases the key length to 168 bits with +the same restrictions as for triple ecb mode. +.SH NOTES +.IX Header "NOTES" +This text was been written in large parts by Eric Young in his original +documentation for SSLeay, the predecessor of OpenSSL. In turn, he attributed +it to: +.PP +.Vb 5 +\& AS 2805.5.2 +\& Australian Standard +\& Electronic funds transfer \- Requirements for interfaces, +\& Part 5.2: Modes of operation for an n\-bit block cipher algorithm +\& Appendix A +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBF_encrypt\fR\|(3), \fBDES_crypt\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/editline.7 b/static/netbsd/man7/editline.7 new file mode 100644 index 00000000..eb7a9e89 --- /dev/null +++ b/static/netbsd/man7/editline.7 @@ -0,0 +1,941 @@ +.\" $NetBSD: editline.7,v 1.7 2026/02/01 01:52:58 uwe Exp $ +.\" $OpenBSD: editline.7,v 1.1 2016/04/20 01:11:45 schwarze Exp $ +.\" +.\" Copyright (c) 2016 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd January 31, 2026 +.Dt EDITLINE 7 +.Os +.Sh NAME +.Nm editline +.Nd line editing user interface +.Sh DESCRIPTION +When a program using the +.Xr editline 3 +library prompts for an input string using the function +.Xr el_wgets 3 , +it reads characters from the terminal. +Invalid input bytes that do not form characters are silently +discarded. +For each character read, one editor command is executed. +The mapping of input characters to editor commands depends on the +editing mode. +There are three editing modes: vi insert mode, vi command mode, +and emacs mode. +The default is vi insert mode. +The program can switch the default to emacs mode by using the +.Xr el_set 3 +or +.Xr el_parse 3 +functions, and the user can switch to emacs mode either in the +.Xr editrc 5 +configuration file or interactively with the +.Ic ed-command +editor command, in all three cases executing the +.Ic bind Fl e +builtin command. +.Pp +If trying to read from the terminal results in end of file or an +error, the library signals end of file to the program and does not +return a string. +.Ss Input character bindings +All default bindings described below can be overridden by individual +programs and can be changed with the +.Xr editrc 5 +.Ic bind +builtin command. +.Pp +In the following tables, +.Sq Ctrl- +indicates a character with the bit 0x40 flipped, and +.Sq Meta- +indicates a character with the bit 0x80 set. +In vi insert mode and in emacs mode, all Meta-characters considered +printable by the current +.Xr locale 1 +are bound to +.Ic ed-insert +instead of to the editor command listed below. +Consequently, in UTF-8 mode, most of the Meta-characters are not +directly accessible because their code points are occupied by +printable Unicode characters, and Meta-characters are usually input +using the +.Ic em-meta-next +editor command. +For example, to enter +.Sq Meta-B +in order to call the +.Ic ed-prev-word +editor command in emacs mode, call +.Ic em-meta-next +by pressing and releasing the escape key (or equivalently, Ctrl-[), +then press and release the +.Sq B +key. +If you have configured a Meta-key on your keyboard, for example +with +.Ql setxkbmap -option altwin:left_meta_win , +the Ctrl-Meta-characters are directly accessible. +For example, to enter +.Sq Ctrl-Meta-H +in order to call the +.Ic ed-delete-prev-word +editor command in emacs mode, hold down the keys +.Sq Ctrl , +.Sq Meta , +and +.Sq H +at the same time. +Alternatively, press and release the escape key, then press and +release +.Sq Ctrl-H . +.Pp +In vi input mode, input characters are bound to the following editor +commands by default: +.Bl -column -offset indent "Ctrl-Z, TSTP" "ed-search-next-history" +.It Ctrl-D, EOF Ta Ic vi-list-or-eof +.It Ctrl-H, BS Ta Ic vi-delete-prev-char +.It Ctrl-J, LF Ta Ic ed-newline +.It Ctrl-M, CR Ta Ic ed-newline +.It Ctrl-Q Ta Ic ed-tty-start-output +.It Ctrl-S Ta Ic ed-tty-stop-output +.It Ctrl-U Ta Ic vi-kill-line-prev +.It Ctrl-V Ta Ic ed-quoted-insert +.It Ctrl-W Ta Ic ed-delete-prev-word +.It Ctrl-[, ESC Ta Ic vi-command-mode +.It Ctrl-\e, QUIT Ta Ic ed-tty-sigquit +.It Ctrl-?, DEL Ta Ic vi-delete-prev-char +.El +.Pp +All other input characters except the NUL character (Ctrl-@) are +bound to +.Ic ed-insert . +.Pp +In vi command mode, input characters are bound to the following +editor commands by default: +.Bl -column -offset indent "Ctrl-Z, TSTP" "ed-search-next-history" +.It Ctrl-A Ta Ic ed-move-to-beg +.It Ctrl-C, INT Ta Ic ed-tty-sigint +.It Ctrl-E Ta Ic ed-move-to-end +.It Ctrl-H, BS Ta Ic ed-delete-prev-char +.It Ctrl-J, LF Ta Ic ed-newline +.It Ctrl-K Ta Ic ed-kill-line +.It Ctrl-L, FF Ta Ic ed-clear-screen +.It Ctrl-M, CR Ta Ic ed-newline +.It Ctrl-N Ta Ic ed-next-history +.It Ctrl-O Ta Ic ed-tty-flush-output +.It Ctrl-P Ta Ic ed-prev-history +.It Ctrl-Q Ta Ic ed-tty-start-output +.It Ctrl-R Ta Ic ed-redisplay +.It Ctrl-S Ta Ic ed-tty-stop-output +.It Ctrl-U Ta Ic vi-kill-line-prev +.It Ctrl-W Ta Ic ed-delete-prev-word +.It Ctrl-[, ESC Ta Ic em-meta-next +.It Ctrl-\e, QUIT Ta Ic ed-tty-sigquit +.It Space Ta Ic ed-next-char +.It # Ta Ic vi-comment-out +.It $ Ta Ic ed-move-to-end +.It % Ta Ic vi-match +.It + Ta Ic ed-next-history +.It \&, Ta Ic vi-repeat-prev-char +.It - Ta Ic ed-prev-history +.It \&. Ta Ic vi-redo +.It / Ta Ic vi-search-prev +.It 0 Ta Ic vi-zero +.It 1 to 9 Ta Ic ed-argument-digit +.It \&: Ta Ic ed-command +.It \&; Ta Ic vi-repeat-next-char +.It \&? Ta Ic vi-search-next +.It @ Ta Ic vi-alias +.It A Ta Ic vi-add-at-eol +.It B Ta Ic vi-prev-big-word +.It C Ta Ic vi-change-to-eol +.It D Ta Ic ed-kill-line +.It E Ta Ic vi-end-big-word +.It F Ta Ic vi-prev-char +.It G Ta Ic vi-to-history-line +.It I Ta Ic vi-insert-at-bol +.It J Ta Ic ed-search-next-history +.It K Ta Ic ed-search-prev-history +.It N Ta Ic vi-repeat-search-prev +.It O Ta Ic ed-sequence-lead-in +.It P Ta Ic vi-paste-prev +.It R Ta Ic vi-replace-mode +.It S Ta Ic vi-substitute-line +.It T Ta Ic vi-to-prev-char +.It U Ta Ic vi-undo-line +.It W Ta Ic vi-next-big-word +.It X Ta Ic ed-delete-prev-char +.It Y Ta Ic vi-yank-end +.It \&[ Ta Ic ed-sequence-lead-in +.It ^ Ta Ic ed-move-to-beg +.It _ Ta Ic vi-history-word +.It a Ta Ic vi-add +.It b Ta Ic vi-prev-word +.It c Ta Ic vi-change-meta +.It d Ta Ic vi-delete-meta +.It e Ta Ic vi-end-word +.It f Ta Ic vi-next-char +.It h Ta Ic ed-prev-char +.It i Ta Ic vi-insert +.It j Ta Ic ed-next-history +.It k Ta Ic ed-prev-history +.It l Ta Ic ed-next-char +.It n Ta Ic vi-repeat-search-next +.It p Ta Ic vi-paste-next +.It r Ta Ic vi-replace-char +.It s Ta Ic vi-substitute-char +.It t Ta Ic vi-to-next-char +.It u Ta Ic vi-undo +.It v Ta Ic vi-histedit +.It w Ta Ic vi-next-word +.It x Ta Ic ed-delete-next-char +.It y Ta Ic vi-yank +.It \&| Ta Ic vi-to-column +.It ~ Ta Ic vi-change-case +.It Ctrl-?, DEL Ta Ic ed-delete-prev-char +.It Meta-O Ta Ic ed-sequence-lead-in +.It Meta-[ Ta Ic ed-sequence-lead-in +.El +.Pp +In emacs mode, input characters are bound to the following editor +commands by default: +.Bl -column -offset indent "Ctrl-Z, TSTP" "ed-search-next-history" +.It 0 to 9 Ta Ic ed-digit +.It Ctrl-@, NUL Ta Ic em-set-mark +.It Ctrl-A Ta Ic ed-move-to-beg +.It Ctrl-B Ta Ic ed-prev-char +.It Ctrl-C, INT Ta Ic ed-tty-sigint +.It Ctrl-D, EOF Ta Ic em-delete-or-list +.It Ctrl-E Ta Ic ed-move-to-end +.It Ctrl-F Ta Ic ed-next-char +.It Ctrl-H, BS Ta Ic em-delete-prev-char +.It Ctrl-J, LF Ta Ic ed-newline +.It Ctrl-K Ta Ic ed-kill-line +.It Ctrl-L, FF Ta Ic ed-clear-screen +.It Ctrl-M, CR Ta Ic ed-newline +.It Ctrl-N Ta Ic ed-next-history +.It Ctrl-O Ta Ic ed-tty-flush-output +.It Ctrl-P Ta Ic ed-prev-history +.It Ctrl-Q Ta Ic ed-tty-start-output +.It Ctrl-R Ta Ic ed-redisplay +.It Ctrl-S Ta Ic ed-tty-stop-output +.It Ctrl-T Ta Ic ed-transpose-chars +.It Ctrl-U Ta Ic ed-kill-line +.It Ctrl-V Ta Ic ed-quoted-insert +.It Ctrl-W Ta Ic em-kill-region +.It Ctrl-X Ta Ic ed-sequence-lead-in +.It Ctrl-Y Ta Ic em-yank +.It Ctrl-Z, TSTP Ta Ic ed-tty-sigtstp +.It Ctrl-[, ESC Ta Ic em-meta-next +.It Ctrl-\e, QUIT Ta Ic ed-tty-sigquit +.It Ctrl-] Ta Ic ed-tty-dsusp +.It Ctrl-?, DEL Ta Ic em-delete-prev-char +.It Ctrl-Meta-H Ta Ic ed-delete-prev-word +.It Ctrl-Meta-L Ta Ic ed-clear-screen +.It Ctrl-Meta-_ Ta Ic em-copy-prev-word +.It Meta-0 to 9 Ta Ic ed-argument-digit +.It Meta-B Ta Ic ed-prev-word +.It Meta-C Ta Ic em-capitol-case +.It Meta-D Ta Ic em-delete-next-word +.It Meta-F Ta Ic em-next-word +.It Meta-L Ta Ic em-lower-case +.It Meta-N Ta Ic ed-search-next-history +.It Meta-O Ta Ic ed-sequence-lead-in +.It Meta-P Ta Ic ed-search-prev-history +.It Meta-U Ta Ic em-upper-case +.It Meta-W Ta Ic em-copy-region +.It Meta-X Ta Ic ed-command +.It Meta-[ Ta Ic ed-sequence-lead-in +.It Meta-b Ta Ic ed-prev-word +.It Meta-c Ta Ic em-capitol-case +.It Meta-d Ta Ic em-delete-next-word +.It Meta-f Ta Ic em-next-word +.It Meta-l Ta Ic em-lower-case +.It Meta-n Ta Ic ed-search-next-history +.It Meta-p Ta Ic ed-search-prev-history +.It Meta-u Ta Ic em-upper-case +.It Meta-w Ta Ic em-copy-region +.It Meta-x Ta Ic ed-command +.It Ctrl-Meta-? Ta Ic ed-delete-prev-word +.El +.Pp +The remaining +.Xr ascii 7 +characters in the range 0x20 to 0x7e are bound to +.Ic ed-insert . +.Pp +If standard output is not connected to a terminal device +or +.Xr el_set 3 +was used to set +.Dv EL_EDITMODE +to 0, all input character bindings are disabled and all characters +typed are appended to the edit buffer. +In that case, the edit buffer is returned to the program after a +newline or carriage return character is typed, or after the first +character typed if +.Xr el_set 3 +was used to set +.Dv EL_UNBUFFERED +to non-zero. +.Ss Editor commands +Most editor commands accept an optional argument. +The argument is entered by prefixing the editor command with one +or more of the editor commands +.Ic ed-argument-digit , +.Ic ed-digit , +.Ic em-universal-argument , +or +.Ic vi-zero . +When an argument is not provided, it defaults to 1. +For most editor commands, the effect of an argument is to repeatedly +execute the command that number of times. +.Pp +When talking about a character string from a left character to a +right character, the left character is included in the string, while +the right character is not included. +.Pp +If an editor command causes an error, the input character is discarded, +no action occurs, and the terminal bell is rung. +In case of a non-fatal error, the terminal bell is also rung, +but the editor command takes effect anyway. +.Pp +In the following list, the default key bindings are listed after +each editor command. +.Bl -tag -width 4n +.It Ic ed-argument-digit Pq vi command: 1 to 9; emacs: Meta-0 to Meta-9 +If in argument input mode, append the input digit to the argument +being read. +Otherwise, switch to argument input mode and use the input digit +as the most significant digit of the argument. +It is an error if the input character is not a digit or if the +existing argument is already greater than a million. +.It Ic ed-clear-screen Pq vi command: Ctrl-L; emacs: Ctrl-L, Ctrl-Meta-L +Clear the screen and display the edit buffer at the top. +Ignore any argument. +.It Ic ed-command Pq vi command: So \&: Sc ; emacs: Meta-X, Meta-x +Read a line from the terminal bypassing the normal line editing +functionality and execute that line as an +.Xr editrc 5 +builtin command. +If in vi command mode, also switch back to vi insert mode. +Ignore any argument. +.It Ic ed-delete-next-char Pq vi command: x +Delete the character at the cursor position. +With an argument, delete that number of characters. +In emacs mode, it is an error if the cursor is at the end of the +edit buffer. +In vi mode, the last character in the edit buffer is deleted in +that case, and it is an error if the buffer is empty. +.It Ic ed-delete-prev-char Pq vi command: X, Ctrl-H, BS, Ctrl-?, DEL +Delete the character to the left of the cursor position. +With an argument, delete that number of characters. +It is an error if the cursor is at the beginning of the edit buffer. +.It Ic ed-delete-prev-word Pq vi: Ctrl-W; emacs: Ctrl-Meta-H, Ctrl-Meta-? +Move to the left to the closest beginning of a word, delete the +string from that position to the cursor, and save it to the cut +buffer. +With an argument, delete that number of words. +It is an error if the cursor is at the beginning of the edit buffer. +.It Ic ed-digit Pq emacs: 0 to 9 +If in argument input mode, append the input digit to the argument +being read. +Otherwise, call +.Ic ed-insert . +It is an error if the input character is not a digit or if the +existing argument is already greater than a million. +.It Ic ed-end-of-file Pq not bound by default +Discard the edit buffer and indicate end of file to the program. +Ignore any argument. +.It Ic ed-ignore Pq various +Discard the input character and do nothing. +.It Ic ed-insert Pq vi input: almost all; emacs: printable characters +In insert mode, insert the input character left of the cursor +position. +In replace mode, overwrite the character at the cursor and move the +cursor to the right by one character position. +Accept an argument to do this repeatedly. +It is an error if the input character is the NUL character (Ctrl-@). +Failure to enlarge the edit buffer also results in an error. +.It Ic ed-kill-line Pq vi command: D, Ctrl-K; emacs: Ctrl-K, Ctrl-U +Delete the string from the cursor position to the end of the line +and save it to the cut buffer. +Ignore any argument. +.It Ic ed-move-to-beg Pq vi command: ^, Ctrl-A; emacs: Ctrl-A +In vi mode, move the cursor to the first non-space character in the +edit buffer. +In emacs mode, move the cursor to the beginning of the edit buffer. +Ignore any argument. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +.It Ic ed-move-to-end Pq vi command: $, Ctrl-E; emacs: Ctrl-E +Move the cursor to the end of the edit buffer. +Ignore any argument. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +.It Ic ed-newline Pq all modes: Ctrl-J, LF, Ctrl-M, CR +Append a newline character to the edit buffer and return the edit +buffer to the program. +Ignore any argument. +.It Ic ed-next-char Pq vi command: Space, l; emacs: Ctrl-F +Move the cursor one character position to the right. +With an argument, move by that number of characters. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +It is an error if the cursor is already at the end of the edit +buffer. +.It Ic ed-next-history Pq vi command: j, +, Ctrl-N; emacs: Ctrl-N +Replace the edit buffer with the next history line. +That line is older than the current line. +With an argument, go forward by that number of history lines. +It is a non-fatal error to advance by more lines than are available. +.It Ic ed-next-line Pq not bound by default +Move the cursor down one line. +With an argument, move down by that number of lines. +It is an error if the edit buffer does not contain enough newline +characters to the right of the cursor position. +.It Ic ed-prev-char Pq vi command: h; emacs: Ctrl-B +Move the cursor one character position to the left. +With an argument, move by that number of characters. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +It is an error if the cursor is already at the beginning of the +edit buffer. +.It Ic ed-prev-history Pq vi command: k, -, Ctrl-P; emacs: Ctrl-P +Replace the edit buffer with the previous history line. +That line is newer than the current line. +With an argument, go back by that number of lines. +It is a non-fatal error to back up by more lines than are available. +.It Ic ed-prev-line Pq not bound by default +Move the cursor up one line. +With an argument, move up by that number of lines. +It is an error if the edit buffer does not contain enough newline +characters to the left of the cursor position. +.It Ic ed-prev-word Pq emacs: Meta-B, Meta-b +Move the cursor to the left to the closest beginning of a word. +With an argument, repeat that number of times. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +It is an error if the cursor is already at the beginning of the +edit buffer. +.It Ic ed-quoted-insert Pq vi insert, emacs: Ctrl-V +Read one character from the terminal bypassing the normal line +editing functionality and call +.Ic ed-insert +on it. +If trying to read the character returns end of file or an error, +call +.Ic ed-end-of-file +instead. +.It Ic ed-redisplay Pq vi command, emacs: Ctrl-R +Redisplay everything. +Ignore any argument. +.It Ic ed-search-next-history Pq vi command: J; emacs: Meta-N, Meta-n +Replace the edit buffer with the next matching history entry. +.It Ic ed-search-prev-history Pq vi command: K; emacs: Meta-P, Meta-p +Replace the edit buffer with the previous matching history entry. +.It Ic ed-sequence-lead-in Pq vi cmd: O, \&[; emacs: Ctrl-X;\ + both: Meta-O, Meta-[ +Call a macro. +See the section about +.Sx Macros +below for details. +.It Ic ed-start-over Pq not bound by default +Discard the contents of the edit buffer and start from scratch. +Ignore any argument. +.It Ic ed-transpose-chars Pq emacs: Ctrl-T +Exchange the character at the cursor position with the one to the +left of it and move the cursor to the character to the right of the +two exchanged characters. +Ignore any argument. +It is an error if the cursor is at the beginning of the edit buffer +or if the edit buffer contains less than two characters. +.It Ic ed-unassigned Pq all characters not listed +This editor command always results in an error. +.It Ic em-capitol-case Pq emacs: Meta-C, Meta-c +Capitalize the string from the cursor to the end of the current +word. +That is, if it contains at least one alphabetic character, convert +the first alphabetic character to upper case, and convert all +characters to the right of it to lower case. +In any case, move the cursor to the next character after the end +of the current word. +.It Ic em-copy-prev-word Pq emacs: Ctrl-Meta-_ +Copy the string from the beginning of the current word to the cursor +and insert it to the left of the cursor. +Move the cursor to the character after the inserted string. +It is an error if the cursor is at the beginning of the edit buffer. +.It Ic em-copy-region Pq emacs: Meta-W, Meta-w +Copy the string from the cursor to the mark to the cut buffer. +It is an error if the mark is not set. +.It Ic em-delete-next-word Pq emacs: Meta-D, Meta-d +Delete the string from the cursor to the end of the current word +and save it to the cut buffer. +It is an error if the cursor is at the end of the edit buffer. +.It Ic em-delete-or-list Pq emacs: Ctrl-D, EOF +If the cursor is not at the end of the line, delete the character +at the cursor. +If the edit buffer is empty, indicate end of file to the program. +It is an error if the cursor is at the end of the edit buffer and +the edit buffer is not empty. +.It Ic em-delete-prev-char Pq emacs: Ctrl-H, BS, Ctrl-?, DEL +Delete the character to the left of the cursor. +It is an error if the cursor is at the beginning of the edit buffer. +.It Ic em-exchange-mark Pq not bound by default +Exchange the cursor and the mark. +.It Ic em-gosmacs-transpose Pq not bound by default +Exchange the two characters to the left of the cursor. +It is an error if the cursor is on the first or second character +of the edit buffer. +.It Ic em-inc-search-next Pq not bound by default +Emacs incremental next search. +.It Ic em-inc-search-prev Pq not bound by default +Emacs incremental reverse search. +.It Ic em-kill-line Pq not bound by default +Delete the entire contents of the edit buffer and save it to the +cut buffer. +.It Ic em-kill-region Pq emacs: Ctrl-W +Delete the string from the cursor to the mark and save it to the +cut buffer. +It is an error if the mark is not set. +.It Ic em-lower-case Pq emacs: Meta-L, Meta-l +Convert the characters from the cursor to the end of the current +word to lower case. +.It Ic em-meta-next Pq vi command, emacs: Ctrl-[, ESC +Set the bit 0x80 on the next character typed. +Unless the resulting code point is printable, holding down the +.Sq Meta- +key while typing that character is a simpler way to achieve the +same effect. +.It Ic em-next-word Pq Meta-F, Meta-f +Move the cursor to the end of the current word. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +It is an error if the cursor is already at the end of the edit +buffer. +.It Ic em-set-mark Pq emacs: Ctrl-Q, NUL +Set the mark at the current cursor position. +.It Ic em-toggle-overwrite Pq insert +Switch from insert to overwrite mode or vice versa. +.It Ic em-universal-argument Pq not bound by default +If in argument input mode, multiply the argument by 4. +Otherwise, switch to argument input mode and set the argument to 4. +It is an error if the existing argument is already greater than a +million. +.It Ic em-upper-case Pq emacs: Meta-U, Meta-u +Convert the characters from the cursor to the end of the current +word to upper case. +.It Ic em-yank Pq emacs: Ctrl-Y +Paste the cut buffer to the left of the cursor. +.It Ic vi-add Pq vi command: a +Switch to vi insert mode. +Unless the cursor is already at the end of the edit buffer, move +it one character position to the right. +.It Ic vi-add-at-eol Pq vi command: A +Switch to vi insert mode and move the cursor to the end of the edit +buffer. +.It Ic vi-alias Pq vi command: @ +If an alias function was defined by calling the +.Xr el_set 3 +or +.Xr el_wset 3 +function with the argument +.Dv EL_ALIAS_TEXT , +read one character from the terminal bypassing the normal line +editing functionality, call the alias function passing the argument that was specified with +.Dv EL_ALIAS_TEXT +as the first argument and the character read, with an underscore +prepended, as the second argument, and pass the string returned +from the alias function to +.Xr el_wpush 3 . +It is an error if no alias function is defined or if trying to read +the character results in end of file or an error. +.It Ic vi-change-case Pq vi command: ~ +Change the case of the character at the cursor and move the cursor +one character position to the right. +It is an error if the cursor is already at the end of the edit +buffer. +.It Ic vi-change-meta Pq vi command: c +Delete the string from the cursor to the position specified by the +following movement command and save a copy of it to the cut buffer. +When given twice in a row, instead delete the whole contents of the +edit buffer and save a copy of it to the cut buffer. +In either case, switch to vi insert mode after that. +.It Ic vi-change-to-eol Pq vi command: C +Delete the string from the cursor position to the end of the line +and save it to the cut buffer, then switch to vi insert mode. +.It Ic vi-command-mode Pq vi insert: Ctrl-[, ESC +Discard pending actions and arguments and switch to vi command mode. +Unless the cursor is already at the beginning of the edit buffer, +move it to the left by one character position. +.It Ic vi-comment-out Pq vi command: # +Insert a +.Sq # +character at the beginning of the edit buffer and return the edit +buffer to the program. +.It Ic vi-delete-meta Pq vi command: d +Delete the string from the cursor to the position specified by the +following movement command and save a copy of it to the cut buffer. +When given twice in a row, instead delete the whole contents of the +edit buffer and save a copy of it to the cut buffer. +.It Ic vi-delete-prev-char Pq vi insert: Ctrl-H, BS, Ctrl-?, DEL +Delete the character to the left of the cursor. +It is an error if the cursor is already at the beginning of the +edit buffer. +.It Ic vi-end-big-word Pq vi command: E +Move the cursor to the end of the current space delimited word. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +It is an error if the cursor is already at the end of the edit +buffer. +.It Ic vi-end-word Pq vi command: e +Move the cursor to the end of the current word. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +It is an error if the cursor is already at the end of the edit +buffer. +.It Ic vi-history-word Pq vi command: _ +Insert the first word from the most recent history entry after the +cursor, move the cursor after to the character after the inserted +word, and switch to vi insert mode. +It is an error if there is no history entry or the most recent +history entry is empty. +.It Ic vi-histedit Pq vi command: v +Edit the buffer with the editor and return the edit buffer to the program. +The editor specified by the +.Ev EDITOR +environment variable will be invoked instead of the default editor +.Xr vi 1 . +.It Ic vi-insert Pq vi command: i +Enter insert mode. +.It Ic vi-insert-at-bol Pq vi command: I +Move the cursor to the beginning of the edit buffer and switch to +vi insert mode. +.It Ic vi-kill-line-prev Pq vi: Ctrl-U +Delete the string from the beginning of the edit buffer to the +cursor and save it to the cut buffer. +.It Ic vi-list-or-eof Pq vi insert: Ctrl-D, EOF +If the edit buffer is empty, indicate end of file to the program. +It is an error if the edit buffer is not empty. +.It Ic vi-match Pq vi command: % +Consider opening and closing parentheses, braces, and brackets as +delimiters. +If the cursor is not at a delimiter, move it to the right until it +gets to one, then move it to the matching delimiter. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +It is an error if there is no delimiter at the cursor or in the +string to the right of the cursor, or if the first such delimiter +has no matching delimiter. +.It Ic vi-next-big-word Pq vi command: W +Move the cursor to the right to the beginning of the next space +delimited word. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +It is an error if the cursor is already at the end of the edit +buffer or on its last character. +.It Ic vi-next-char Pq vi command: f +Read one character from the terminal bypassing the normal line +editing functionality and move the cursor to the right to the next +instance of that character in the edit buffer. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +If trying to read the character results in end of file or an error, +call +.Ic ed-end-of-file +instead. +It is an error if the character is not found searching to the right +in the edit buffer. +.It Ic vi-next-word Pq vi command: w +Move the cursor to the right to the beginning of the next word. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +It is an error if the cursor is already at the end of the edit +buffer or on its last character. +.It Ic vi-paste-next Pq vi command: p +Insert a copy of the cut buffer to the right of the cursor. +It is an error if the cut buffer is empty. +.It Ic vi-paste-prev Pq vi command: P +Insert a copy of the cut buffer to the left of the cursor. +It is an error if the cut buffer is empty. +.It Ic vi-prev-big-word Pq vi command: B +Move the cursor to the left to the next beginning of a space delimited +word. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +It is an error if the cursor is already at the beginning of the +edit buffer. +.It Ic vi-prev-char Pq vi command: F +Read one character from the terminal bypassing the normal line +editing functionality and move the cursor to the left to the next +instance of that character in the edit buffer. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +If trying to read the character results in end of file or an error, +call +.Ic ed-end-of-file +instead. +It is an error if the character is not found searching to the left +in the edit buffer. +.It Ic vi-prev-word Pq vi command: b +Move the cursor to the left to the next beginning of a word. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +It is an error if the cursor is already at the beginning of the +edit buffer. +.It Ic vi-redo Pq vi command: Sq \&. +Redo the last non-motion command. +.It Ic vi-repeat-next-char Pq vi command: Sq \&; +Repeat the most recent character search in the same search direction. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +.It Ic vi-repeat-prev-char Pq vi command: Sq \&, +Repeat the most recent character search in the opposite search +direction. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +.It Ic vi-repeat-search-next Pq vi command: n +Repeat the most recent history search in the same search direction. +.It Ic vi-repeat-search-prev Pq vi command: N +Repeat the most recent history search in the opposite search +direction. +.It Ic vi-replace-char Pq vi command: r +Switch to vi replace mode, and automatically switch back to vi +command mode after the next character typed. +See +.Ic ed-insert +for a description of replace mode. +It is an error if the cursor is at the end of the edit buffer. +.It Ic vi-replace-mode Pq vi command: R +Switch to vi replace mode. +This is a variant of vi insert mode; see +.Ic ed-insert +for the difference. +.It Ic vi-search-next Pq vi command: \&? +Replace the edit buffer with the next matching history entry. +.It Ic vi-search-prev Pq vi command: / +Replace the edit buffer with the previous matching history entry. +.It Ic vi-substitute-char Pq vi command: s +Delete the character at the cursor and switch to vi insert mode. +.It Ic vi-substitute-line Pq vi command: S +Delete the entire contents of the edit buffer, save a copy of it +in the cut buffer, and enter vi insert mode. +.It Ic vi-to-column Pq vi command: \&| +Move the cursor to the column specified as the argument. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +.It Ic vi-to-history-line Pq vi command: G +Replace the edit buffer with the specified history entry. +.It Ic vi-to-next-char Pq vi command: t +Read one character from the terminal bypassing the normal line +editing functionality and move the cursor to the right to the +character before the next instance of that character in the edit +buffer. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +If trying to read the character results in end of file or an error, +call +.Ic ed-end-of-file +instead. +It is an error if the character is not found searching to the right +in the edit buffer. +.It Ic vi-to-prev-char Pq vi command: T +Read one character from the terminal bypassing the normal line +editing functionality and move the cursor to the left to the character +after the next instance of that character in the edit buffer. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +If trying to read the character results in end of file or an error, +call +.Ic ed-end-of-file +instead. +It is an error if the character is not found searching to the left +in the edit buffer. +.It Ic vi-undo Pq vi command: u +Undo the last change. +.It Ic vi-undo-line Pq vi command: U +Undo all changes to the edit buffer. +.It Ic vi-yank Pq vi command: y +Copy the string from the cursor to the position specified by the +following movement command to the cut buffer. +When given twice in a row, instead copy the whole contents of the +edit buffer to the cut buffer. +.It Ic vi-yank-end Pq vi command: Y +Copy the string from the cursor to the end of the edit buffer to +the cut buffer. +.It Ic vi-zero Pq vi command: 0 +If in argument input mode, multiply the argument by ten. +Otherwise, move the cursor to the beginning of the edit buffer. +Can be used as a movement command after +.Ic vi_change_meta , +.Ic vi_delete_meta , +or +.Ic vi_yank . +.El +.Ss Macros +If an input character is bound to the editor command +.Ic ed-sequence-lead-in , +.Nm +attempts to call a macro. +If the input character by itself forms the name of a macro, that +macro is executed. +Otherwise, additional input characters are read until the string +read forms the name of a macro, in which case that macro is executed, +or until the string read matches the beginning of none of the existing +macro names, in which case the string including the final, mismatching +character is discarded and the terminal bell is rung. +.Pp +There are two kinds of macros. +Command macros execute a single editor command. +Keyboard macros return a string of characters that is appended +as a new line to the +.Sx Input Queue . +.Pp +The following command macros are defined by default in vi command +mode and in emacs mode: +.Bl -column -offset indent "Esc O A, Esc O A" "em-exchange-mark" +.It Esc \&[ A, Esc O A Ta Ic ed-prev-history +.It Esc \&[ B, Esc O B Ta Ic ed-next-history +.It Esc \&[ C, Esc O C Ta Ic ed-next-char +.It Esc \&[ D, Esc O D Ta Ic ed-prev-char +.It Esc \&[ F, Esc O F Ta Ic ed-move-to-end +.It Esc \&[ H, Esc O H Ta Ic ed-move-to-beg +.El +.Pp +In vi command mode, they are also defined by default without the +initial escape character. +.Pp +In addition, the +.Nm +library tries to bind the strings generated by the arrow keys +as reported by the +.Xr terminfo 5 +database to these editor commands, unless that would clobber +user settings. +.Pp +In emacs mode, the two-character string +.Dq Ctrl-X Ctrl-X +is bound to the +.Ic em-exchange-mark +editor command. +.Ss Input Queue +The +.Nm +library maintains an input queue operated in FIFO mode. +Whenever it needs an input character, it takes the first character +from the first line of the input queue. +When the queue is empty, it reads from the terminal. +.Pp +A line can be appended to the end of the input queue in several ways: +.Bl -dash -offset indent +.It +By calling one of the keyboard +.Sx Macros . +.It +By calling the editor command +.Ic vi-redo . +.It +By calling the editor command +.Ic vi-alias . +.It +By pressing a key in emacs incremental search mode that doesn't +have a special meaning in that mode but returns to normal emacs +mode. +.It +If an application program directly calls the functions +.Xr el_push 3 +or +.Xr el_wpush 3 , +it can provide additional, program-specific ways +of appending to the input queue. +.El +.Sh SEE ALSO +.Xr mg 1 , +.Xr vi 1 , +.Xr editline 3 , +.Xr el_wgets 3 , +.Xr el_wpush 3 , +.Xr el_wset 3 , +.Xr editrc 5 +.Sh HISTORY +This manual page first appeared in +.Ox 6.0 +and +.Nx 8 . +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Ingo Schwarze Aq Mt schwarze@openbsd.org . diff --git a/static/netbsd/man7/eqn.7 b/static/netbsd/man7/eqn.7 new file mode 100644 index 00000000..24b72413 --- /dev/null +++ b/static/netbsd/man7/eqn.7 @@ -0,0 +1,507 @@ +.\" Id: eqn.7,v 1.39 2020/01/10 11:55:04 schwarze Exp +.\" +.\" Copyright (c) 2011 Kristaps Dzonsons +.\" Copyright (c) 2014 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd January 10, 2020 +.Dt EQN 7 +.Os +.Sh NAME +.Nm eqn +.Nd eqn language reference for mandoc +.Sh DESCRIPTION +The +.Nm eqn +language is an equation-formatting language. +It is used within +.Xr mdoc 7 +and +.Xr man 7 +.Ux +manual pages. +It describes the +.Em structure +of an equation, not its mathematical meaning. +This manual describes the +.Nm +language accepted by the +.Xr mandoc 1 +utility, which corresponds to the Second Edition +.Nm +specification (see +.Sx SEE ALSO +for references). +.Pp +An equation starts with an input line containing exactly the characters +.Sq \&.EQ , +may contain multiple input lines, and ends with an input line +containing exactly the characters +.Sq \&.EN . +Equivalently, an equation can be given in the middle of a single +text input line by surrounding it with the equation delimiters +defined with the +.Cm delim +statement. +.Pp +The equation grammar is as follows, where quoted strings are +case-sensitive literals in the input: +.Bd -literal -offset indent +eqn : box | eqn box +box : text + | \(dq{\(dq eqn \(dq}\(dq + | \(dqdefine\(dq text text + | \(dqndefine\(dq text text + | \(dqtdefine\(dq text text + | \(dqgfont\(dq text + | \(dqgsize\(dq text + | \(dqset\(dq text text + | \(dqundef\(dq text + | \(dqsqrt\(dq box + | box pos box + | box mark + | \(dqmatrix\(dq \(dq{\(dq [col \(dq{\(dq list \(dq}\(dq]* \(dq}\(dq + | pile \(dq{\(dq list \(dq}\(dq + | font box + | \(dqsize\(dq text box + | \(dqleft\(dq text eqn [\(dqright\(dq text] +col : \(dqlcol\(dq | \(dqrcol\(dq | \(dqccol\(dq | \(dqcol\(dq +text : [^space\e\(dq]+ | \e\(dq.*\e\(dq +pile : \(dqlpile\(dq | \(dqcpile\(dq | \(dqrpile\(dq | \(dqpile\(dq +pos : \(dqover\(dq | \(dqsup\(dq | \(dqsub\(dq | \(dqto\(dq | \(dqfrom\(dq +mark : \(dqdot\(dq | \(dqdotdot\(dq | \(dqhat\(dq | \(dqtilde\(dq | \(dqvec\(dq + | \(dqdyad\(dq | \(dqbar\(dq | \(dqunder\(dq +font : \(dqroman\(dq | \(dqitalic\(dq | \(dqbold\(dq | \(dqfat\(dq +list : eqn + | list \(dqabove\(dq eqn +space : [\e^~ \et] +.Ed +.Pp +White-space consists of the space, tab, circumflex, and tilde +characters. +It is required to delimit tokens consisting of alphabetic characters +and it is ignored at other places. +Braces and quotes also delimit tokens. +If within a quoted string, these space characters are retained. +Quoted strings are also not scanned for keywords, glyph names, +and expansion of definitions. +To print a literal quote character, it can be prepended with a +backslash or expressed with the \e(dq escape sequence. +.Pp +Subequations can be enclosed in braces to pass them as arguments +to operation keywords, overriding standard operation precedence. +Braces can be nested. +To set a brace verbatim, it needs to be enclosed in quotes. +.Pp +The following text terms are translated into a rendered glyph, if +available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa, +lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta, +upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA, +THETA, UPSILON, XI, inter (intersection), union (union), prod (product), +int (integral), sum (summation), grad (gradient), del (vector +differential), times (multiply), cdot (center-dot), nothing (zero-width +space), approx (approximately equals), prime (prime), half (one-half), +partial (partial differential), inf (infinity), >> (much greater), << +(much less), <\- (left arrow), \-> (right arrow), +\- (plus-minus), != +(not equal), == (equivalence), <= (less-than-equal), and >= +(more-than-equal). +The character escape sequences documented in +.Xr mandoc_char 7 +can be used, too. +.Pp +The following control statements are available: +.Bl -tag -width Ds +.It Cm define +Replace all occurrences of a key with a value. +Its syntax is as follows: +.Pp +.D1 Cm define Ar key cvalc +.Pp +The first character of the value string, +.Ar c , +is used as the delimiter for the value +.Ar val . +This allows for arbitrary enclosure of terms (not just quotes), such as +.Pp +.D1 Cm define Ar foo \(aqbar baz\(aq +.D1 Cm define Ar foo cbar bazc +.Pp +It is an error to have an empty +.Ar key +or +.Ar val . +Note that a quoted +.Ar key +causes errors in some +.Nm +implementations and should not be considered portable. +It is not expanded for replacements. +Definitions may refer to other definitions; these are evaluated +recursively when text replacement occurs and not when the definition is +created. +.Pp +Definitions can create arbitrary strings, for example, the following is +a legal construction. +.Bd -literal -offset indent +define foo \(aqdefine\(aq +foo bar \(aqbaz\(aq +.Ed +.Pp +Self-referencing definitions will raise an error. +The +.Cm ndefine +statement is a synonym for +.Cm define , +while +.Cm tdefine +is discarded. +.It Cm delim +This statement takes a string argument consisting of two bytes, +to be used as the opening and closing delimiters for equations +in the middle of text input lines. +Conventionally, the dollar sign is used for both delimiters, +as follows: +.Bd -literal -offset indent +\&.EQ +delim $$ +\&.EN +An equation like $sin pi = 0$ can now be entered +in the middle of a text input line. +.Ed +.Pp +The special statement +.Cm delim off +temporarily disables previously declared delimiters and +.Cm delim on +reenables them. +.It Cm gfont +Set the default font of subsequent output. +Its syntax is as follows: +.Pp +.D1 Cm gfont Ar font +.Pp +In mandoc, this value is discarded. +.It Cm gsize +Set the default size of subsequent output. +Its syntax is as follows: +.Pp +.D1 Cm gsize Oo +|\- Oc Ns Ar size +.Pp +The +.Ar size +value should be an integer. +If prepended by a sign, +the font size is changed relative to the current size. +.It Cm set +Set an equation mode. +In mandoc, both arguments are thrown away. +Its syntax is as follows: +.Pp +.D1 Cm set Ar key val +.Pp +The +.Ar key +and +.Ar val +are not expanded for replacements. +This statement is a GNU extension. +.It Cm undef +Unset a previously-defined key. +Its syntax is as follows: +.Pp +.D1 Cm define Ar key +.Pp +Once invoked, the definition for +.Ar key +is discarded. +The +.Ar key +is not expanded for replacements. +This statement is a GNU extension. +.El +.Pp +Operation keywords have the following semantics: +.Bl -tag -width Ds +.It Cm above +See +.Cm pile . +.It Cm bar +Draw a line over the preceding box. +.It Cm bold +Set the following box using bold font. +.It Cm ccol +Like +.Cm cpile , +but for use in +.Cm matrix . +.It Cm cpile +Like +.Cm pile , +but with slightly increased vertical spacing. +.It Cm dot +Set a single dot over the preceding box. +.It Cm dotdot +Set two dots (dieresis) over the preceding box. +.It Cm dyad +Set a dyad symbol (left-right arrow) over the preceding box. +.It Cm fat +A synonym for +.Cm bold . +.It Cm font +Set the second argument using the font specified by the first argument; +currently not recognized by the +.Xr mandoc 1 +.Nm +parser. +.It Cm from +Set the following box below the preceding box, +using a slightly smaller font. +Used for sums, integrals, limits, and the like. +.It Cm hat +Set a hat (circumflex) over the preceding box. +.It Cm italic +Set the following box using italic font. +.It Cm lcol +Like +.Cm lpile , +but for use in +.Cm matrix . +.It Cm left +Set the first argument as a big left delimiter before the second argument. +As an optional third argument, +.Cm right +can follow. +In that case, the fourth argument is set as a big right delimiter after +the second argument. +.It Cm lpile +Like +.Cm cpile , +but subequations are left-justified. +.It Cm matrix +Followed by a list of columns enclosed in braces. +All columns need to have the same number of subequations. +The columns are set as a matrix. +The difference compared to multiple subsequent +.Cm pile +operators is that in a +.Cm matrix , +corresponding subequations in all columns line up horizontally, +while each +.Cm pile +does vertical spacing independently. +.It Cm over +Set a fraction. +The preceding box is the numerator, the following box is the denominator. +.It Cm pile +Followed by a list of subequations enclosed in braces, +the subequations being separated by +.Cm above +keywords. +Sets the subequations one above the other, each of them centered. +Typically used to represent vectors in coordinate representation. +.It Cm rcol +Like +.Cm rpile , +but for use in +.Cm matrix . +.It Cm right +See +.Cm left ; +.Cm right +cannot be used without +.Cm left . +To set a big right delimiter without a big left delimiter, the following +construction can be used: +.Pp +.D1 Cm left No \(dq\(dq Ar box Cm right Ar delimiter +.It Cm roman +Set the following box using the default font. +.It Cm rpile +Like +.Cm cpile , +but subequations are right-justified. +.It Cm size +Set the second argument with the font size specified by the first +argument; currently ignored by +.Xr mandoc 1 . +By prepending a plus or minus sign to the first argument, +the font size can be selected relative to the current size. +.It Cm sqrt +Set the square root of the following box. +.It Cm sub +Set the following box as a subscript to the preceding box. +.It Cm sup +Set the following box as a superscript to the preceding box. +As a special case, if a +.Cm sup +clause immediately follows a +.Cm sub +clause as in +.Pp +.D1 Ar mainbox Cm sub Ar subbox Cm sup Ar supbox +.Pp +both are set with respect to the same +.Ar mainbox , +that is, +.Ar supbox +is set above +.Ar subbox . +.It Cm tilde +Set a tilde over the preceding box. +.It Cm to +Set the following box above the preceding box, +using a slightly smaller font. +Used for sums and integrals and the like. +As a special case, if a +.Cm to +clause immediately follows a +.Cm from +clause as in +.Pp +.D1 Ar mainbox Cm from Ar frombox Cm to Ar tobox +.Pp +both are set below and above the same +.Ar mainbox . +.It Cm under +Underline the preceding box. +.It Cm vec +Set a vector symbol (right arrow) over the preceding box. +.El +.Pp +The binary operations +.Cm from , +.Cm to , +.Cm sub , +and +.Cm sup +group to the right, that is, +.Pp +.D1 Ar mainbox Cm sup Ar supbox Cm sub Ar subbox +.Pp +is the same as +.Pp +.D1 Ar mainbox Cm sup Brq Ar supbox Cm sub Ar subbox +.Pp +and different from +.Pp +.D1 Bro Ar mainbox Cm sup Ar supbox Brc Cm sub Ar subbox . +.Pp +By contrast, +.Cm over +groups to the left. +.Pp +In the following list, earlier operations bind more tightly than +later operations: +.Pp +.Bl -enum -compact +.It +.Cm dyad , +.Cm vec , +.Cm under , +.Cm bar , +.Cm tilde , +.Cm hat , +.Cm dot , +.Cm dotdot +.It +.Cm fat , +.Cm roman , +.Cm italic , +.Cm bold , +.Cm size +.It +.Cm sub , +.Cm sup +.It +.Cm sqrt +.It +.Cm over +.It +.Cm from , +.Cm to +.El +.Sh COMPATIBILITY +This section documents the compatibility of mandoc +.Nm +and the troff +.Nm +implementation (including GNU troff). +.Pp +.Bl -dash -compact +.It +The text string +.Sq \e\(dq +is interpreted as a literal quote in troff. +In mandoc, this is interpreted as a comment. +.It +In troff, The circumflex and tilde white-space symbols map to +fixed-width spaces. +In mandoc, these characters are synonyms for the space character. +.It +The troff implementation of +.Nm +allows for equation alignment with the +.Cm mark +and +.Cm lineup +tokens. +mandoc discards these tokens. +The +.Cm back Ar n , +.Cm fwd Ar n , +.Cm up Ar n , +and +.Cm down Ar n +commands are also ignored. +.El +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr mdoc 7 , +.Xr roff 7 +.Rs +.%A Brian W. Kernighan +.%A Lorinda L. Cherry +.%T System for Typesetting Mathematics +.%J Communications of the ACM +.%V 18 +.%P pp. 151\(en157 +.%D March, 1975 +.Re +.Rs +.%A Brian W. Kernighan +.%A Lorinda L. Cherry +.%T Typesetting Mathematics, User's Guide +.%D 1976 +.Re +.Rs +.%A Brian W. Kernighan +.%A Lorinda L. Cherry +.%T Typesetting Mathematics, User's Guide (Second Edition) +.%D 1978 +.Re +.Sh HISTORY +The eqn utility, a preprocessor for troff, was originally written by +Brian W. Kernighan and Lorinda L. Cherry in 1975. +The GNU reimplementation of eqn, part of the GNU troff package, was +released in 1989 by James Clark. +The eqn component of +.Xr mandoc 1 +was added in 2011. +.Sh AUTHORS +This +.Nm +reference was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . diff --git a/static/netbsd/man7/evp.7 b/static/netbsd/man7/evp.7 new file mode 100644 index 00000000..c5363468 --- /dev/null +++ b/static/netbsd/man7/evp.7 @@ -0,0 +1,164 @@ +.\" $NetBSD: evp.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP 7" +.TH EVP 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +evp \- high\-level cryptographic functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP library provides a high\-level interface to cryptographic +functions. +.PP +The \fBEVP_Seal\fR\fIXXX\fR and \fBEVP_Open\fR\fIXXX\fR +functions provide public key encryption and decryption to implement digital "envelopes". +.PP +The \fBEVP_DigestSign\fR\fIXXX\fR and +\&\fBEVP_DigestVerify\fR\fIXXX\fR functions implement +digital signatures and Message Authentication Codes (MACs). Also see the older +\&\fBEVP_Sign\fR\fIXXX\fR and \fBEVP_Verify\fR\fIXXX\fR +functions. +.PP +Symmetric encryption is available with the \fBEVP_Encrypt\fR\fIXXX\fR +functions. The \fBEVP_Digest\fR\fIXXX\fR functions provide message digests. +.PP +The \fBEVP_PKEY\fR\fIXXX\fR functions provide a high\-level interface to +asymmetric algorithms. To create a new EVP_PKEY see +\&\fBEVP_PKEY_new\fR\|(3). EVP_PKEYs can be associated +with a private key of a particular algorithm by using the functions +described on the \fBEVP_PKEY_fromdata\fR\|(3) page, or +new keys can be generated using \fBEVP_PKEY_keygen\fR\|(3). +EVP_PKEYs can be compared using \fBEVP_PKEY_eq\fR\|(3), or printed using +\&\fBEVP_PKEY_print_private\fR\|(3). \fBEVP_PKEY_todata\fR\|(3) can be used to convert a +key back into an \fBOSSL_PARAM\fR\|(3) array. +.PP +The EVP_PKEY functions support the full range of asymmetric algorithm operations: +.IP "For key agreement see \fBEVP_PKEY_derive\fR\|(3)" 4 +.IX Item "For key agreement see EVP_PKEY_derive" +.PD 0 +.IP "For signing and verifying see \fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify\fR\|(3) and \fBEVP_PKEY_verify_recover\fR\|(3). However, note that these functions do not perform a digest of the data to be signed. Therefore, normally you would use the \fBEVP_DigestSignInit\fR\|(3) functions for this purpose." 4 +.IX Item "For signing and verifying see EVP_PKEY_sign, EVP_PKEY_verify and EVP_PKEY_verify_recover. However, note that these functions do not perform a digest of the data to be signed. Therefore, normally you would use the EVP_DigestSignInit functions for this purpose." +.IP "For encryption and decryption see \fBEVP_PKEY_encrypt\fR\|(3) and \fBEVP_PKEY_decrypt\fR\|(3) respectively. However, note that these functions perform encryption and decryption only. As public key encryption is an expensive operation, normally you would wrap an encrypted message in a ""digital envelope"" using the \fBEVP_SealInit\fR\|(3) and \fBEVP_OpenInit\fR\|(3) functions." 4 +.IX Item "For encryption and decryption see EVP_PKEY_encrypt and EVP_PKEY_decrypt respectively. However, note that these functions perform encryption and decryption only. As public key encryption is an expensive operation, normally you would wrap an encrypted message in a ""digital envelope"" using the EVP_SealInit and EVP_OpenInit functions." +.PD +.PP +The \fBEVP_BytesToKey\fR\|(3) function provides some limited support for password +based encryption. Careful selection of the parameters will provide a PKCS#5 PBKDF1 compatible +implementation. However, new applications should not typically use this (preferring, for example, +PBKDF2 from PCKS#5). +.PP +The \fBEVP_Encode\fR\fIXXX\fR and +\&\fBEVP_Decode\fR\fIXXX\fR functions implement base64 encoding +and decoding. +.PP +All the symmetric algorithms (ciphers), digests and asymmetric algorithms +(public key algorithms) can be replaced by ENGINE modules providing alternative +implementations. If ENGINE implementations of ciphers or digests are registered +as defaults, then the various EVP functions will automatically use those +implementations automatically in preference to built in software +implementations. For more information, consult the \fBengine\fR\|(3) man page. +.PP +Although low\-level algorithm specific functions exist for many algorithms +their use is discouraged. They cannot be used with an ENGINE and ENGINE +versions of new algorithms cannot be accessed using the low\-level functions. +Also makes code harder to adapt to new algorithms and some options are not +cleanly supported at the low\-level and some operations are more efficient +using the high\-level interface. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_DigestInit\fR\|(3), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_OpenInit\fR\|(3), +\&\fBEVP_SealInit\fR\|(3), +\&\fBEVP_DigestSignInit\fR\|(3), +\&\fBEVP_SignInit\fR\|(3), +\&\fBEVP_VerifyInit\fR\|(3), +\&\fBEVP_EncodeInit\fR\|(3), +\&\fBEVP_PKEY_new\fR\|(3), +\&\fBEVP_PKEY_fromdata\fR\|(3), +\&\fBEVP_PKEY_todata\fR\|(3), +\&\fBEVP_PKEY_keygen\fR\|(3), +\&\fBEVP_PKEY_print_private\fR\|(3), +\&\fBEVP_PKEY_decrypt\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBEVP_PKEY_verify_recover\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3), +\&\fBEVP_BytesToKey\fR\|(3), +\&\fBENGINE_by_id\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/example.7 b/static/netbsd/man7/example.7 new file mode 100644 index 00000000..7e871bae --- /dev/null +++ b/static/netbsd/man7/example.7 @@ -0,0 +1,13 @@ +# $NetBSD: example.7,v 1.1.1.1 2012/03/23 21:20:15 christos Exp $ +# block all ICMP packets. +# +block in proto icmp all +# +# allow in ICMP echos and echo-replies. +# +pass in on le1 proto icmp from any to any icmp-type echo +pass in on le1 proto icmp from any to any icmp-type echorep +# +# block all ICMP destination unreachable packets which are port-unreachables +# +block in on le1 proto icmp from any to any icmp-type unreach code 3 diff --git a/static/netbsd/man7/fips_module.7 b/static/netbsd/man7/fips_module.7 new file mode 100644 index 00000000..cafd24ce --- /dev/null +++ b/static/netbsd/man7/fips_module.7 @@ -0,0 +1,646 @@ +.\" $NetBSD: fips_module.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "FIPS_MODULE 7" +.TH FIPS_MODULE 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +fips_module \- OpenSSL fips module guide +.SH SYNOPSIS +.IX Header "SYNOPSIS" +See the individual manual pages for details. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This guide details different ways that OpenSSL can be used in conjunction +with the FIPS module. Which is the correct approach to use will depend on your +own specific circumstances and what you are attempting to achieve. +.PP +For information related to installing the FIPS module see +. +.PP +Note that the old functions \fBFIPS_mode()\fR and \fBFIPS_mode_set()\fR are no longer +present so you must remove them from your application if you use them. +.PP +Applications written to use the OpenSSL 3.0 FIPS module should not use any +legacy APIs or features that avoid the FIPS module. Specifically this includes: +.IP \(bu 4 +Low level cryptographic APIs (use the high level APIs, such as EVP, instead) +.IP \(bu 4 +Engines +.IP \(bu 4 +Any functions that create or modify custom "METHODS" (for example +\&\fBEVP_MD_meth_new()\fR, \fBEVP_CIPHER_meth_new()\fR, \fBEVP_PKEY_meth_new()\fR, \fBRSA_meth_new()\fR, +\&\fBEC_KEY_METHOD_new()\fR, etc.) +.PP +All of the above APIs are deprecated in OpenSSL 3.0 \- so a simple rule is to +avoid using all deprecated functions. See \fBossl\-guide\-migration\fR\|(7) for a list of +deprecated functions. +.SS "Making all applications use the FIPS module by default" +.IX Subsection "Making all applications use the FIPS module by default" +One simple approach is to cause all applications that are using OpenSSL to only +use the FIPS module for cryptographic algorithms by default. +.PP +This approach can be done purely via configuration. As long as applications are +built and linked against OpenSSL 3.0 and do not override the loading of the +default config file or its settings then they can automatically start using the +FIPS module without the need for any further code changes. +.PP +To do this the default OpenSSL config file will have to be modified. The +location of this config file will depend on the platform, and any options that +were given during the build process. You can check the location of the config +file by running this command: +.PP +.Vb 2 +\& $ openssl version \-d +\& OPENSSLDIR: "/usr/local/ssl" +.Ve +.PP +Caution: Many Operating Systems install OpenSSL by default. It is a common error +to not have the correct version of OpenSSL in your \f(CW$PATH\fR. Check that you are +running an OpenSSL 3.0 version like this: +.PP +.Vb 2 +\& $ openssl version \-v +\& OpenSSL 3.0.0\-dev xx XXX xxxx (Library: OpenSSL 3.0.0\-dev xx XXX xxxx) +.Ve +.PP +The \fBOPENSSLDIR\fR value above gives the directory name for where the default +config file is stored. So in this case the default config file will be called +\&\fI/usr/local/ssl/openssl.cnf\fR. +.PP +Edit the config file to add the following lines near the beginning: +.PP +.Vb 2 +\& config_diagnostics = 1 +\& openssl_conf = openssl_init +\& +\& .include /usr/local/ssl/fipsmodule.cnf +\& +\& [openssl_init] +\& providers = provider_sect +\& alg_section = algorithm_sect +\& +\& [provider_sect] +\& fips = fips_sect +\& base = base_sect +\& +\& [base_sect] +\& activate = 1 +\& +\& [algorithm_sect] +\& default_properties = fips=yes +.Ve +.PP +Obviously the include file location above should match the path and name of the +FIPS module config file that you installed earlier. +See . +.PP +For FIPS usage, it is recommended that the \fBconfig_diagnostics\fR option is +enabled to prevent accidental use of non\-FIPS validated algorithms via broken +or mistaken configuration. See \fBconfig\fR\|(5). +.PP +Any applications that use OpenSSL 3.0 and are started after these changes are +made will start using only the FIPS module unless those applications take +explicit steps to avoid this default behaviour. Note that this configuration +also activates the "base" provider. The base provider does not include any +cryptographic algorithms (and therefore does not impact the validation status of +any cryptographic operations), but does include other supporting algorithms that +may be required. It is designed to be used in conjunction with the FIPS module. +.PP +This approach has the primary advantage that it is simple, and no code changes +are required in applications in order to benefit from the FIPS module. There are +some disadvantages to this approach: +.IP \(bu 4 +You may not want all applications to use the FIPS module. +.Sp +It may be the case that some applications should and some should not use the +FIPS module. +.IP \(bu 4 +If applications take explicit steps to not load the default config file or +set different settings. +.Sp +This method will not work for these cases. +.IP \(bu 4 +The algorithms available in the FIPS module are a subset of the algorithms +that are available in the default OpenSSL Provider. +.Sp +If any applications attempt to use any algorithms that are not present, +then they will fail. +.IP \(bu 4 +Usage of certain deprecated APIs avoids the use of the FIPS module. +.Sp +If any applications use those APIs then the FIPS module will not be used. +.SS "Selectively making applications use the FIPS module by default" +.IX Subsection "Selectively making applications use the FIPS module by default" +A variation on the above approach is to do the same thing on an individual +application basis. The default OpenSSL config file depends on the compiled in +value for \fBOPENSSLDIR\fR as described in the section above. However it is also +possible to override the config file to be used via the \fBOPENSSL_CONF\fR +environment variable. For example the following, on Unix, will cause the +application to be executed with a non\-standard config file location: +.PP +.Vb 1 +\& $ OPENSSL_CONF=/my/nondefault/openssl.cnf myapplication +.Ve +.PP +Using this mechanism you can control which config file is loaded (and hence +whether the FIPS module is loaded) on an application by application basis. +.PP +This removes the disadvantage listed above that you may not want all +applications to use the FIPS module. All the other advantages and disadvantages +still apply. +.SS "Programmatically loading the FIPS module (default library context)" +.IX Subsection "Programmatically loading the FIPS module (default library context)" +Applications may choose to load the FIPS provider explicitly rather than relying +on config to do this. The config file is still necessary in order to hold the +FIPS module config data (such as its self test status and integrity data). But +in this case we do not automatically activate the FIPS provider via that config +file. +.PP +To do things this way configure as per +"Making all applications use the FIPS module by default" above, but edit the +\&\fIfipsmodule.cnf\fR file to remove or comment out the line which says +\&\f(CW\*(C`activate = 1\*(C'\fR (note that setting this value to 0 is \fInot\fR sufficient). +This means all the required config information will be available to load the +FIPS module, but it is not automatically loaded when the application starts. The +FIPS provider can then be loaded programmatically like this: +.PP +.Vb 1 +\& #include +\& +\& int main(void) +\& { +\& OSSL_PROVIDER *fips; +\& OSSL_PROVIDER *base; +\& +\& fips = OSSL_PROVIDER_load(NULL, "fips"); +\& if (fips == NULL) { +\& printf("Failed to load FIPS provider\en"); +\& exit(EXIT_FAILURE); +\& } +\& base = OSSL_PROVIDER_load(NULL, "base"); +\& if (base == NULL) { +\& OSSL_PROVIDER_unload(fips); +\& printf("Failed to load base provider\en"); +\& exit(EXIT_FAILURE); +\& } +\& +\& /* Rest of application */ +\& +\& OSSL_PROVIDER_unload(base); +\& OSSL_PROVIDER_unload(fips); +\& exit(EXIT_SUCCESS); +\& } +.Ve +.PP +Note that this should be one of the first things that you do in your +application. If any OpenSSL functions get called that require the use of +cryptographic functions before this occurs then, if no provider has yet been +loaded, then the default provider will be automatically loaded. If you then +later explicitly load the FIPS provider then you will have both the FIPS and the +default provider loaded at the same time. It is unspecified which implementation +of an algorithm will be used if multiple implementations are available and you +have not explicitly specified via a property query (see below) which one should +be used. +.PP +Also note that in this example we have additionally loaded the "base" provider. +This loads a sub\-set of algorithms that are also available in the default +provider \- specifically non cryptographic ones which may be used in conjunction +with the FIPS provider. For example this contains algorithms for encoding and +decoding keys. If you decide not to load the default provider then you +will usually want to load the base provider instead. +.PP +In this example we are using the "default" library context. OpenSSL functions +operate within the scope of a library context. If no library context is +explicitly specified then the default library context is used. For further +details about library contexts see the \fBOSSL_LIB_CTX\fR\|(3) man page. +.SS "Loading the FIPS module at the same time as other providers" +.IX Subsection "Loading the FIPS module at the same time as other providers" +It is possible to have the FIPS provider and other providers (such as the +default provider) all loaded at the same time into the same library context. You +can use a property query string during algorithm fetches to specify which +implementation you would like to use. +.PP +For example to fetch an implementation of SHA256 which conforms to FIPS +standards you can specify the property query \f(CW\*(C`fips=yes\*(C'\fR like this: +.PP +.Vb 1 +\& EVP_MD *sha256; +\& +\& sha256 = EVP_MD_fetch(NULL, "SHA2\-256", "fips=yes"); +.Ve +.PP +If no property query is specified, or more than one implementation matches the +property query then it is unspecified which implementation of a particular +algorithm will be returned. +.PP +This example shows an explicit request for an implementation of SHA256 from the +default provider: +.PP +.Vb 1 +\& EVP_MD *sha256; +\& +\& sha256 = EVP_MD_fetch(NULL, "SHA2\-256", "provider=default"); +.Ve +.PP +It is also possible to set a default property query string. The following +example sets the default property query of \f(CW\*(C`fips=yes\*(C'\fR for all fetches within +the default library context: +.PP +.Vb 1 +\& EVP_set_default_properties(NULL, "fips=yes"); +.Ve +.PP +If a fetch function has both an explicit property query specified, and a +default property query is defined then the two queries are merged together and +both apply. The local property query overrides the default properties if the +same property name is specified in both. +.PP +There are two important built\-in properties that you should be aware of: +.PP +The "provider" property enables you to specify which provider you want an +implementation to be fetched from, e.g. \f(CW\*(C`provider=default\*(C'\fR or \f(CW\*(C`provider=fips\*(C'\fR. +All algorithms implemented in a provider have this property set on them. +.PP +There is also the \f(CW\*(C`fips\*(C'\fR property. All FIPS algorithms match against the +property query \f(CW\*(C`fips=yes\*(C'\fR. There are also some non\-cryptographic algorithms +available in the default and base providers that also have the \f(CW\*(C`fips=yes\*(C'\fR +property defined for them. These are the encoder and decoder algorithms that +can (for example) be used to write out a key generated in the FIPS provider to a +file. The encoder and decoder algorithms are not in the FIPS module itself but +are allowed to be used in conjunction with the FIPS algorithms. +.PP +It is possible to specify default properties within a config file. For example +the following config file automatically loads the default and FIPS providers and +sets the default property value to be \f(CW\*(C`fips=yes\*(C'\fR. Note that this config file +does not load the "base" provider. All supporting algorithms that are in "base" +are also in "default", so it is unnecessary in this case: +.PP +.Vb 2 +\& config_diagnostics = 1 +\& openssl_conf = openssl_init +\& +\& .include /usr/local/ssl/fipsmodule.cnf +\& +\& [openssl_init] +\& providers = provider_sect +\& alg_section = algorithm_sect +\& +\& [provider_sect] +\& fips = fips_sect +\& default = default_sect +\& +\& [default_sect] +\& activate = 1 +\& +\& [algorithm_sect] +\& default_properties = fips=yes +.Ve +.SS "Programmatically loading the FIPS module (nondefault library context)" +.IX Subsection "Programmatically loading the FIPS module (nondefault library context)" +In addition to using properties to separate usage of the FIPS module from other +usages this can also be achieved using library contexts. In this example we +create two library contexts. In one we assume the existence of a config file +called \fIopenssl\-fips.cnf\fR that automatically loads and configures the FIPS and +base providers. The other library context will just use the default provider. +.PP +.Vb 4 +\& OSSL_LIB_CTX *fips_libctx, *nonfips_libctx; +\& OSSL_PROVIDER *defctxnull = NULL; +\& EVP_MD *fipssha256 = NULL, *nonfipssha256 = NULL; +\& int ret = 1; +\& +\& /* +\& * Create two nondefault library contexts. One for fips usage and +\& * one for non\-fips usage +\& */ +\& fips_libctx = OSSL_LIB_CTX_new(); +\& nonfips_libctx = OSSL_LIB_CTX_new(); +\& if (fips_libctx == NULL || nonfips_libctx == NULL) +\& goto err; +\& +\& /* Prevent anything from using the default library context */ +\& defctxnull = OSSL_PROVIDER_load(NULL, "null"); +\& +\& /* +\& * Load config file for the FIPS library context. We assume that +\& * this config file will automatically activate the FIPS and base +\& * providers so we don\*(Aqt need to explicitly load them here. +\& */ +\& if (!OSSL_LIB_CTX_load_config(fips_libctx, "openssl\-fips.cnf")) +\& goto err; +\& +\& /* +\& * Set the default property query on the FIPS library context to +\& * ensure that only FIPS algorithms can be used. There are a few non\-FIPS +\& * approved algorithms in the FIPS provider for backward compatibility reasons. +\& */ +\& if (!EVP_set_default_properties(fips_libctx, "fips=yes")) +\& goto err; +\& +\& /* +\& * We don\*(Aqt need to do anything special to load the default +\& * provider into nonfips_libctx. This happens automatically if no +\& * other providers are loaded. +\& * Because we don\*(Aqt call OSSL_LIB_CTX_load_config() explicitly for +\& * nonfips_libctx it will just use the default config file. +\& */ +\& +\& /* As an example get some digests */ +\& +\& /* Get a FIPS validated digest */ +\& fipssha256 = EVP_MD_fetch(fips_libctx, "SHA2\-256", NULL); +\& if (fipssha256 == NULL) +\& goto err; +\& +\& /* Get a non\-FIPS validated digest */ +\& nonfipssha256 = EVP_MD_fetch(nonfips_libctx, "SHA2\-256", NULL); +\& if (nonfipssha256 == NULL) +\& goto err; +\& +\& /* Use the digests */ +\& +\& printf("Success\en"); +\& ret = 0; +\& +\& err: +\& EVP_MD_free(fipssha256); +\& EVP_MD_free(nonfipssha256); +\& OSSL_LIB_CTX_free(fips_libctx); +\& OSSL_LIB_CTX_free(nonfips_libctx); +\& OSSL_PROVIDER_unload(defctxnull); +\& +\& return ret; +.Ve +.PP +Note that we have made use of the special "null" provider here which we load +into the default library context. We could have chosen to use the default +library context for FIPS usage, and just create one additional library context +for other usages \- or vice versa. However if code has not been converted to use +library contexts then the default library context will be automatically used. +This could be the case for your own existing applications as well as certain +parts of OpenSSL itself. Not all parts of OpenSSL are library context aware. If +this happens then you could "accidentally" use the wrong library context for a +particular operation. To be sure this doesn\*(Aqt happen you can load the "null" +provider into the default library context. Because a provider has been +explicitly loaded, the default provider will not automatically load. This means +code using the default context by accident will fail because no algorithms will +be available. +.PP +See "Library Context" in \fBossl\-guide\-migration\fR\|(7) for additional information about the +Library Context. +.SS "Using Encoders and Decoders with the FIPS module" +.IX Subsection "Using Encoders and Decoders with the FIPS module" +Encoders and decoders are used to read and write keys or parameters from or to +some external format (for example a PEM file). If your application generates +keys or parameters that then need to be written into PEM or DER format +then it is likely that you will need to use an encoder to do this. Similarly +you need a decoder to read previously saved keys and parameters. In most cases +this will be invisible to you if you are using APIs that existed in +OpenSSL 1.1.1 or earlier such as \fBi2d_PrivateKey\fR\|(3). However the appropriate +encoder/decoder will need to be available in the library context associated with +the key or parameter object. The built\-in OpenSSL encoders and decoders are +implemented in both the default and base providers and are not in the FIPS +module boundary. However since they are not cryptographic algorithms themselves +it is still possible to use them in conjunction with the FIPS module, and +therefore these encoders/decoders have the \f(CW\*(C`fips=yes\*(C'\fR property against them. +You should ensure that either the default or base provider is loaded into the +library context in this case. +.SS "Using the FIPS module in SSL/TLS" +.IX Subsection "Using the FIPS module in SSL/TLS" +Writing an application that uses libssl in conjunction with the FIPS module is +much the same as writing a normal libssl application. If you are using global +properties and the default library context to specify usage of FIPS validated +algorithms then this will happen automatically for all cryptographic algorithms +in libssl. If you are using a nondefault library context to load the FIPS +provider then you can supply this to libssl using the function +\&\fBSSL_CTX_new_ex\fR\|(3). This works as a drop in replacement for the function +\&\fBSSL_CTX_new\fR\|(3) except it provides you with the capability to specify the +library context to be used. You can also use the same function to specify +libssl specific properties to use. +.PP +In this first example we create two SSL_CTX objects using two different library +contexts. +.PP +.Vb 11 +\& /* +\& * We assume that a nondefault library context with the FIPS +\& * provider loaded has been created called fips_libctx. +\& */ +\& SSL_CTX *fips_ssl_ctx = SSL_CTX_new_ex(fips_libctx, "fips=yes", TLS_method()); +\& /* +\& * We assume that a nondefault library context with the default +\& * provider loaded has been created called non_fips_libctx. +\& */ +\& SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_ex(non_fips_libctx, NULL, +\& TLS_method()); +.Ve +.PP +In this second example we create two SSL_CTX objects using different properties +to specify FIPS usage: +.PP +.Vb 10 +\& /* +\& * The "fips=yes" property includes all FIPS approved algorithms +\& * as well as encoders from the default provider that are allowed +\& * to be used. The NULL below indicates that we are using the +\& * default library context. +\& */ +\& SSL_CTX *fips_ssl_ctx = SSL_CTX_new_ex(NULL, "fips=yes", TLS_method()); +\& /* +\& * The "provider!=fips" property allows algorithms from any +\& * provider except the FIPS provider +\& */ +\& SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_ex(NULL, "provider!=fips", +\& TLS_method()); +.Ve +.SS "Confirming that an algorithm is being provided by the FIPS module" +.IX Subsection "Confirming that an algorithm is being provided by the FIPS module" +A chain of links needs to be followed to go from an algorithm instance to the +provider that implements it. The process is similar for all algorithms. Here the +example of a digest is used. +.PP +To go from an \fBEVP_MD_CTX\fR to an \fBEVP_MD\fR, use \fBEVP_MD_CTX_md\fR\|(3) . +To go from the \fBEVP_MD\fR to its \fBOSSL_PROVIDER\fR, +use \fBEVP_MD_get0_provider\fR\|(3). +To extract the name from the \fBOSSL_PROVIDER\fR, use +\&\fBOSSL_PROVIDER_get0_name\fR\|(3). +.SS "FIPS indicators" +.IX Subsection "FIPS indicators" +FIPS indicators have been added to the FIPS provider in OpenSSL 3.4. +FIPS 140\-3 requires indicators to be used if the FIPS provider allows non +approved algorithms. An algorithm is approved if it passes all required checks +such as minimum key size. By default an error will occur if any check fails. +For backwards compatibility individual algorithms may override the checks by +using either an option in the FIPS configuration (See +"FIPS indicator options" in \fBfips_config\fR\|(5)) OR in code using an algorithm context +setter. Overriding the check means that the algorithm is not FIPS compliant. +\&\fBOSSL_INDICATOR_set_callback\fR\|(3) can be called to register a callback to log +unapproved algorithms. At the end of any algorithm operation the approved status +can be queried using an algorithm context getter to retrieve the indicator +(e.g. "fips\-indicator"). +An example of an algorithm context setter is "key\-check" +in "Supported parameters" in \fBEVP_KDF\-HKDF\fR\|(7). +.PP +The following algorithms use "fips\-indicator" to query if the algorithm +is approved: +.IP "DSA Key generation" 4 +.IX Item "DSA Key generation" +DSA Key generation is no longer approved. +See "DSA parameters" in \fBEVP_PKEY\-DSA\fR\|(7) +.IP "DSA Signatures" 4 +.IX Item "DSA Signatures" +DSA Signature generation is no longer approved. +See "Signature Parameters" in \fBEVP_SIGNATURE\-DSA\fR\|(7) +.IP "ECDSA Signatures" 4 +.IX Item "ECDSA Signatures" +See "ECDSA Signature Parameters" in \fBEVP_SIGNATURE\-ECDSA\fR\|(7) +.IP "EC Key Generation" 4 +.IX Item "EC Key Generation" +See "Common EC parameters" in \fBEVP_PKEY\-EC\fR\|(7) +.IP "RSA Encryption" 4 +.IX Item "RSA Encryption" +"pkcs1" padding is no longer approved. +.Sp +See "RSA Asymmetric Cipher parameters" in \fBEVP_ASYM_CIPHER\-RSA\fR\|(7) and +"RSA KEM parameters" in \fBEVP_KEM\-RSA\fR\|(7) +.IP "RSA Signatures" 4 +.IX Item "RSA Signatures" +See "Signature Parameters" in \fBEVP_SIGNATURE\-RSA\fR\|(7) +.IP DRBGS 4 +.IX Item "DRBGS" +See "Supported parameters" in \fBEVP_RAND\-HASH\-DRBG\fR\|(7) and +\&\fBEVP_RAND\-HMAC\-DRBG\fR\|(7)/Supported parameters> +.IP DES 4 +.IX Item "DES" +Triple\-DES is not longer approved for encryption. +See "Parameters" in \fBEVP_CIPHER\-DES\fR\|(7) +.IP DH 4 +.IX Item "DH" +See "DH and DHX key exchange parameters" in \fBEVP_KEYEXCH\-DH\fR\|(7) +.IP ECDH 4 +.IX Item "ECDH" +See "ECDH Key Exchange parameters" in \fBEVP_KEYEXCH\-ECDH\fR\|(7) +.IP KDFS 4 +.IX Item "KDFS" +See relevant KDF documentation e.g. "Supported parameters" in \fBEVP_KDF\-HKDF\fR\|(7) +.IP "CMAC and KMAC" 4 +.IX Item "CMAC and KMAC" +See "Supported parameters" in \fBEVP_MAC\-CMAC\fR\|(7) and +"Supported parameters" in \fBEVP_MAC\-KMAC\fR\|(7) +.PP +The following FIPS algorithms are unapproved and use the "fips\-indicator". +.IP RAND\-TEST\-RAND 4 +.IX Item "RAND-TEST-RAND" +See "Supported parameters" in \fBEVP_RAND\-TEST\-RAND\fR\|(7) +The indicator callback is NOT triggered for this algorithm since it is used +internally for non security purposes. +.IP "X25519 and X448 Key Generation and Key Exchange" 4 +.IX Item "X25519 and X448 Key Generation and Key Exchange" +.PP +The unapproved (non FIPS validated) algorithms have a property query value of +"fips=no". +.PP +The following algorithms use a unique indicator and do not trigger the +indicator callback. +.IP "AES\-GCM ciphers support the indicator ""iv\-generated""" 4 +.IX Item "AES-GCM ciphers support the indicator ""iv-generated""" +See "PARAMETERS" in \fBEVP_EncryptInit\fR\|(3) for further information. +.IP "ECDSA and RSA Signatures support the indicator ""verify\-message""." 4 +.IX Item "ECDSA and RSA Signatures support the indicator ""verify-message""." +See "ECDSA Signature Parameters" in \fBEVP_SIGNATURE\-ECDSA\fR\|(7) and +"Signature Parameters" in \fBEVP_SIGNATURE\-RSA\fR\|(7) /for further information. +.SH NOTES +.IX Header "NOTES" +Some released versions of OpenSSL do not include a validated +FIPS provider. To determine which versions have undergone +the validation process, please refer to the +OpenSSL Downloads page . If you +require FIPS\-approved functionality, it is essential to build your FIPS +provider using one of the validated versions listed there. Normally, +it is possible to utilize a FIPS provider constructed from one of the +validated versions alongside \fIlibcrypto\fR and \fIlibssl\fR compiled from any +release within the same major release series. This flexibility enables +you to address bug fixes and CVEs that fall outside the FIPS boundary. +.PP +As the FIPS provider still supports non\-FIPS validated algorithms, +The property query \f(CW\*(C`fips=yes\*(C'\fR is mandatory for applications that +want to operate in a FIPS approved manner. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-migration\fR\|(7), \fBcrypto\fR\|(7), \fBfips_config\fR\|(5), + +.SH HISTORY +.IX Header "HISTORY" +The FIPS module guide was created for use with the new FIPS provider +in OpenSSL 3.0. +FIPS indicators were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/fsf-funding.7 b/static/netbsd/man7/fsf-funding.7 new file mode 100644 index 00000000..e3f0bee8 --- /dev/null +++ b/static/netbsd/man7/fsf-funding.7 @@ -0,0 +1,189 @@ +.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "FSF-FUNDING 7" +.TH FSF-FUNDING 7 "2025-07-11" "gcc-12.5.0" "GNU" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +fsf\-funding \- Funding Free Software +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +.SS "Funding Free Software" +.IX Subsection "Funding Free Software" +If you want to have more free software a few years from now, it makes +sense for you to help encourage people to contribute funds for its +development. The most effective approach known is to encourage +commercial redistributors to donate. +.PP +Users of free software systems can boost the pace of development by +encouraging for-a-fee distributors to donate part of their selling price +to free software developers\-\-\-the Free Software Foundation, and others. +.PP +The way to convince distributors to do this is to demand it and expect +it from them. So when you compare distributors, judge them partly by +how much they give to free software development. Show distributors +they must compete to be the one who gives the most. +.PP +To make this approach work, you must insist on numbers that you can +compare, such as, \*(L"We will donate ten dollars to the Frobnitz project +for each disk sold.\*(R" Don't be satisfied with a vague promise, such as +\&\*(L"A portion of the profits are donated,\*(R" since it doesn't give a basis +for comparison. +.PP +Even a precise fraction \*(L"of the profits from this disk\*(R" is not very +meaningful, since creative accounting and unrelated business decisions +can greatly alter what fraction of the sales price counts as profit. +If the price you pay is \f(CW$50\fR, ten percent of the profit is probably +less than a dollar; it might be a few cents, or nothing at all. +.PP +Some redistributors do development work themselves. This is useful too; +but to keep everyone honest, you need to inquire how much they do, and +what kind. Some kinds of development make much more long-term +difference than others. For example, maintaining a separate version of +a program contributes very little; maintaining the standard version of a +program for the whole community contributes much. Easy new ports +contribute little, since someone else would surely do them; difficult +ports such as adding a new \s-1CPU\s0 to the \s-1GNU\s0 Compiler Collection contribute more; +major new features or packages contribute the most. +.PP +By establishing the idea that supporting further development is \*(L"the +proper thing to do\*(R" when distributing free software for a fee, we can +assure a steady flow of resources into making more free software. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIgpl\fR\|(7), \fIgfdl\fR\|(7). +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1994 Free Software Foundation, Inc. +Verbatim copying and redistribution of this section is permitted +without royalty; alteration is not permitted. diff --git a/static/netbsd/man7/gfdl.7 b/static/netbsd/man7/gfdl.7 new file mode 100644 index 00000000..3ab58248 --- /dev/null +++ b/static/netbsd/man7/gfdl.7 @@ -0,0 +1,647 @@ +.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "GFDL 7" +.TH GFDL 7 "2025-07-11" "gcc-12.5.0" "GNU" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +gfdl \- GNU Free Documentation License +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\f(CW@comment\fR For some cases, this default \f(CW@node\fR/@unnumbered is not applicable and +\&\f(CW@comment\fR causes warnings. In those cases, the including file can set +\&\f(CW@comment\fR nodefaultgnufreedocumentationlicensenode and provide it's own version. +\&\f(CW@comment\fR F.i., when this file is included in an \f(CW@raisesections\fR context, the +\&\f(CW@comment\fR including file can use an \f(CW@unnumberedsec\fR. +.SS "\s-1GNU\s0 Free Documentation License" +.IX Subsection "GNU Free Documentation License" +.SS "Version 1.3, 3 November 2008" +.IX Subsection "Version 1.3, 3 November 2008" +.Vb 2 +\& Copyright (c) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +\& EBE +\& +\& Everyone is permitted to copy and distribute verbatim copies +\& of this license document, but changing it is not allowed. +.Ve +.IP "0." 4 +.IX Item "0." +\&\s-1PREAMBLE\s0 +.Sp +The purpose of this License is to make a manual, textbook, or other +functional and useful document \fIfree\fR in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. +.Sp +This License is a kind of \*(L"copyleft\*(R", which means that derivative +works of the document must themselves be free in the same sense. It +complements the \s-1GNU\s0 General Public License, which is a copyleft +license designed for free software. +.Sp +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. +.IP "1." 4 +.IX Item "1." +\&\s-1APPLICABILITY AND DEFINITIONS\s0 +.Sp +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The \*(L"Document\*(R", below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as \*(L"you\*(R". You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. +.Sp +A \*(L"Modified Version\*(R" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. +.Sp +A \*(L"Secondary Section\*(R" is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. +.Sp +The \*(L"Invariant Sections\*(R" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. +.Sp +The \*(L"Cover Texts\*(R" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. +.Sp +A \*(L"Transparent\*(R" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not \*(L"Transparent\*(R" is called \*(L"Opaque\*(R". +.Sp +Examples of suitable formats for Transparent copies include plain +\&\s-1ASCII\s0 without markup, Texinfo input format, LaTeX input +format, \s-1SGML\s0 or \s-1XML\s0 using a publicly available +\&\s-1DTD,\s0 and standard-conforming simple \s-1HTML,\s0 +PostScript or \s-1PDF\s0 designed for human modification. Examples +of transparent image formats include \s-1PNG, XCF\s0 and +\&\s-1JPG.\s0 Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, \s-1SGML\s0 or +\&\s-1XML\s0 for which the \s-1DTD\s0 and/or processing tools are +not generally available, and the machine-generated \s-1HTML,\s0 +PostScript or \s-1PDF\s0 produced by some word processors for +output purposes only. +.Sp +The \*(L"Title Page\*(R" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, \*(L"Title Page\*(R" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. +.Sp +The \*(L"publisher\*(R" means any person or entity that distributes copies +of the Document to the public. +.Sp +A section \*(L"Entitled \s-1XYZ\*(R"\s0 means a named subunit of the Document whose +title either is precisely \s-1XYZ\s0 or contains \s-1XYZ\s0 in parentheses following +text that translates \s-1XYZ\s0 in another language. (Here \s-1XYZ\s0 stands for a +specific section name mentioned below, such as \*(L"Acknowledgements\*(R", +\&\*(L"Dedications\*(R", \*(L"Endorsements\*(R", or \*(L"History\*(R".) To \*(L"Preserve the Title\*(R" +of such a section when you modify the Document means that it remains a +section \*(L"Entitled \s-1XYZ\*(R"\s0 according to this definition. +.Sp +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. +.IP "2." 4 +.IX Item "2." +\&\s-1VERBATIM COPYING\s0 +.Sp +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. +.Sp +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. +.IP "3." 4 +.IX Item "3." +\&\s-1COPYING IN QUANTITY\s0 +.Sp +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. +.Sp +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. +.Sp +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. +.Sp +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. +.IP "4." 4 +.IX Item "4." +\&\s-1MODIFICATIONS\s0 +.Sp +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: +.RS 4 +.IP "A." 4 +.IX Item "A." +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. +.IP "B." 4 +.IX Item "B." +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. +.IP "C." 4 +.IX Item "C." +State on the Title page the name of the publisher of the +Modified Version, as the publisher. +.IP "D." 4 +.IX Item "D." +Preserve all the copyright notices of the Document. +.IP "E." 4 +.IX Item "E." +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. +.IP "F." 4 +.IX Item "F." +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. +.IP "G." 4 +.IX Item "G." +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. +.IP "H." 4 +.IX Item "H." +Include an unaltered copy of this License. +.IP "I." 4 +.IX Item "I." +Preserve the section Entitled \*(L"History\*(R", Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled \*(L"History\*(R" in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. +.IP "J." 4 +.IX Item "J." +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the \*(L"History\*(R" section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. +.IP "K." 4 +.IX Item "K." +For any section Entitled \*(L"Acknowledgements\*(R" or \*(L"Dedications\*(R", Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. +.IP "L." 4 +.IX Item "L." +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. +.IP "M." 4 +.IX Item "M." +Delete any section Entitled \*(L"Endorsements\*(R". Such a section +may not be included in the Modified Version. +.IP "N." 4 +.IX Item "N." +Do not retitle any existing section to be Entitled \*(L"Endorsements\*(R" or +to conflict in title with any Invariant Section. +.IP "O." 4 +.IX Item "O." +Preserve any Warranty Disclaimers. +.RE +.RS 4 +.Sp +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. +.Sp +You may add a section Entitled \*(L"Endorsements\*(R", provided it contains +nothing but endorsements of your Modified Version by various +parties\-\-\-for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. +.Sp +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +.Sp +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. +.RE +.IP "5." 4 +.IX Item "5." +\&\s-1COMBINING DOCUMENTS\s0 +.Sp +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. +.Sp +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. +.Sp +In the combination, you must combine any sections Entitled \*(L"History\*(R" +in the various original documents, forming one section Entitled +\&\*(L"History\*(R"; likewise combine any sections Entitled \*(L"Acknowledgements\*(R", +and any sections Entitled \*(L"Dedications\*(R". You must delete all +sections Entitled \*(L"Endorsements.\*(R" +.IP "6." 4 +.IX Item "6." +\&\s-1COLLECTIONS OF DOCUMENTS\s0 +.Sp +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. +.Sp +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. +.IP "7." 4 +.IX Item "7." +\&\s-1AGGREGATION WITH INDEPENDENT WORKS\s0 +.Sp +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an \*(L"aggregate\*(R" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. +.Sp +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. +.IP "8." 4 +.IX Item "8." +\&\s-1TRANSLATION\s0 +.Sp +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. +.Sp +If a section in the Document is Entitled \*(L"Acknowledgements\*(R", +\&\*(L"Dedications\*(R", or \*(L"History\*(R", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. +.IP "9." 4 +.IX Item "9." +\&\s-1TERMINATION\s0 +.Sp +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. +.Sp +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. +.Sp +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. +.Sp +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. +.IP "10." 4 +.IX Item "10." +\&\s-1FUTURE REVISIONS OF THIS LICENSE\s0 +.Sp +The Free Software Foundation may publish new, revised versions +of the \s-1GNU\s0 Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +<\fBhttps://www.gnu.org/copyleft/\fR>. +.Sp +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License \*(L"or any later version\*(R" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. +.IP "11." 4 +.IX Item "11." +\&\s-1RELICENSING\s0 +.Sp +\&\*(L"Massive Multiauthor Collaboration Site\*(R" (or \*(L"\s-1MMC\s0 Site\*(R") means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +\&\*(L"Massive Multiauthor Collaboration\*(R" (or \*(L"\s-1MMC\*(R"\s0) contained in the +site means any set of copyrightable works thus published on the \s-1MMC\s0 +site. +.Sp +\&\*(L"CC-BY-SA\*(R" means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. +.Sp +\&\*(L"Incorporate\*(R" means to publish or republish a Document, in whole or +in part, as part of another Document. +.Sp +An \s-1MMC\s0 is \*(L"eligible for relicensing\*(R" if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this \s-1MMC,\s0 and subsequently incorporated in whole +or in part into the \s-1MMC,\s0 (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. +.Sp +The operator of an \s-1MMC\s0 Site may republish an \s-1MMC\s0 contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the \s-1MMC\s0 is eligible for relicensing. +.SS "\s-1ADDENDUM:\s0 How to use this License for your documents" +.IX Subsection "ADDENDUM: How to use this License for your documents" +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: +.PP +.Vb 7 +\& Copyright (C) . +\& Permission is granted to copy, distribute and/or modify this document +\& under the terms of the GNU Free Documentation License, Version 1.3 +\& or any later version published by the Free Software Foundation; +\& with no Invariant Sections, no Front\-Cover Texts, and no Back\-Cover +\& Texts. A copy of the license is included in the section entitled "GNU +\& Free Documentation License". +.Ve +.PP +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the \*(L"with...Texts.\*(R" line with this: +.PP +.Vb 3 +\& with the Invariant Sections being , with +\& the Front\-Cover Texts being , and with the Back\-Cover Texts +\& being . +.Ve +.PP +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. +.PP +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the \s-1GNU\s0 General Public License, +to permit their use in free software. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIgpl\fR\|(7), \fIfsf\-funding\fR\|(7). +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +<\fBhttps://fsf.org/\fR> +.PP +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. diff --git a/static/netbsd/man7/gpl.7 b/static/netbsd/man7/gpl.7 new file mode 100644 index 00000000..e77b5a09 --- /dev/null +++ b/static/netbsd/man7/gpl.7 @@ -0,0 +1,846 @@ +.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "GPL 7" +.TH GPL 7 "2025-07-11" "gcc-12.5.0" "GNU" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +gpl \- GNU General Public License +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +.SS "\s-1GNU\s0 General Public License" +.IX Subsection "GNU General Public License" +.SS "Version 3, 29 June 2007" +.IX Subsection "Version 3, 29 June 2007" +.Vb 1 +\& Copyright (c) 2007 Free Software Foundation, Inc. +\& +\& Everyone is permitted to copy and distribute verbatim copies of this +\& license document, but changing it is not allowed. +.Ve +.SS "Preamble" +.IX Subsection "Preamble" +The \s-1GNU\s0 General Public License is a free, copyleft license for +software and other kinds of works. +.PP +The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the \s-1GNU\s0 General Public License is intended to guarantee your freedom +to share and change all versions of a program\*(--to make sure it remains +free software for all its users. We, the Free Software Foundation, +use the \s-1GNU\s0 General Public License for most of our software; it +applies also to any other work released this way by its authors. You +can apply it to your programs, too. +.PP +When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. +.PP +To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you +have certain responsibilities if you distribute copies of the +software, or if you modify it: responsibilities to respect the freedom +of others. +.PP +For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, +receive or can get the source code. And you must show them these +terms so they know their rights. +.PP +Developers that use the \s-1GNU GPL\s0 protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. +.PP +For the developers' and authors' protection, the \s-1GPL\s0 clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the \s-1GPL\s0 requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. +.PP +Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the +manufacturer can do so. This is fundamentally incompatible with the +aim of protecting users' freedom to change the software. The +systematic pattern of such abuse occurs in the area of products for +individuals to use, which is precisely where it is most unacceptable. +Therefore, we have designed this version of the \s-1GPL\s0 to prohibit the +practice for those products. If such problems arise substantially in +other domains, we stand ready to extend this provision to those +domains in future versions of the \s-1GPL,\s0 as needed to protect the +freedom of users. +.PP +Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish +to avoid the special danger that patents applied to a free program +could make it effectively proprietary. To prevent this, the \s-1GPL\s0 +assures that patents cannot be used to render the program non-free. +.PP +The precise terms and conditions for copying, distribution and +modification follow. +.SS "\s-1TERMS AND CONDITIONS\s0" +.IX Subsection "TERMS AND CONDITIONS" +.IP "0. Definitions." 4 +.IX Item "0. Definitions." +\&\*(L"This License\*(R" refers to version 3 of the \s-1GNU\s0 General Public License. +.Sp +\&\*(L"Copyright\*(R" also means copyright-like laws that apply to other kinds +of works, such as semiconductor masks. +.Sp +\&\*(L"The Program\*(R" refers to any copyrightable work licensed under this +License. Each licensee is addressed as \*(L"you\*(R". \*(L"Licensees\*(R" and +\&\*(L"recipients\*(R" may be individuals or organizations. +.Sp +To \*(L"modify\*(R" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of +an exact copy. The resulting work is called a \*(L"modified version\*(R" of +the earlier work or a work \*(L"based on\*(R" the earlier work. +.Sp +A \*(L"covered work\*(R" means either the unmodified Program or a work based +on the Program. +.Sp +To \*(L"propagate\*(R" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. +.Sp +To \*(L"convey\*(R" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user +through a computer network, with no transfer of a copy, is not +conveying. +.Sp +An interactive user interface displays \*(L"Appropriate Legal Notices\*(R" to +the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. +.IP "1. Source Code." 4 +.IX Item "1. Source Code." +The \*(L"source code\*(R" for a work means the preferred form of the work for +making modifications to it. \*(L"Object code\*(R" means any non-source form +of a work. +.Sp +A \*(L"Standard Interface\*(R" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. +.Sp +The \*(L"System Libraries\*(R" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +\&\*(L"Major Component\*(R", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. +.Sp +The \*(L"Corresponding Source\*(R" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. +.Sp +The Corresponding Source need not include anything that users can +regenerate automatically from other parts of the Corresponding Source. +.Sp +The Corresponding Source for a work in source code form is that same +work. +.IP "2. Basic Permissions." 4 +.IX Item "2. Basic Permissions." +All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. +.Sp +You may make, run and propagate covered works that you do not convey, +without conditions so long as your license otherwise remains in force. +You may convey covered works to others for the sole purpose of having +them make modifications exclusively for you, or provide you with +facilities for running those works, provided that you comply with the +terms of this License in conveying all material for which you do not +control copyright. Those thus making or running the covered works for +you must do so exclusively on your behalf, under your direction and +control, on terms that prohibit them from making any copies of your +copyrighted material outside their relationship with you. +.Sp +Conveying under any other circumstances is permitted solely under the +conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. +.IP "3. Protecting Users' Legal Rights From Anti-Circumvention Law." 4 +.IX Item "3. Protecting Users' Legal Rights From Anti-Circumvention Law." +No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the \s-1WIPO\s0 copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. +.Sp +When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such +circumvention is effected by exercising rights under this License with +respect to the covered work, and you disclaim any intention to limit +operation or modification of the work as a means of enforcing, against +the work's users, your or third parties' legal rights to forbid +circumvention of technological measures. +.IP "4. Conveying Verbatim Copies." 4 +.IX Item "4. Conveying Verbatim Copies." +You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. +.Sp +You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. +.IP "5. Conveying Modified Source Versions." 4 +.IX Item "5. Conveying Modified Source Versions." +You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these +conditions: +.RS 4 +.IP "a." 4 +.IX Item "a." +The work must carry prominent notices stating that you modified it, +and giving a relevant date. +.IP "b." 4 +.IX Item "b." +The work must carry prominent notices stating that it is released +under this License and any conditions added under section 7. This +requirement modifies the requirement in section 4 to \*(L"keep intact all +notices\*(R". +.IP "c." 4 +.IX Item "c." +You must license the entire work, as a whole, under this License to +anyone who comes into possession of a copy. This License will +therefore apply, along with any applicable section 7 additional terms, +to the whole of the work, and all its parts, regardless of how they +are packaged. This License gives no permission to license the work in +any other way, but it does not invalidate such permission if you have +separately received it. +.IP "d." 4 +.IX Item "d." +If the work has interactive user interfaces, each must display +Appropriate Legal Notices; however, if the Program has interactive +interfaces that do not display Appropriate Legal Notices, your work +need not make them do so. +.RE +.RS 4 +.Sp +A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +\&\*(L"aggregate\*(R" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. +.RE +.IP "6. Conveying Non-Source Forms." 4 +.IX Item "6. Conveying Non-Source Forms." +You may convey a covered work in object code form under the terms of +sections 4 and 5, provided that you also convey the machine-readable +Corresponding Source under the terms of this License, in one of these +ways: +.RS 4 +.IP "a." 4 +.IX Item "a." +Convey the object code in, or embodied in, a physical product +(including a physical distribution medium), accompanied by the +Corresponding Source fixed on a durable physical medium customarily +used for software interchange. +.IP "b." 4 +.IX Item "b." +Convey the object code in, or embodied in, a physical product +(including a physical distribution medium), accompanied by a written +offer, valid for at least three years and valid for as long as you +offer spare parts or customer support for that product model, to give +anyone who possesses the object code either (1) a copy of the +Corresponding Source for all the software in the product that is +covered by this License, on a durable physical medium customarily used +for software interchange, for a price no more than your reasonable +cost of physically performing this conveying of source, or (2) access +to copy the Corresponding Source from a network server at no charge. +.IP "c." 4 +.IX Item "c." +Convey individual copies of the object code with a copy of the written +offer to provide the Corresponding Source. This alternative is +allowed only occasionally and noncommercially, and only if you +received the object code with such an offer, in accord with subsection +6b. +.IP "d." 4 +.IX Item "d." +Convey the object code by offering access from a designated place +(gratis or for a charge), and offer equivalent access to the +Corresponding Source in the same way through the same place at no +further charge. You need not require recipients to copy the +Corresponding Source along with the object code. If the place to copy +the object code is a network server, the Corresponding Source may be +on a different server (operated by you or a third party) that supports +equivalent copying facilities, provided you maintain clear directions +next to the object code saying where to find the Corresponding Source. +Regardless of what server hosts the Corresponding Source, you remain +obligated to ensure that it is available for as long as needed to +satisfy these requirements. +.IP "e." 4 +.IX Item "e." +Convey the object code using peer-to-peer transmission, provided you +inform other peers where the object code and Corresponding Source of +the work are being offered to the general public at no charge under +subsection 6d. +.RE +.RS 4 +.Sp +A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. +.Sp +A \*(L"User Product\*(R" is either (1) a \*(L"consumer product\*(R", which means any +tangible personal property which is normally used for personal, +family, or household purposes, or (2) anything designed or sold for +incorporation into a dwelling. In determining whether a product is a +consumer product, doubtful cases shall be resolved in favor of +coverage. For a particular product received by a particular user, +\&\*(L"normally used\*(R" refers to a typical or common use of that class of +product, regardless of the status of the particular user or of the way +in which the particular user actually uses, or expects or is expected +to use, the product. A product is a consumer product regardless of +whether the product has substantial commercial, industrial or +non-consumer uses, unless such uses represent the only significant +mode of use of the product. +.Sp +\&\*(L"Installation Information\*(R" for a User Product means any methods, +procedures, authorization keys, or other information required to +install and execute modified versions of a covered work in that User +Product from a modified version of its Corresponding Source. The +information must suffice to ensure that the continued functioning of +the modified object code is in no case prevented or interfered with +solely because modification has been made. +.Sp +If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in \s-1ROM\s0). +.Sp +The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or +updates for a work that has been modified or installed by the +recipient, or for the User Product in which it has been modified or +installed. Access to a network may be denied when the modification +itself materially and adversely affects the operation of the network +or violates the rules and protocols for communication across the +network. +.Sp +Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. +.RE +.IP "7. Additional Terms." 4 +.IX Item "7. Additional Terms." +\&\*(L"Additional permissions\*(R" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. +.Sp +When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. +.Sp +Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders +of that material) supplement the terms of this License with terms: +.RS 4 +.IP "a." 4 +.IX Item "a." +Disclaiming warranty or limiting liability differently from the terms +of sections 15 and 16 of this License; or +.IP "b." 4 +.IX Item "b." +Requiring preservation of specified reasonable legal notices or author +attributions in that material or in the Appropriate Legal Notices +displayed by works containing it; or +.IP "c." 4 +.IX Item "c." +Prohibiting misrepresentation of the origin of that material, or +requiring that modified versions of such material be marked in +reasonable ways as different from the original version; or +.IP "d." 4 +.IX Item "d." +Limiting the use for publicity purposes of names of licensors or +authors of the material; or +.IP "e." 4 +.IX Item "e." +Declining to grant rights under trademark law for use of some trade +names, trademarks, or service marks; or +.IP "f." 4 +.IX Item "f." +Requiring indemnification of licensors and authors of that material by +anyone who conveys the material (or modified versions of it) with +contractual assumptions of liability to the recipient, for any +liability that these contractual assumptions directly impose on those +licensors and authors. +.RE +.RS 4 +.Sp +All other non-permissive additional terms are considered \*(L"further +restrictions\*(R" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. +.Sp +If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. +.Sp +Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; the +above requirements apply either way. +.RE +.IP "8. Termination." 4 +.IX Item "8. Termination." +You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). +.Sp +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. +.Sp +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. +.Sp +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. +.IP "9. Acceptance Not Required for Having Copies." 4 +.IX Item "9. Acceptance Not Required for Having Copies." +You are not required to accept this License in order to receive or run +a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. +.IP "10. Automatic Licensing of Downstream Recipients." 4 +.IX Item "10. Automatic Licensing of Downstream Recipients." +Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. +.Sp +An \*(L"entity transaction\*(R" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. +.Sp +You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. +.IP "11. Patents." 4 +.IX Item "11. Patents." +A \*(L"contributor\*(R" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's \*(L"contributor version\*(R". +.Sp +A contributor's \*(L"essential patent claims\*(R" are all patent claims owned +or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, \*(L"control\*(R" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. +.Sp +Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. +.Sp +In the following three paragraphs, a \*(L"patent license\*(R" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To \*(L"grant\*(R" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. +.Sp +If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. \*(L"Knowingly relying\*(R" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. +.Sp +If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. +.Sp +A patent license is \*(L"discriminatory\*(R" if it does not include within the +scope of its coverage, prohibits the exercise of, or is conditioned on +the non-exercise of one or more of the rights that are specifically +granted under this License. You may not convey a covered work if you +are a party to an arrangement with a third party that is in the +business of distributing software, under which you make payment to the +third party based on the extent of your activity of conveying the +work, and under which the third party grants, to any of the parties +who would receive the covered work from you, a discriminatory patent +license (a) in connection with copies of the covered work conveyed by +you (or copies made from those copies), or (b) primarily for and in +connection with specific products or compilations that contain the +covered work, unless you entered into that arrangement, or that patent +license was granted, prior to 28 March 2007. +.Sp +Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. +.IP "12. No Surrender of Others' Freedom." 4 +.IX Item "12. No Surrender of Others' Freedom." +If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey +a covered work so as to satisfy simultaneously your obligations under +this License and any other pertinent obligations, then as a +consequence you may not convey it at all. For example, if you agree +to terms that obligate you to collect a royalty for further conveying +from those to whom you convey the Program, the only way you could +satisfy both those terms and this License would be to refrain entirely +from conveying the Program. +.IP "13. Use with the \s-1GNU\s0 Affero General Public License." 4 +.IX Item "13. Use with the GNU Affero General Public License." +Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the \s-1GNU\s0 Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the \s-1GNU\s0 Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. +.IP "14. Revised Versions of this License." 4 +.IX Item "14. Revised Versions of this License." +The Free Software Foundation may publish revised and/or new versions +of the \s-1GNU\s0 General Public License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. +.Sp +Each version is given a distinguishing version number. If the Program +specifies that a certain numbered version of the \s-1GNU\s0 General Public +License \*(L"or any later version\*(R" applies to it, you have the option of +following the terms and conditions either of that numbered version or +of any later version published by the Free Software Foundation. If +the Program does not specify a version number of the \s-1GNU\s0 General +Public License, you may choose any version ever published by the Free +Software Foundation. +.Sp +If the Program specifies that a proxy can decide which future versions +of the \s-1GNU\s0 General Public License can be used, that proxy's public +statement of acceptance of a version permanently authorizes you to +choose that version for the Program. +.Sp +Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. +.IP "15. Disclaimer of Warranty." 4 +.IX Item "15. Disclaimer of Warranty." +\&\s-1THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW.\s0 \s-1EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM \*(L"AS IS\*(R" WITHOUT +WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE.\s0 \s-1THE ENTIRE RISK AS TO THE QUALITY AND +PERFORMANCE OF THE PROGRAM IS WITH YOU.\s0 \s-1SHOULD THE PROGRAM PROVE +DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR +CORRECTION.\s0 +.IP "16. Limitation of Liability." 4 +.IX Item "16. Limitation of Liability." +\&\s-1IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR +CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM\s0 (\s-1INCLUDING BUT +NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR +LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM +TO OPERATE WITH ANY OTHER PROGRAMS\s0), \s-1EVEN IF SUCH HOLDER OR OTHER +PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.\s0 +.IP "17. Interpretation of Sections 15 and 16." 4 +.IX Item "17. Interpretation of Sections 15 and 16." +If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. +.SS "\s-1END OF TERMS AND CONDITIONS\s0" +.IX Subsection "END OF TERMS AND CONDITIONS" +.SS "How to Apply These Terms to Your New Programs" +.IX Subsection "How to Apply These Terms to Your New Programs" +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. +.PP +To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the \*(L"copyright\*(R" line and a pointer to where the full notice is found. +.PP +.Vb 2 +\& +\& Copyright (C) +\& +\& This program is free software: you can redistribute it and/or modify +\& it under the terms of the GNU General Public License as published by +\& the Free Software Foundation, either version 3 of the License, or (at +\& your option) any later version. +\& +\& This program is distributed in the hope that it will be useful, but +\& WITHOUT ANY WARRANTY; without even the implied warranty of +\& MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +\& General Public License for more details. +\& +\& You should have received a copy of the GNU General Public License +\& along with this program. If not, see . +.Ve +.PP +Also add information on how to contact you by electronic and paper mail. +.PP +If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: +.PP +.Vb 4 +\& Copyright (C) +\& This program comes with ABSOLUTELY NO WARRANTY; for details type "show w". +\& This is free software, and you are welcome to redistribute it +\& under certain conditions; type "show c" for details. +.Ve +.PP +The hypothetical commands \fBshow w\fR and \fBshow c\fR should show +the appropriate parts of the General Public License. Of course, your +program's commands might be different; for a \s-1GUI\s0 interface, you would +use an \*(L"about box\*(R". +.PP +You should also get your employer (if you work as a programmer) or school, +if any, to sign a \*(L"copyright disclaimer\*(R" for the program, if necessary. +For more information on this, and how to apply and follow the \s-1GNU GPL,\s0 see +<\fBhttps://www.gnu.org/licenses/\fR>. +.PP +The \s-1GNU\s0 General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use +the \s-1GNU\s0 Lesser General Public License instead of this License. But +first, please read <\fBhttps://www.gnu.org/licenses/why\-not\-lgpl.html\fR>. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIgfdl\fR\|(7), \fIfsf\-funding\fR\|(7). +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 2007 Free Software Foundation, Inc. +.PP +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. diff --git a/static/netbsd/man7/krb5-plugin.7 b/static/netbsd/man7/krb5-plugin.7 new file mode 100644 index 00000000..6e05bd3e --- /dev/null +++ b/static/netbsd/man7/krb5-plugin.7 @@ -0,0 +1,247 @@ +.\" $NetBSD: krb5-plugin.7,v 1.3 2023/06/19 21:41:44 christos Exp $ +.\" +.\" Copyright (c) 1999 - 2005 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd December 21, 2011 +.Dt KRB5-PLUGIN 7 +.Os HEIMDAL +.Sh NAME +.Nm krb5-plugin +.Nd plugin interface for Heimdal +.Sh SYNOPSIS +.In krb5.h +.In krb5/an2ln_plugin.h +.In krb5/ccache_plugin.h +.In krb5/db_plugin.h +.In krb5/kuserok_plugin.h +.In krb5/locate_plugin.h +.In krb5/send_to_kdc_plugin.h +.Sh DESCRIPTION +Heimdal has a plugin interface. Plugins may be statically linked into +Heimdal and registered via the +.Xr krb5_plugin_register 3 +function, or they may be dynamically loaded from shared objects present +in the Heimdal plugins directories. +.Pp +Plugins consist of a C struct whose struct name is given in the +associated header file, such as, for example, +.Va krb5plugin_kuserok_ftable +and a pointer to which is either registered via +.Xr krb5_plugin_register 3 +or found in a shared object via a symbol lookup for the symbol name +defined in the associated header file (e.g., "kuserok" for the +plugin for +.Xr krb5_kuserok 3 +). +.Pp +The plugin structs for all plugin types always begin with the same three +common fields: +.Bl -enum -compact +.It +.Va minor_version +, an int. Plugin minor versions are defined in each plugin type's +associated header file. +.It +.Va init +, a pointer to a function with two arguments, a krb5_context and a +void **, returning a krb5_error_code. This function will be called to +initialize a plugin-specific context in the form of a void * that will +be output through the init function's second argument. +.It +.Va fini +, a pointer to a function of one argument, a void *, consisting of the +plugin's context to be destroyed, and returning void. +.El +.Pp +Each plugin type must add zero or more fields to this struct following +the above three. Plugins are typically invoked in no particular order +until one succeeds or fails, or all return a special return value such +as KRB5_PLUGIN_NO_HANDLE to indicate that the plugin was not applicable. +Most plugin types obtain deterministic plugin behavior in spite of the +non-deterministic invocation order by, for example, invoking all plugins +for each "rule" and passing the rule to each plugin with the expectation +that just one plugin will match any given rule. +.Pp +There is a database plugin system intended for many of the uses of +databases in Heimdal. The plugin is expected to call +.Xr heim_db_register 3 +from its +.Va init +entry point to register a DB type. The DB plugin's +.Va fini +function must do nothing, and the plugin must not provide any other +entry points. +.Pp +The krb5_kuserok plugin adds a single field to its struct: a pointer to +a function that implements kuserok functionality with the following +form: +.Bd -literal -offset indent +static krb5_error_code +kuserok(void *plug_ctx, krb5_context context, const char *rule, + unsigned int flags, const char *k5login_dir, + const char *luser, krb5_const_principal principal, + krb5_boolean *result) +.Ed +.Pp +The +.Va luser +, +.Va principal +and +.Va result +arguments are self-explanatory (see +.Xr krb5_kuserok 3 +). The +.Va plug_ctx +argument is the context output by the plugin's init function. The +.Va rule +argument is a kuserok rule from the krb5.conf file; each plugin is invoked once +for each rule until all plugins fail or one succeeds. The +.Va k5login_dir +argument provides an alternative k5login file location, if not NULL. +The +.Va flags +argument indicates whether the plugin may call +.Xr krb5_aname_to_localname 3 +(KUSEROK_ANAME_TO_LNAME_OK), and whether k5login databases are expected to be +authoritative (KUSEROK_K5LOGIN_IS_AUTHORITATIVE). +.Pp +The plugin for +.Xr krb5_aname_to_localname 3 +is named "an2ln" and has a single extra field for the plugin struct: +.Bd -literal -offset indent +typedef krb5_error_code (*set_result_f)(void *, const char *); + +static krb5_error_code +an2ln(void *plug_ctx, krb5_context context, const char *rule, + krb5_const_principal aname, set_result_f set_res_f, void *set_res_ctx) +.Ed +.Pp +The arguments for the +.Va an2ln +plugin are similar to those of the kuserok plugin, but the result, being +a string, is set by calling the +.Va set_res_f +function argument with the +.Va set_res_ctx +and result string as arguments. The +.Va set_res_f +function will make a copy of the string. +.Sh FILES +.Bl -tag -compact +.It Pa libdir/plugin/krb5/* +Shared objects containing plugins for Heimdal. +.El +.Sh EXAMPLES +.Pp +An example an2ln plugin that maps principals to a constant "nouser" +follows: +.Pp +.Bd -literal -offset indent +#include + +static krb5_error_code KRB5_CALLCONV +nouser_plug_init(krb5_context context, void **ctx) +{ + *ctx = NULL; + return 0; +} + +static void KRB5_CALLCONV nouser_plug_fini(void *ctx) { } + +static krb5_error_code KRB5_CALLCONV +nouser_plug_an2ln(void *plug_ctx, krb5_context context, + const char *rule, + krb5_const_principal aname, + set_result_f set_res_f, void *set_res_ctx) +{ + krb5_error_code ret; + + if (strcmp(rule, "NOUSER") != 0) + return KRB5_PLUGIN_NO_HANDLE; + + ret = set_res_f(set_res_ctx, "nouser"); + + return ret; +} + +krb5plugin_an2ln_ftable an2ln = { + KRB5_PLUGIN_AN2LN_VERSION_0, + nouser_plug_init, + nouser_plug_fini, + nouser_plug_an2ln, +}; +.Ed +.Pp +An example kuserok plugin that rejects all requests follows. (Note that +there exists a built-in plugin with this functionality; see +.Xr krb5_kuserok 3 +). +.Pp +.Bd -literal -offset indent +#include + +static krb5_error_code KRB5_CALLCONV +reject_plug_init(krb5_context context, void **ctx) +{ + *ctx = NULL; + return 0; +} + +static void KRB5_CALLCONV reject_plug_fini(void *ctx) { } + +static krb5_error_code KRB5_CALLCONV +reject_plug_kuserok(void *plug_ctx, krb5_context context, const char *rule, + unsigned int flags, const char *k5login_dir, + const char *luser, krb5_const_principal principal, + krb5_boolean *result) +{ + if (strcmp(rule, "REJECT") != 0) + return KRB5_PLUGIN_NO_HANDLE; + + *result = FALSE; + return 0; +} + +krb5plugin_kuserok_ftable kuserok = { + KRB5_PLUGIN_KUSEROK_VERSION_0, + reject_plug_init, + reject_plug_fini, + reject_plug_kuserok, +}; +.Ed +.Sh SEE ALSO +.Xr krb5_plugin_register 3 +.Xr krb5_kuserok 3 +.Xr krb5_aname_to_localname 3 diff --git a/static/netbsd/man7/kyua-atf-interface.7 b/static/netbsd/man7/kyua-atf-interface.7 new file mode 100644 index 00000000..acf541be --- /dev/null +++ b/static/netbsd/man7/kyua-atf-interface.7 @@ -0,0 +1,405 @@ +.\" Copyright 2012 Google Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" * Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" * Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" * Neither the name of Google Inc. nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.Dd September 9, 2012 +.Dt KYUA-ATF-INTERFACE 1 +.Os +.Sh NAME +.Nm atf-interface +.Nd Description of the ATF test program interface +.Sh DESCRIPTION +The interface of ATF test programs is the interface of the test +programs linked to the +.Nm atf-c , +.Nm atf-c++ +and +.Nm atf-sh +libraries provided by ATF. +.Pp +The ATF interface can be understood as the mechanisms used by test programs +to communicate with the runtime engine as well as the assumptions that test +programs and test cases can make while running. +.Pp +A test case is the most basic part of a test suite. A test case is +supposed to reproduce one, and only one, scenario. For example: if the +item under test was a function, the test case would provide a single set of +input parameters to the function and check its output; If the item under +test was a binary, the test case would provide a single set of arguments to +the program and check its behavior. +.Ss Test case parts +Test cases have three parts: +.Bl -tag -width cleanupXX +.It Head +Programmatically defines metadata properties. The head must not perform +any other thing than defining such properties. In particular, no testing +whatsoever can happen in the head. (Ideally the definition of metadata +properties would not happen programmatically.) +.It Body +The actual test case which performs any desired testing and reports a +result. The body is executed by the runtime engine in a deterministic way; +see the isolation section below. +.It Cleanup +An optional cleanup routine. Note that the runtime engine will attempt to +clean up the work directory automatically, so this routine should only be +provided in cases where the test modifies system-wide state not known by +the runtime engine. The cleanup part is executed in the same directory as +the body. However, the body and the cleanup parts +.Em do not share the same process space ; +the only way to pass data around from the body to the cleanup is by means +of files in the work directory. +.El +.Ss Metadata properties +The following test case metadata properties must be exported in the test +case list for every test case: +.Bl -tag -width XX +.It Va ident +Single-word string. The name of the test case. Must be unique within the +test program. +.El +.Pp +The following test case metadata properties may be exported in the +test case list for every test case: +.Bl -tag -width XX +.It Va descr +Multi-word string. A textual description for the test case. Usually, +providing a descriptive identifier is better than providing a textual +description. +.It Va has.cleanup +Boolean. Whether the test case defines a cleanup routine or not. +.It Va require.arch +Whitespace separated list of the architectures required by the test case. +If defined, the test case is skipped unless the host architecture matches +any of the values defined in this property. +.It Va require.config +Whitespace separated list of configuration variable names. The list of +configuration variables that must be defined. The test is skipped if any +of these is missing. +.It Va require.files +Whitespace separated list of absolute paths to installed files. If any of +these files is not found, the test case is skipped. +.It Va require.machine +Whitespace separated list of the machine types required by the test case. +If defined, the test case is skipped unless the host machine type matches +any of the values defined in this property. +.It Va require.progs +Whitespace separated list of program names (either absolute names or base +names). If any of these programs is not found, the test case is skipped. +.It Va require.user +Either +.Sq root +or +.Sq unprivileged . +If +.Sq root , +the test case must be run as the superuser or otherwise it is skipped. If +.Sq unprivileged , +the test case must be run as an unprivileged user or else it is skipped. +.It Va timeout +Integer. The amount of seconds the test case can run for before it is +killed by the runtime engine. +.El +.Ss Configuration properties +The following properties may be defined by the runtime engine and are +propagated to the test cases: +.Bl -tag -width XX +.It Va unprivileged-user +String, optional. Specifies the name of the user under which tests that +set +.Sq require.user=unprivileged +are executed. +.El +.Ss Results +A test case must always report a result by creating the results file +specified through the +.Fl r +flag. For convenience when running test cases without the runtime engine, +this file may point to +.Pa /dev/stdout +or +.Pa /dev/stderr +in which case the file must not be created (because the creation will +fail). +.Pp +Aside from creating the results file, the process in which the test case +runs must terminate in particular ways for the test result to be considered +valid. +.Pp +If the test case fails to create the test result, if the test result is +created but contains an invalid syntax, or if the termination status of the +process does not match the requirements of the test result, the runtime +engine marks the test case as +.Sq broken . +Note that the +.Sq broken +state is decided by the runtime engine; a test case cannot report itself as +.Sq broken . +.Pp +The general syntax for the results file is as follows: +.Bd -literal -offset indent +[[(int)]: reason] +.Ed +.Pp +The following results are allowed: +.Bl -tag -width XX +.It expected_death +The process is expected to terminate either due to a clean call to +.Xr exit 3 +or due to the reception of a signal. The contents of the file are +.Sq expected_death: \\n . +Example: +.Sq expected_death: Calling libdofoo breaks due to bug xyz . +.It expected_exit +The process is expected to terminate cleanly. The contents of the file are +.Sq expected_exit: +if the exit code is irrelevant or +.Sq expected_exit(): +if the process must terminate with a given exit code. Examples: +.Sq expected_exit: Calling bar exits but it should not +or +.Sq expected_exit(123): Calling bar exits with an unexpected code . +.It expected_failure +The process must exit cleanly with an +.Va EXIT_SUCCESS +exit code. The contents of the file are +.Sq expected_failure: \\n +Example: +.Sq expected_failure: 2 + 2 = 3 . +.It expected_signal +The process is expected to terminate due to the reception of a signal. The +contents of the file are +.Sq expected_signal: +if the signal number is irrelevant or +.Sq expected_signal(): +if the process must terminate due to a particular signal. Examples: +.Sq expected_signal: Calling bar crashes +or +.Sq expected_signal(1): Calling bar kills ourselves due to unhandled SIGHUP . +.It expected_timeout +The process is expected to hang for longer than its +.Va timeout +metadata property. Only the runtime engine can control this situation +because the runtime engine is the one implementing the timeout +functionality. +.It failed +The process must exit cleanly with an +.Va EXIT_FAILURE +exit code. The contents of the file are +.Sq failed: \\n . +Example: +.Sq failed: Failed on purpose\\n . +.It passed +The process must exit cleanly with an +.Va EXIT_SUCCESS +exit code. The contents of the file are +.Sq passed\\n . +.It skipped +The process must exit cleanly with an +.Va EXIT_SUCCESS +exit code. The contents of the file are +.Sq skipped: \\n . +Example: +.Sq skipped: Skipped because the foo is not present\\n . +.El +.Ss Isolation +The runtime engine attempts to isolate test cases from other test cases in +the same test program and from the rest of the system by performing what is +called +.Em test case isolation . +.Pp +Whenever the user runs a test program binary by hand (i.e. not through +.Xr kyua 1 ) , +the test program will print a warning message stating that test case +isolation does not work and therefore the program may cause side-effects +and/or report invalid values. +.Pp +The runtime engine must set the +.Va __RUNNING_INSIDE_ATF_RUN +environment variable to the magic value +.Sq internal-yes-value +to tell the test programs that they are being run with isolation enabled. +.Pp +The test case isolation performs the following: +.Bl -tag -width XX +.It Process space +Each test case body and cleanup routines are executed in independent +processes. Corollary: the test case can do whatever it wants to the +current process (such as modifying global variables) without having to undo +such changes. +.It Process group +The test case body and cleanup are executed in their own process groups. +Should they spawn any children, such children should maintain the same +process group. This is done to allow the runtime engine to kill the whole +process subtree once the test case finishes (or if the test case hangs). +.It Work directory +The test case body and its cleanup (if any) are executed in a temporary +directory automatically created by the runtime engine. This temporary +directory is shared among the body and cleanup parts of a single test case +but is completely separate from the temporary directories of other tests. +Corollary: the test case body and cleanup routines can write to their +current directory without bothering to clean any files and/or directories +they create. The runtime engine takes care to recursively delete the +temporary directories after the execution of a test case. Any file systems +mounted within the temporary directory will be unmounted if possible. +.It Home directory +The +.Va HOME +environment variable is set to the absolute path of the work directory. +.It Umask +The value of the umask is set to 0022. +.It Environment +The +.Va LANG , +.Va LC_ALL , +.Va LC_COLLATE , +.Va LC_CTYPE , +.Va LC_MESSAGES , +.Va LC_MONETARY , +.Va LC_NUMERIC +and +.Va LC_TIME +variables are unset. The +.Va TZ +variable is set to +.Sq UTC . +.It Process limits +The maximum soft core size limit is raised to its corresponding hard limit. +This is a simple, best-effort attempt at allowing test cases to dump core +for further diagnostic purposes. +.El +.Ss Test programs +A test program is, simply put, a collection of related test cases. The +test program can be seen as a command-line dispatcher for the test cases. +A test program must provide one or more test cases. If it does not contain +any test case, the runtime system will report it as invalid. +.Pp +Test programs expose their list of test cases in a machine parseable +format. The runtime engine obtains the list of test cases to know what +tests to run and to know how to set up the environment of each test prior +execution. The test program must not do any test when asked to dump its +test case list. +.Pp +The generic syntax to obtain the list of test cases included in a test +program is: +.Bd -literal -offset indent + -l +.Ed +.Pp +The list of test cases follows the following format: +.Bd -literal -offset indent +LIST ::= HEADER NEWLINE TEST_CASES + +HEADER ::= 'Content-Type: application/X-atf-tp; version="1"' +NEWLINE ::= '\\n' +TEST_CASES ::= TEST_CASE | TEST_CASE NEWLINE TEST_CASES + +TEST_CASE ::= IDENT_PROPERTY PROPERTIES +IDENT_PROPERTY ::= 'ident' DELIM STRING NEWLINE +DELIM ::= ': ' + +PROPERTIES ::= PROPERTY | PROPERTY PROPERTIES +PROPERTY ::= PROPERTY_NAME DELIM STRING NEWLINE +PROPERTY_NAME ::= (see below) +.Ed +.Pp +An example: +.Bd -literal -offset indent +Content-Type: application/X-atf-tp; version="1" + +ident: addition +descr: Tests that the addition function works + +ident: subtraction +descr: Tests that the subtraction function works + +ident: remove +descr: Tests removing files +require.root: true +timeout: 50 +has.cleanup: true +.Ed +.Pp +The syntax to run a test case body part is: +.Bd -literal -offset indent + [-r resfile] [-s srcdir] [-v var=value]* [:body] +.Ed +.Pp +This must run the test case body +.Dq as is , +without any attempt of isolating it from the rest of the system. It is the +responsibility of the runtime engine to do such isolation. +.Pp +The runtime engine always passes the path of a nonexistent file to +.Fl r , +which must be created by the test case; and always passes an absolute path +to the +.Fl s +flag pointing to the directory containing the test program executable. +.Pp +The runtime engine shall pass any configuration variables it wants through +the +.Fl v +flag, and these can be later inspected by the test case at will. +.Pp +A note to users: if you run the test case by hand (not through +.Xr kyua 1 nor +.Xr atf-run 1 ) +from the command line, none of the isolation features described in the +isolation section apply. This means that the test case can (and probably +will) write to the current directory and leave garbage behind. Also, given +that the test case is executed without e.g. clearing the environment, the +results of the test case may differ from those obtained when running the +test case inside the runtime engine. +.Em Only use this for debugging purposes +(i.e. to run the test case code under GDB). +.Pp +The syntax to run a test case cleanup part is: +.Bd -literal -offset indent + [-s srcdir] [-v var=value]* :cleanup +.Ed +.Pp +This can only be performed if and only if the test case sets the +.Va has.cleanup +property to true. Otherwise the behavior of executing the cleanup part is +undefined. +.Pp +The same rules for +.Fl s +and +.Fl v +apply as to when running the body. +.Pp +The cleanup part must be executed in the same directory as the body but in +a separate process space. The only way for test cases to transfer state +(if any) from the body to the cleanup routine is by means of files in the +current directory. +.Pp +The cleanup part does not have to worry about deleting temporary files +created in the current directory. The runtime engine does this +automatically. +.Sh SEE ALSO +.Xr kyua-test 1 , +.Xr kyuafile 5 diff --git a/static/netbsd/man7/kyua-plain-interface.7 b/static/netbsd/man7/kyua-plain-interface.7 new file mode 100644 index 00000000..e0b30590 --- /dev/null +++ b/static/netbsd/man7/kyua-plain-interface.7 @@ -0,0 +1,63 @@ +.\" Copyright 2012 Google Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" * Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" * Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" * Neither the name of Google Inc. nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.Dd September 9, 2012 +.Dt KYUA-PLAIN-INTERFACE 1 +.Os +.Sh NAME +.Nm plain-interface +.Nd Description of the plain test program interface +.Sh DESCRIPTION +The +.Em plain test interface +is the interface of test programs that return their pass/fail status as an +exit code. While simple, this interface is what legacy test programs use +and what test programs written with many other testing libraries use too. +.Pp +Kyua supports this interface for two main reasons: first, to simplify the +incorporation of legacy test programs into a Kyua test suite; and, second, +to ensure that the Kyua run-time engine does not become tied to a +particular test interface. +.Pp +The results of a plain test are one of the following: +.Bl -tag -width passedXX +.It passed +If the test program exits with a success exit code; i.e. 0. +.It failed +If the test program exits with a failure exit code; i.e. not 0. +.It broken +If the test program exits due to any other reason (e.g. it crashes) or +if it fails to be executed. +.El +.Pp +Plain test programs are executed with the same isolation features as +ATF test programs; see +.Xr kyua-atf-interface 7 . +.Sh SEE ALSO +.Xr kyua-test 1 , +.Xr kyuafile 5 , +.Xr kyua-atf-interface 7 diff --git a/static/netbsd/man7/life_cycle-cipher.7 b/static/netbsd/man7/life_cycle-cipher.7 new file mode 100644 index 00000000..ddf5ebe4 --- /dev/null +++ b/static/netbsd/man7/life_cycle-cipher.7 @@ -0,0 +1,210 @@ +.\" $NetBSD: life_cycle-cipher.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "LIFE_CYCLE-CIPHER 7" +.TH LIFE_CYCLE-CIPHER 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +life_cycle\-cipher \- The cipher algorithm life\-cycle +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All symmetric ciphers (CIPHERs) go through a number of stages in their +life\-cycle: +.IP start 4 +.IX Item "start" +This state represents the CIPHER before it has been allocated. It is the +starting state for any life\-cycle transitions. +.IP newed 4 +.IX Item "newed" +This state represents the CIPHER after it has been allocated. +.IP initialised 4 +.IX Item "initialised" +These states represent the CIPHER when it is set up and capable of processing +input. There are three possible initialised states: +.RS 4 +.IP "initialised using EVP_CipherInit" 4 +.IX Item "initialised using EVP_CipherInit" +.PD 0 +.IP "initialised for decryption using EVP_DecryptInit" 4 +.IX Item "initialised for decryption using EVP_DecryptInit" +.IP "initialised for encryption using EVP_EncryptInit" 4 +.IX Item "initialised for encryption using EVP_EncryptInit" +.PD +.RE +.RS 4 +.RE +.IP updated 4 +.IX Item "updated" +These states represent the CIPHER when it is set up and capable of processing +additional input or generating output. The three possible states directly +correspond to those for initialised above. The three different streams should +not be mixed. +.IP finaled 4 +.IX Item "finaled" +This state represents the CIPHER when it has generated output. +.IP freed 4 +.IX Item "freed" +This state is entered when the CIPHER is freed. It is the terminal state +for all life\-cycle transitions. +.SS "State Transition Diagram" +.IX Subsection "State Transition Diagram" +The usual life\-cycle of a CIPHER is illustrated: + +---------------------------+ + | | + | start | + | | + +---------------------------+ + - - - - - - - - - - - - - + + | \*(Aq any of the initialised \*(Aq + | EVP_CIPHER_CTX_new \*(Aq updated or finaled states \*(Aq + v \*(Aq \*(Aq + +---------------------------+ + - - - - - - - - - - - - - + + | | | + | newed | | EVP_CIPHER_CTX_reset + | | <----+ + +---------------------------+ + | | | + +---------+ | +---------+ + EVP_DecryptInit | | EVP_CipherInit | EVP_EncryptInit + v v v + +---------------------------+ +---------------------------+ +---------------------------+ + | | | | | | + | initialised | | initialised | | initialised | + | for decryption | | | | for encryption | + +---------------------------+ +---------------------------+ +---------------------------+ + | | | + | EVP_DecryptUpdate | EVP_CipherUpdate EVP_EncryptUpdate | + | v | + | +---------------------------+ | + | | |--------------------+ | + | | updated | EVP_CipherUpdate | | + | | | <------------------+ | + v +---------------------------+ v + +---------------------------+ | +---------------------------+ + | |---------------------+ | | | + | updated | EVP_DecryptUpdate | | | updated |------+ + | for decryption | <-------------------+ | | for encryption | | + +---------------------------+ | +---------------------------+ | + | EVP_CipherFinal | | ^ | + +-------+ | +--------+ | | + EVP_DecryptFinal | | | EVP_EncryptFinal +-------------------+ + v v v EVP_EncryptUpdate + +---------------------------+ + | |-----------------------------+ + | finaled | | + | | <---------------------------+ + +---------------------------+ EVP_CIPHER_CTX_get_params + | (AEAD encryption) + | EVP_CIPHER_CTX_free + v + +---------------------------+ + | | + | freed | + | | + +---------------------------+ +.SS "Formal State Transitions" +.IX Subsection "Formal State Transitions" +This section defines all of the legal state transitions. +This is the canonical list. + Function Call ---------------------------------------------- Current State ----------------------------------------------- + start newed initialised updated finaled initialised updated initialised updated freed + decryption decryption encryption encryption + EVP_CIPHER_CTX_new newed + EVP_CipherInit initialised initialised initialised initialised initialised initialised initialised initialised + EVP_DecryptInit initialised initialised initialised initialised initialised initialised initialised initialised + decryption decryption decryption decryption decryption decryption decryption decryption + EVP_EncryptInit initialised initialised initialised initialised initialised initialised initialised initialised + encryption encryption encryption encryption encryption encryption encryption encryption + EVP_CipherUpdate updated updated + EVP_DecryptUpdate updated updated + decryption decryption + EVP_EncryptUpdate updated updated + encryption encryption + EVP_CipherFinal finaled + EVP_DecryptFinal finaled + EVP_EncryptFinal finaled + EVP_CIPHER_CTX_free freed freed freed freed freed freed freed freed freed + EVP_CIPHER_CTX_reset newed newed newed newed newed newed newed newed + EVP_CIPHER_CTX_get_params newed initialised updated initialised updated initialised updated + decryption decryption encryption encryption + EVP_CIPHER_CTX_set_params newed initialised updated initialised updated initialised updated + decryption decryption encryption encryption + EVP_CIPHER_CTX_gettable_params newed initialised updated initialised updated initialised updated + decryption decryption encryption encryption + EVP_CIPHER_CTX_settable_params newed initialised updated initialised updated initialised updated + decryption decryption encryption encryption +.SH NOTES +.IX Header "NOTES" +At some point the EVP layer will begin enforcing the transitions described +herein. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-cipher\fR\|(7), \fBEVP_EncryptInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/life_cycle-digest.7 b/static/netbsd/man7/life_cycle-digest.7 new file mode 100644 index 00000000..80c06021 --- /dev/null +++ b/static/netbsd/man7/life_cycle-digest.7 @@ -0,0 +1,189 @@ +.\" $NetBSD: life_cycle-digest.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "LIFE_CYCLE-DIGEST 7" +.TH LIFE_CYCLE-DIGEST 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +life_cycle\-digest \- The digest algorithm life\-cycle +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All message digests (MDs) go through a number of stages in their life\-cycle: +.IP start 4 +.IX Item "start" +This state represents the MD before it has been allocated. It is the +starting state for any life\-cycle transitions. +.IP newed 4 +.IX Item "newed" +This state represents the MD after it has been allocated. +.IP initialised 4 +.IX Item "initialised" +This state represents the MD when it is set up and capable of processing +input. +.IP updated 4 +.IX Item "updated" +This state represents the MD when it is set up and capable of processing +additional input or generating output. +.IP finaled 4 +.IX Item "finaled" +This state represents the MD when it has generated output. +For an XOF digest, this state represents the MD when it has generated a +single\-shot output. +.IP squeezed 4 +.IX Item "squeezed" +For an XOF digest, this state represents the MD when it has generated output. +It can be called multiple times to generate more output. The output length is +variable for each call. +.IP freed 4 +.IX Item "freed" +This state is entered when the MD is freed. It is the terminal state +for all life\-cycle transitions. +.SS "State Transition Diagram" +.IX Subsection "State Transition Diagram" +The usual life\-cycle of a MD is illustrated: + +--------------------+ + | start | + +--------------------+ + | EVP_MD_CTX_reset + | EVP_MD_CTX_new +-------------------------------------------------+ + v v | + EVP_MD_CTX_reset + - - - - - - - - - - - - - - - - - - - - - - + EVP_MD_CTX_reset | + +-------------------> \*(Aq newed \*(Aq <--------------------+ | + | + - - - - - - - - - - - - - - - - - - - - - - + | | + | | | | + | | EVP_DigestInit | | + | v | | + | EVP_DigestInit + - - - - - - - - - - - - - - - - - - - - - - + | | + +----+-------------------> \*(Aq initialised \*(Aq <+ EVP_DigestInit | | + | | + - - - - - - - - - - - - - - - - - - - - - - + | | | + | | | ^ | | | + | | | EVP_DigestUpdate | EVP_DigestInit | | | + | | v | | | | + | | +---------------------------------------------+ | | | + | +-------------------- | | | | | + | | | | | | + | EVP_DigestUpdate | | | | | + | +-------------------- | | | | | + | | | updated | | | | + | +-------------------> | | | | | + | | | | | | + | | | | | | + +----+------------------------- | | -+-------------------+----+ | + | | +---------------------------------------------+ | | | | + | | | | | | | + | | | EVP_DigestSqueeze +-------------------+ | | | + | | v | | | | + | | EVP_DigestSqueeze +---------------------------------------------+ | | | + | | +-------------------- | | | | | + | | | | squeezed | | | | + | | +-------------------> | | ---------------------+ | | + | | +---------------------------------------------+ | | + | | | | | + | | +---------------------------------------+ | | + | | | | | + | | +---------------------------------------------+ EVP_DigestFinalXOF | | | + | +------------------------- | finaled | <--------------------+----+ | + | +---------------------------------------------+ | | + | EVP_DigestFinal ^ | | | | + +---------------------------------+ | | EVP_MD_CTX_free | | + | v | | + | +------------------+ EVP_MD_CTX_free | | + | | freed | <--------------------+ | + | +------------------+ | + | | + +------------------------------------------------------+ +.SS "Formal State Transitions" +.IX Subsection "Formal State Transitions" +This section defines all of the legal state transitions. +This is the canonical list. + Function Call --------------------- Current State ----------------------------------- + start newed initialised updated finaled squeezed freed + EVP_MD_CTX_new newed + EVP_DigestInit initialised initialised initialised initialised initialised + EVP_DigestUpdate updated updated + EVP_DigestFinal finaled + EVP_DigestFinalXOF finaled + EVP_DigestSqueeze squeezed squeezed + EVP_MD_CTX_free freed freed freed freed freed + EVP_MD_CTX_reset newed newed newed newed + EVP_MD_CTX_get_params newed initialised updated + EVP_MD_CTX_set_params newed initialised updated + EVP_MD_CTX_gettable_params newed initialised updated + EVP_MD_CTX_settable_params newed initialised updated + EVP_MD_CTX_copy_ex newed initialised updated squeezed +.SH NOTES +.IX Header "NOTES" +At some point the EVP layer will begin enforcing the transitions described +herein. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBEVP_DigestInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/life_cycle-kdf.7 b/static/netbsd/man7/life_cycle-kdf.7 new file mode 100644 index 00000000..5e21da6f --- /dev/null +++ b/static/netbsd/man7/life_cycle-kdf.7 @@ -0,0 +1,146 @@ +.\" $NetBSD: life_cycle-kdf.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "LIFE_CYCLE-KDF 7" +.TH LIFE_CYCLE-KDF 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +life_cycle\-kdf \- The KDF algorithm life\-cycle +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All key derivation functions (KDFs) and pseudo random functions (PRFs) +go through a number of stages in their life\-cycle: +.IP start 4 +.IX Item "start" +This state represents the KDF/PRF before it has been allocated. It is the +starting state for any life\-cycle transitions. +.IP newed 4 +.IX Item "newed" +This state represents the KDF/PRF after it has been allocated. +.IP deriving 4 +.IX Item "deriving" +This state represents the KDF/PRF when it is set up and capable of generating +output. +.IP freed 4 +.IX Item "freed" +This state is entered when the KDF/PRF is freed. It is the terminal state +for all life\-cycle transitions. +.SS "State Transition Diagram" +.IX Subsection "State Transition Diagram" +The usual life\-cycle of a KDF/PRF is illustrated: + +-------------------+ + | start | + +-------------------+ + | + | EVP_KDF_CTX_new + v + +-------------------+ + | newed | <+ + +-------------------+ | + | | + | EVP_KDF_derive | + v | EVP_KDF_CTX_reset + EVP_KDF_derive +-------------------+ | + + - - - - - - - - | | | + \*(Aq | deriving | | + + - - - - - - - -> | | -+ + +-------------------+ + | + | EVP_KDF_CTX_free + v + +-------------------+ + | freed | + +-------------------+ +.SS "Formal State Transitions" +.IX Subsection "Formal State Transitions" +This section defines all of the legal state transitions. +This is the canonical list. + Function Call ------------- Current State ------------- + start newed deriving freed + EVP_KDF_CTX_new newed + EVP_KDF_derive deriving deriving + EVP_KDF_CTX_free freed freed freed + EVP_KDF_CTX_reset newed newed + EVP_KDF_CTX_get_params newed deriving + EVP_KDF_CTX_set_params newed deriving + EVP_KDF_CTX_gettable_params newed deriving + EVP_KDF_CTX_settable_params newed deriving +.SH NOTES +.IX Header "NOTES" +At some point the EVP layer will begin enforcing the transitions described +herein. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-kdf\fR\|(7), \fBEVP_KDF\fR\|(3). +.SH HISTORY +.IX Header "HISTORY" +The provider KDF interface was introduced in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/life_cycle-mac.7 b/static/netbsd/man7/life_cycle-mac.7 new file mode 100644 index 00000000..4c9e42a6 --- /dev/null +++ b/static/netbsd/man7/life_cycle-mac.7 @@ -0,0 +1,165 @@ +.\" $NetBSD: life_cycle-mac.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "LIFE_CYCLE-MAC 7" +.TH LIFE_CYCLE-MAC 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +life_cycle\-mac \- The MAC algorithm life\-cycle +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All message authentication codes (MACs) +go through a number of stages in their life\-cycle: +.IP start 4 +.IX Item "start" +This state represents the MAC before it has been allocated. It is the +starting state for any life\-cycle transitions. +.IP newed 4 +.IX Item "newed" +This state represents the MAC after it has been allocated. +.IP initialised 4 +.IX Item "initialised" +This state represents the MAC when it is set up and capable of processing +input. +.IP updated 4 +.IX Item "updated" +This state represents the MAC when it is set up and capable of processing +additional input or generating output. +.IP finaled 4 +.IX Item "finaled" +This state represents the MAC when it has generated output. +.IP freed 4 +.IX Item "freed" +This state is entered when the MAC is freed. It is the terminal state +for all life\-cycle transitions. +.SS "State Transition Diagram" +.IX Subsection "State Transition Diagram" +The usual life\-cycle of a MAC is illustrated: + +-------------------+ + | start | + +-------------------+ + | + | EVP_MAC_CTX_new + v + +-------------------+ + | newed | + +-------------------+ + | + | EVP_MAC_init + v + +-------------------+ + +> | initialised | <+ + | +-------------------+ | + | | | + | | EVP_MAC_update | EVP_MAC_init + | v | + EVP_MAC_init | +-------------------+ | + | | updated | -+ + | +-------------------+ + | | | + | | EVP_MAC_final | EVP_MAC_finalXOF + | v v + | +-------------------+ + +- | finaled | + +-------------------+ + | + | EVP_MAC_CTX_free + v + +-------------------+ + | freed | + +-------------------+ +.SS "Formal State Transitions" +.IX Subsection "Formal State Transitions" +This section defines all of the legal state transitions. +This is the canonical list. + Function Call --------------------- Current State ---------------------- + start newed initialised updated finaled freed + EVP_MAC_CTX_new newed + EVP_MAC_init initialised initialised initialised initialised + EVP_MAC_update updated updated + EVP_MAC_final finaled + EVP_MAC_finalXOF finaled + EVP_MAC_CTX_free freed freed freed freed freed + EVP_MAC_CTX_get_params newed initialised updated + EVP_MAC_CTX_set_params newed initialised updated + EVP_MAC_CTX_gettable_params newed initialised updated + EVP_MAC_CTX_settable_params newed initialised updated +.SH NOTES +.IX Header "NOTES" +At some point the EVP layer will begin enforcing the transitions described +herein. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-mac\fR\|(7), \fBEVP_MAC\fR\|(3). +.SH HISTORY +.IX Header "HISTORY" +The provider MAC interface was introduced in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/life_cycle-pkey.7 b/static/netbsd/man7/life_cycle-pkey.7 new file mode 100644 index 00000000..0e5ab7d3 --- /dev/null +++ b/static/netbsd/man7/life_cycle-pkey.7 @@ -0,0 +1,249 @@ +.\" $NetBSD: life_cycle-pkey.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "LIFE_CYCLE-PKEY 7" +.TH LIFE_CYCLE-PKEY 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +life_cycle\-pkey \- The PKEY algorithm life\-cycle +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All public keys (PKEYs) go through a number of stages in their life\-cycle: +.IP start 4 +.IX Item "start" +This state represents the PKEY before it has been allocated. It is the +starting state for any life\-cycle transitions. +.IP newed 4 +.IX Item "newed" +This state represents the PKEY after it has been allocated. +.IP decapsulate 4 +.IX Item "decapsulate" +This state represents the PKEY when it is ready to perform a private key decapsulation +operation. +.IP decrypt 4 +.IX Item "decrypt" +This state represents the PKEY when it is ready to decrypt some ciphertext. +.IP derive 4 +.IX Item "derive" +This state represents the PKEY when it is ready to derive a shared secret. +.IP "digest sign" 4 +.IX Item "digest sign" +This state represents the PKEY when it is ready to perform a private key signature +operation. +.IP encapsulate 4 +.IX Item "encapsulate" +This state represents the PKEY when it is ready to perform a public key encapsulation +operation. +.IP encrypt 4 +.IX Item "encrypt" +This state represents the PKEY when it is ready to encrypt some plaintext. +.IP "key generation" 4 +.IX Item "key generation" +This state represents the PKEY when it is ready to generate a new public/private key. +.IP "parameter generation" 4 +.IX Item "parameter generation" +This state represents the PKEY when it is ready to generate key parameters. +.IP verify 4 +.IX Item "verify" +This state represents the PKEY when it is ready to verify a public key signature. +.IP "verify recover" 4 +.IX Item "verify recover" +This state represents the PKEY when it is ready to recover a public key signature data. +.IP freed 4 +.IX Item "freed" +This state is entered when the PKEY is freed. It is the terminal state +for all life\-cycle transitions. +.SS "State Transition Diagram" +.IX Subsection "State Transition Diagram" +The usual life\-cycle of a PKEY object is illustrated: + +-------------+ + | | + | start | + | | + EVP_PKEY_derive +-------------+ + +-------------+ EVP_PKEY_derive_set_peer | +-------------+ + | |----------------------------+ | +----------------------------| | + | derive | | | | EVP_PKEY_verify | verify | + | |<---------------------------+ | +--------------------------->| | + +-------------+ | +-------------+ + ^ | ^ + | EVP_PKEY_derive_init | EVP_PKEY_verify_init | + +---------------------------------------+ | +---------------------------------------+ + | | | + +-------------+ | | | +-------------+ + | |----------------------------+ | | | +----------------------------| | + | digest sign | EVP_PKEY_sign | | | | | EVP_PKEY_verify_recover | verify | + | |<---------------------------+ | | | +--------------------------->| recover | + +-------------+ | | | +-------------+ + ^ | | | ^ + | EVP_PKEY_sign_init | | | EVP_PKEY_verify_recover_init | + +---------------------------------+ | | | +---------------------------------+ + | | | | | + +-------------+ | | | | | +-------------+ + | |----------------------------+ | | | | | +----------------------------| | + | decapsulate | EVP_PKEY_decapsulate | | | | | | | EVP_PKEY_decrypt | decrypt | + | |<---------------------------+ | | v | | +--------------------------->| | + +-------------+ | +-------------+ | +-------------+ + ^ +---| |---+ ^ + | EVP_PKEY_decapsulate_init | | EVP_PKEY_decrypt_init | + +-------------------------------------| newed |-------------------------------------+ + | | + +---| |---+ + +-------------+ | +-------------+ | +-------------+ + | |----------------------------+ | | | | +----------------------------| | + | encapsulate | EVP_PKEY_encapsulate | | | | | | EVP_PKEY_encrypt | encrypt | + | |<---------------------------+ | | | | +--------------------------->| | + +-------------+ | | | | +-------------+ + ^ | | | | ^ + | EVP_PKEY_encapsulate_init | | | | EVP_PKEY_encrypt_init | + +---------------------------------+ | | +---------------------------------+ + | | + +---------------------------------------+ +---------------------------------------+ + | EVP_PKEY_paramgen_init EVP_PKEY_keygen_init | + v v + +-------------+ +-------------+ + | |----------------------------+ +----------------------------| | + | parameter | | | | key | + | generation |<---------------------------+ +--------------------------->| generation | + +-------------+ EVP_PKEY_paramgen EVP_PKEY_keygen +-------------+ + EVP_PKEY_gen EVP_PKEY_gen + + + + - - - - - + +-----------+ + \*(Aq \*(Aq EVP_PKEY_CTX_free | | + \*(Aq any state \*(Aq------------------->| freed | + \*(Aq \*(Aq | | + + - - - - - + +-----------+ +.SS "Formal State Transitions" +.IX Subsection "Formal State Transitions" +This section defines all of the legal state transitions. +This is the canonical list. + Function Call ---------------------------------------------------------------------- Current State ---------------------------------------------------------------------- + start newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key freed + sign recover generation generation + EVP_PKEY_CTX_new newed + EVP_PKEY_CTX_new_id newed + EVP_PKEY_CTX_new_from_name newed + EVP_PKEY_CTX_new_from_pkey newed + EVP_PKEY_sign_init digest digest digest digest digest digest digest digest digest digest digest + sign sign sign sign sign sign sign sign sign sign sign + EVP_PKEY_sign digest + sign + EVP_PKEY_verify_init verify verify verify verify verify verify verify verify verify verify verify + EVP_PKEY_verify verify + EVP_PKEY_verify_recover_init verify verify verify verify verify verify verify verify verify verify verify + recover recover recover recover recover recover recover recover recover recover recover + EVP_PKEY_verify_recover verify + recover + EVP_PKEY_encrypt_init encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt + EVP_PKEY_encrypt encrypt + EVP_PKEY_decrypt_init decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt + EVP_PKEY_decrypt decrypt + EVP_PKEY_derive_init derive derive derive derive derive derive derive derive derive derive derive + EVP_PKEY_derive_set_peer derive + EVP_PKEY_derive derive + EVP_PKEY_encapsulate_init encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate + EVP_PKEY_encapsulate encapsulate + EVP_PKEY_decapsulate_init decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate + EVP_PKEY_decapsulate decapsulate + EVP_PKEY_paramgen_init parameter parameter parameter parameter parameter parameter parameter parameter parameter parameter parameter + generation generation generation generation generation generation generation generation generation generation generation + EVP_PKEY_paramgen parameter + generation + EVP_PKEY_keygen_init key key key key key key key key key key key + generation generation generation generation generation generation generation generation generation generation generation + EVP_PKEY_keygen key + generation + EVP_PKEY_gen parameter key + generation generation + EVP_PKEY_CTX_get_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key + sign recover generation generation + EVP_PKEY_CTX_set_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key + sign recover generation generation + EVP_PKEY_CTX_gettable_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key + sign recover generation generation + EVP_PKEY_CTX_settable_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key + sign recover generation generation + EVP_PKEY_CTX_free freed freed freed freed freed freed freed freed freed freed freed freed +.SH NOTES +.IX Header "NOTES" +At some point the EVP layer will begin enforcing the transitions described +herein. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_new\fR\|(3), +\&\fBEVP_PKEY_decapsulate\fR\|(3), \fBEVP_PKEY_decrypt\fR\|(3), \fBEVP_PKEY_encapsulate\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), \fBEVP_PKEY_derive\fR\|(3), \fBEVP_PKEY_keygen\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify\fR\|(3), \fBEVP_PKEY_verify_recover\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The provider PKEY interface was introduced in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/life_cycle-rand.7 b/static/netbsd/man7/life_cycle-rand.7 new file mode 100644 index 00000000..ae6bb168 --- /dev/null +++ b/static/netbsd/man7/life_cycle-rand.7 @@ -0,0 +1,158 @@ +.\" $NetBSD: life_cycle-rand.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "LIFE_CYCLE-RAND 7" +.TH LIFE_CYCLE-RAND 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +life_cycle\-rand \- The RAND algorithm life\-cycle +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All random number generator (RANDs) +go through a number of stages in their life\-cycle: +.IP start 4 +.IX Item "start" +This state represents the RAND before it has been allocated. It is the +starting state for any life\-cycle transitions. +.IP newed 4 +.IX Item "newed" +This state represents the RAND after it has been allocated but unable to +generate any output. +.IP instantiated 4 +.IX Item "instantiated" +This state represents the RAND when it is set up and capable of generating +output. +.IP uninstantiated 4 +.IX Item "uninstantiated" +This state represents the RAND when it has been shutdown and it is no longer +capable of generating output. +.IP freed 4 +.IX Item "freed" +This state is entered when the RAND is freed. It is the terminal state +for all life\-cycle transitions. +.SS "State Transition Diagram" +.IX Subsection "State Transition Diagram" +The usual life\-cycle of a RAND is illustrated: + +-------------------------+ + | start | + +-------------------------+ + | + | EVP_RAND_CTX_new + v + +-------------------------+ + | newed | + +-------------------------+ + | + | EVP_RAND_instantiate + v + EVP_RAND_generate +-------------------------+ + +-------------------- | | + | | instantiated | + +-------------------> | | <+ + +-------------------------+ \*(Aq + | \*(Aq + | EVP_RAND_uninstantiate \*(Aq EVP_RAND_instantiate + v \*(Aq + +-------------------------+ \*(Aq + | uninstantiated | -+ + +-------------------------+ + | + | EVP_RAND_CTX_free + v + +-------------------------+ + | freed | + +-------------------------+ +.SS "Formal State Transitions" +.IX Subsection "Formal State Transitions" +This section defines all of the legal state transitions. +This is the canonical list. + Function Call ------------------ Current State ------------------ + start newed instantiated uninstantiated freed + EVP_RAND_CTX_new newed + EVP_RAND_instantiate instantiated + EVP_RAND_generate instantiated + EVP_RAND_uninstantiate uninstantiated + EVP_RAND_CTX_free freed freed freed freed + EVP_RAND_CTX_get_params newed instantiated uninstantiated freed + EVP_RAND_CTX_set_params newed instantiated uninstantiated freed + EVP_RAND_CTX_gettable_params newed instantiated uninstantiated freed + EVP_RAND_CTX_settable_params newed instantiated uninstantiated freed +.SH NOTES +.IX Header "NOTES" +At some point the EVP layer will begin enforcing the transitions described +herein. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-rand\fR\|(7), \fBEVP_RAND\fR\|(3). +.SH HISTORY +.IX Header "HISTORY" +The provider RAND interface was introduced in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/man.7 b/static/netbsd/man7/man.7 new file mode 100644 index 00000000..fca6937b --- /dev/null +++ b/static/netbsd/man7/man.7 @@ -0,0 +1,643 @@ +.\" Id: man.7,v 1.148 2021/08/05 14:31:14 schwarze Exp +.\" +.\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons +.\" Copyright (c) 2011-2015, 2017-2020 Ingo Schwarze +.\" Copyright (c) 2017 Anthony Bentley +.\" Copyright (c) 2010 Joerg Sonnenberger +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd August 5, 2021 +.Dt MAN 7 +.Os +.Sh NAME +.Nm man +.Nd legacy formatting language for manual pages +.Sh DESCRIPTION +The +.Nm man +language was the standard formatting language for +.At +manual pages from 1979 to 1989. +Do not use it to write new manual pages: it is a purely presentational +language and lacks support for semantic markup. +Use the +.Xr mdoc 7 +language, instead. +.Pp +In a +.Nm +document, lines beginning with the control character +.Sq \&. +are called +.Dq macro lines . +The first word is the macro name. +It usually consists of two capital letters. +For a list of portable macros, see +.Sx MACRO OVERVIEW . +The words following the macro name are arguments to the macro. +.Pp +Lines not beginning with the control character are called +.Dq text lines . +They provide free-form text to be printed; the formatting of the text +depends on the respective processing context: +.Bd -literal -offset indent +\&.SH Macro lines change control state. +Text lines are interpreted within the current state. +.Ed +.Pp +Many aspects of the basic syntax of the +.Nm +language are based on the +.Xr roff 7 +language; see the +.Em LANGUAGE SYNTAX +and +.Em MACRO SYNTAX +sections in the +.Xr roff 7 +manual for details, in particular regarding +comments, escape sequences, whitespace, and quoting. +.Pp +Each +.Nm +document starts with the +.Ic TH +macro specifying the document's name and section, followed by the +.Sx NAME +section formatted as follows: +.Bd -literal -offset indent +\&.TH PROGNAME 1 1979-01-10 +\&.SH NAME +\efBprogname\efR \e(en one line about what it does +.Ed +.Sh MACRO OVERVIEW +This overview is sorted such that macros of similar purpose are listed +together. +Deprecated and non-portable macros are not included in the overview, +but can be found in the alphabetical reference below. +.Ss Page header and footer meta-data +.Bl -column "RS, RE" description +.It Ic TH Ta set the title: Ar name section date Op Ar source Op Ar volume +.It Ic AT Ta display AT&T UNIX version in the page footer (<= 1 argument) +.It Ic UC Ta display BSD version in the page footer (<= 1 argument) +.El +.Ss Sections and paragraphs +.Bl -column "RS, RE" description +.It Ic SH Ta section header (one line) +.It Ic SS Ta subsection header (one line) +.It Ic PP Ta start an undecorated paragraph (no arguments) +.It Ic RS , RE Ta reset the left margin: Op Ar width +.It Ic IP Ta indented paragraph: Op Ar head Op Ar width +.It Ic TP Ta tagged paragraph: Op Ar width +.It Ic PD Ta set vertical paragraph distance: Op Ar height +.It Ic in Ta additional indent: Op Ar width +.El +.Ss Physical markup +.Bl -column "RS, RE" description +.It Ic B Ta boldface font +.It Ic I Ta italic font +.It Ic SB Ta small boldface font +.It Ic SM Ta small roman font +.It Ic BI Ta alternate between boldface and italic fonts +.It Ic BR Ta alternate between boldface and roman fonts +.It Ic IB Ta alternate between italic and boldface fonts +.It Ic IR Ta alternate between italic and roman fonts +.It Ic RB Ta alternate between roman and boldface fonts +.It Ic RI Ta alternate between roman and italic fonts +.El +.Sh MACRO REFERENCE +This section is a canonical reference to all macros, arranged +alphabetically. +For the scoping of individual macros, see +.Sx MACRO SYNTAX . +.Bl -tag -width 3n +.It Ic AT +Sets the volume for the footer for compatibility with man pages from +.At +releases. +The optional arguments specify which release it is from. +This macro is an extension that first appeared in +.Bx 4.3 . +.It Ic B +Text is rendered in bold face. +.It Ic BI +Text is rendered alternately in bold face and italic. +Thus, +.Sq .BI this word and that +causes +.Sq this +and +.Sq and +to render in bold face, while +.Sq word +and +.Sq that +render in italics. +Whitespace between arguments is omitted in output. +.Pp +Example: +.Pp +.Dl \&.BI bold italic bold italic +.It Ic BR +Text is rendered alternately in bold face and roman (the default font). +Whitespace between arguments is omitted in output. +See also +.Ic BI . +.It Ic DT +Restore the default tabulator positions. +They are at intervals of 0.5 inches. +This has no effect unless the tabulator positions were changed with the +.Xr roff 7 +.Ic ta +request. +.It Ic EE +This is a non-standard Version 9 +.At +extension later adopted by GNU. +In +.Xr mandoc 1 , +it does the same as the +.Xr roff 7 +.Ic fi +request (switch to fill mode). +.It Ic EX +This is a non-standard Version 9 +.At +extension later adopted by GNU. +In +.Xr mandoc 1 , +it does the same as the +.Xr roff 7 +.Ic nf +request (switch to no-fill mode). +.It Ic HP +Begin a paragraph whose initial output line is left-justified, but +subsequent output lines are indented, with the following syntax: +.Pp +.D1 Pf . Ic HP Op Ar width +.Pp +The +.Ar width +argument is a +.Xr roff 7 +scaling width. +If specified, it's saved for later paragraph left margins; +if unspecified, the saved or default width is used. +.Pp +This macro is portable, but deprecated +because it has no good representation in HTML output, +usually ending up indistinguishable from +.Ic PP . +.It Ic I +Text is rendered in italics. +.It Ic IB +Text is rendered alternately in italics and bold face. +Whitespace between arguments is omitted in output. +See also +.Ic BI . +.It Ic IP +Begin an indented paragraph with the following syntax: +.Pp +.D1 Pf . Ic IP Op Ar head Op Ar width +.Pp +The +.Ar width +argument is a +.Xr roff 7 +scaling width defining the left margin. +It's saved for later paragraph left-margins; if unspecified, the saved or +default width is used. +.Pp +The +.Ar head +argument is used as a leading term, flushed to the left margin. +This is useful for bulleted paragraphs and so on. +.It Ic IR +Text is rendered alternately in italics and roman (the default font). +Whitespace between arguments is omitted in output. +See also +.Ic BI . +.It Ic LP +A synonym for +.Ic PP . +.It Ic ME +End a mailto block started with +.Ic MT . +This is a non-standard GNU extension. +.It Ic MT +Begin a mailto block. +This is a non-standard GNU extension. +It has the following syntax: +.Bd -unfilled -offset indent +.Pf . Ic MT Ar address +link description to be shown +.Pf . Ic ME +.Ed +.It Ic OP +Optional command-line argument. +This is a non-standard DWB extension. +It has the following syntax: +.Pp +.D1 Pf . Ic OP Ar key Op Ar value +.Pp +The +.Ar key +is usually a command-line flag and +.Ar value +its argument. +.It Ic P +This synonym for +.Ic PP +is an +.At III +extension later adopted by +.Bx 4.3 . +.It Ic PD +Specify the vertical space to be inserted before each new paragraph. +.br +The syntax is as follows: +.Pp +.D1 Pf . Ic PD Op Ar height +.Pp +The +.Ar height +argument is a +.Xr roff 7 +scaling width. +It defaults to +.Cm 1v . +If the unit is omitted, +.Cm v +is assumed. +.Pp +This macro affects the spacing before any subsequent instances of +.Ic HP , +.Ic IP , +.Ic LP , +.Ic P , +.Ic PP , +.Ic SH , +.Ic SS , +.Ic SY , +and +.Ic TP . +.It Ic PP +Begin an undecorated paragraph. +The scope of a paragraph is closed by a subsequent paragraph, +sub-section, section, or end of file. +The saved paragraph left-margin width is reset to the default. +.It Ic RB +Text is rendered alternately in roman (the default font) and bold face. +Whitespace between arguments is omitted in output. +See also +.Ic BI . +.It Ic RE +Explicitly close out the scope of a prior +.Ic RS . +The default left margin is restored to the state before that +.Ic RS +invocation. +.Pp +The syntax is as follows: +.Pp +.D1 Pf . Ic RE Op Ar level +.Pp +Without an argument, the most recent +.Ic RS +block is closed out. +If +.Ar level +is 1, all open +.Ic RS +blocks are closed out. +Otherwise, +.Ar level No \(mi 1 +nested +.Ic RS +blocks remain open. +.It Ic RI +Text is rendered alternately in roman (the default font) and italics. +Whitespace between arguments is omitted in output. +See also +.Ic BI . +.It Ic RS +Temporarily reset the default left margin. +This has the following syntax: +.Pp +.D1 Pf . Ic RS Op Ar width +.Pp +The +.Ar width +argument is a +.Xr roff 7 +scaling width. +If not specified, the saved or default width is used. +.Pp +See also +.Ic RE . +.It Ic SB +Text is rendered in small size (one point smaller than the default font) +bold face. +This macro is an extension that probably first appeared in SunOS 4.0 +and was later adopted by GNU and by +.Bx 4.4 . +.It Ic SH +Begin a section. +The scope of a section is only closed by another section or the end of +file. +The paragraph left-margin width is reset to the default. +.It Ic SM +Text is rendered in small size (one point smaller than the default +font). +.It Ic SS +Begin a sub-section. +The scope of a sub-section is closed by a subsequent sub-section, +section, or end of file. +The paragraph left-margin width is reset to the default. +.It Ic SY +Begin a synopsis block with the following syntax: +.Bd -unfilled -offset indent +.Pf . Ic SY Ar command +.Ar arguments +.Pf . Ic YS +.Ed +.Pp +This is a non-standard GNU extension +and very rarely used even in GNU manual pages. +Formatting is similar to +.Ic IP . +.It Ic TH +Set the name of the manual page for use in the page header +and footer with the following syntax: +.Pp +.D1 Pf . Ic TH Ar name section date Op Ar source Op Ar volume +.Pp +Conventionally, the document +.Ar name +is given in all caps. +The +.Ar section +is usually a single digit, in a few cases followed by a letter. +The recommended +.Ar date +format is +.Sy YYYY-MM-DD +as specified in the ISO-8601 standard; +if the argument does not conform, it is printed verbatim. +If the +.Ar date +is empty or not specified, the current date is used. +The optional +.Ar source +string specifies the organisation providing the utility. +When unspecified, +.Xr mandoc 1 +uses its +.Fl Ios +argument. +The +.Ar volume +string replaces the default volume title of the +.Ar section . +.Pp +Examples: +.Pp +.Dl \&.TH CVS 5 "1992-02-12" GNU +.It Ic TP +Begin a paragraph where the head, if exceeding the indentation width, is +followed by a newline; if not, the body follows on the same line after +advancing to the indentation width. +Subsequent output lines are indented. +The syntax is as follows: +.Bd -unfilled -offset indent +.Pf . Ic TP Op Ar width +.Ar head No \e" one line +.Ar body +.Ed +.Pp +The +.Ar width +argument is a +.Xr roff 7 +scaling width. +If specified, it's saved for later paragraph left-margins; if +unspecified, the saved or default width is used. +.It Ic TQ +Like +.Ic TP , +except that no vertical spacing is inserted before the paragraph. +This is a non-standard GNU extension +and very rarely used even in GNU manual pages. +.It Ic UC +Sets the volume for the footer for compatibility with man pages from +.Bx +releases. +The optional first argument specifies which release it is from. +This macro is an extension that first appeared in +.Bx 3 . +.It Ic UE +End a uniform resource identifier block started with +.Ic UR . +This is a non-standard GNU extension. +.It Ic UR +Begin a uniform resource identifier block. +This is a non-standard GNU extension. +It has the following syntax: +.Bd -unfilled -offset indent +.Pf . Ic UR Ar uri +link description to be shown +.Pf . Ic UE +.Ed +.It Ic YS +End a synopsis block started with +.Ic SY . +This is a non-standard GNU extension. +.It Ic in +Indent relative to the current indentation: +.Pp +.D1 Pf . Ic in Op Ar width +.Pp +If +.Ar width +is signed, the new offset is relative. +Otherwise, it is absolute. +This value is reset upon the next paragraph, section, or sub-section. +.El +.Sh MACRO SYNTAX +The +.Nm +macros are classified by scope: line scope or block scope. +Line macros are only scoped to the current line (and, in some +situations, the subsequent line). +Block macros are scoped to the current line and subsequent lines until +closed by another block macro. +.Ss Line Macros +Line macros are generally scoped to the current line, with the body +consisting of zero or more arguments. +If a macro is scoped to the next line and the line arguments are empty, +the next line, which must be text, is used instead. +Thus: +.Bd -literal -offset indent +\&.I +foo +.Ed +.Pp +is equivalent to +.Sq .I foo . +If next-line macros are invoked consecutively, only the last is used. +If a next-line macro is followed by a non-next-line macro, an error is +raised. +.Pp +The syntax is as follows: +.Bd -literal -offset indent +\&.YO \(lBbody...\(rB +\(lBbody...\(rB +.Ed +.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent +.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes +.It Ic AT Ta <=1 Ta current Ta \& +.It Ic B Ta n Ta next-line Ta \& +.It Ic BI Ta n Ta current Ta \& +.It Ic BR Ta n Ta current Ta \& +.It Ic DT Ta 0 Ta current Ta \& +.It Ic EE Ta 0 Ta current Ta Version 9 At +.It Ic EX Ta 0 Ta current Ta Version 9 At +.It Ic I Ta n Ta next-line Ta \& +.It Ic IB Ta n Ta current Ta \& +.It Ic IR Ta n Ta current Ta \& +.It Ic OP Ta >=1 Ta current Ta DWB +.It Ic PD Ta 1 Ta current Ta \& +.It Ic RB Ta n Ta current Ta \& +.It Ic RI Ta n Ta current Ta \& +.It Ic SB Ta n Ta next-line Ta \& +.It Ic SM Ta n Ta next-line Ta \& +.It Ic TH Ta >1, <6 Ta current Ta \& +.It Ic UC Ta <=1 Ta current Ta \& +.It Ic in Ta 1 Ta current Ta Xr roff 7 +.El +.Ss Block Macros +Block macros comprise a head and body. +As with in-line macros, the head is scoped to the current line and, in +one circumstance, the next line (the next-line stipulations as in +.Sx Line Macros +apply here as well). +.Pp +The syntax is as follows: +.Bd -literal -offset indent +\&.YO \(lBhead...\(rB +\(lBhead...\(rB +\(lBbody...\(rB +.Ed +.Pp +The closure of body scope may be to the section, where a macro is closed +by +.Ic SH ; +sub-section, closed by a section or +.Ic SS ; +or paragraph, closed by a section, sub-section, +.Ic HP , +.Ic IP , +.Ic LP , +.Ic P , +.Ic PP , +.Ic RE , +.Ic SY , +or +.Ic TP . +No closure refers to an explicit block closing macro. +.Pp +As a rule, block macros may not be nested; thus, calling a block macro +while another block macro scope is open, and the open scope is not +implicitly closed, is syntactically incorrect. +.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent +.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes +.It Ic HP Ta <2 Ta current Ta paragraph Ta \& +.It Ic IP Ta <3 Ta current Ta paragraph Ta \& +.It Ic LP Ta 0 Ta current Ta paragraph Ta \& +.It Ic ME Ta 0 Ta none Ta none Ta GNU +.It Ic MT Ta 1 Ta current Ta to \&ME Ta GNU +.It Ic P Ta 0 Ta current Ta paragraph Ta \& +.It Ic PP Ta 0 Ta current Ta paragraph Ta \& +.It Ic RE Ta <=1 Ta current Ta none Ta \& +.It Ic RS Ta 1 Ta current Ta to \&RE Ta \& +.It Ic SH Ta >0 Ta next-line Ta section Ta \& +.It Ic SS Ta >0 Ta next-line Ta sub-section Ta \& +.It Ic SY Ta 1 Ta current Ta to \&YS Ta GNU +.It Ic TP Ta n Ta next-line Ta paragraph Ta \& +.It Ic TQ Ta n Ta next-line Ta paragraph Ta GNU +.It Ic UE Ta 0 Ta current Ta none Ta GNU +.It Ic UR Ta 1 Ta current Ta part Ta GNU +.It Ic YS Ta 0 Ta none Ta none Ta GNU +.El +.Pp +If a block macro is next-line scoped, it may only be followed by in-line +macros for decorating text. +.Ss Font handling +In +.Nm +documents, both +.Sx Physical markup +macros and +.Xr roff 7 +.Ql \ef +font escape sequences can be used to choose fonts. +In text lines, the effect of manual font selection by escape sequences +only lasts until the next macro invocation; in macro lines, it only lasts +until the end of the macro scope. +Note that macros like +.Ic BR +open and close a font scope for each argument. +.Sh SEE ALSO +.Xr man 1 , +.Xr mandoc 1 , +.Xr eqn 7 , +.Xr mandoc_char 7 , +.Xr mdoc 7 , +.Xr roff 7 , +.Xr tbl 7 +.Sh HISTORY +The +.Nm +language first appeared as a macro package for the roff typesetting +system in +.At v7 . +.Pp +The stand-alone implementation that is part of the +.Xr mandoc 1 +utility first appeared in +.Ox 4.6 . +.Sh AUTHORS +.An -nosplit +.An Douglas McIlroy Aq Mt m.douglas.mcilroy@dartmouth.edu +designed and implemented the original version of these macros, +wrote the original version of this manual page, +and was the first to use them when he edited volume 1 of the +.At v7 +manual pages. +.Pp +.An James Clark +later rewrote the macros for groff. +.An Eric S. Raymond Aq Mt esr@thyrsus.com +and +.An Werner Lemberg Aq Mt wl@gnu.org +added the extended +.Nm +macros to groff in 2007. +.Pp +The +.Xr mandoc 1 +program and this +.Nm +reference were written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . diff --git a/static/netbsd/man7/mandoc_char.7 b/static/netbsd/man7/mandoc_char.7 new file mode 100644 index 00000000..4ca508a8 --- /dev/null +++ b/static/netbsd/man7/mandoc_char.7 @@ -0,0 +1,829 @@ +.\" Id: mandoc_char.7,v 1.78 2020/10/31 11:45:16 schwarze Exp +.\" +.\" Copyright (c) 2003 Jason McIntyre +.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons +.\" Copyright (c) 2011,2013,2015,2017-2020 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd October 31, 2020 +.Dt MANDOC_CHAR 7 +.Os +.Sh NAME +.Nm mandoc_char +.Nd mandoc special characters +.Sh DESCRIPTION +This page documents the +.Xr roff 7 +escape sequences accepted by +.Xr mandoc 1 +to represent special characters in +.Xr mdoc 7 +and +.Xr man 7 +documents. +.Pp +The rendering depends on the +.Xr mandoc 1 +output mode; it can be inspected by calling +.Xr man 1 +on the +.Nm +manual page with different +.Fl T +arguments. +In ASCII output, the rendering of some characters may be hard +to interpret for the reader. +Many are rendered as descriptive strings like +.Qq , +.Qq , +or +.Qq , +which may look ugly, and many are replaced by similar ASCII characters. +In particular, accented characters are usually shown without the accent. +For that reason, try to avoid using any of the special characters +documented here except those discussed in the +.Sx DESCRIPTION , +unless they are essential for explaining the subject matter at hand, +for example when documenting complicated mathematical functions. +.Pp +In particular, in English manual pages, do not use special-character +escape sequences to represent national language characters in author +names; instead, provide ASCII transcriptions of the names. +.Ss Dashes and Hyphens +In typography there are different types of dashes of various width: +the hyphen (\(hy), +the en-dash (\(en), +the em-dash (\(em), +and the mathematical minus sign (\(mi). +.Pp +Hyphens are used for adjectives; +to separate the two parts of a compound word; +or to separate a word across two successive lines of text. +The hyphen does not need to be escaped: +.Bd -unfilled -offset indent +blue-eyed +lorry-driver +.Ed +.Pp +The en-dash is used to separate the two elements of a range, +or can be used the same way as an em-dash. +It should be written as +.Sq \e(en : +.Bd -unfilled -offset indent +pp. 95\e(en97. +Go away \e(en or else! +.Ed +.Pp +The em-dash can be used to show an interruption +or can be used the same way as colons, semi-colons, or parentheses. +It should be written as +.Sq \e(em : +.Bd -unfilled -offset indent +Three things \e(em apples, oranges, and bananas. +This is not that \e(em rather, this is that. +.Ed +.Pp +In +.Xr roff 7 +documents, the minus sign is normally written as +.Sq \e- . +In manual pages, some style guides recommend to also use +.Sq \e- +if an ASCII 0x2d +.Dq hyphen-minus +output glyph that can be copied and pasted is desired in output modes +supporting it, for example in +.Fl T Cm utf8 +and +.Fl T Cm html . +But currently, no practically relevant manual page formatter requires +that subtlety, so in manual pages, it is sufficient to write plain +.Sq - +to represent hyphen, minus, and hyphen-minus. +.Pp +If a word on a text input line contains a hyphen, a formatter may decide +to insert an output line break after the hyphen if that helps filling +the current output line, but the whole word would overflow the line. +If it is important that the word is not broken across lines in this +way, a zero-width space +.Pq Sq \e& +can be inserted before or after the hyphen. +While +.Xr mandoc 1 +never breaks the output line after hyphens adjacent to a zero-width +space, after any of the other dash- or hyphen-like characters +represented by escape sequences, or after hyphens inside words in +macro arguments, other software may not respect these rules and may +break the line even in such cases. +.Pp +Some +.Xr roff 7 +implementations contains dictionaries allowing to break the line +at syllable boundaries even inside words that contain no hyphens. +Such automatic hyphenation is not supported by +.Xr mandoc 1 , +which only breaks the line at whitespace, and inside words only +after existing hyphens. +.Ss Spaces +To separate words in normal text, for indenting and alignment +in literal context, and when none of the following special cases apply, +just use the normal space character +.Pq Sq \ . +.Pp +When filling text, output lines may be broken between words, i.e. at space +characters. +To prevent a line break between two particular words, +use the unpaddable non-breaking space escape sequence +.Pq Sq \e\ \& +instead of the normal space character. +For example, the input string +.Dq number\e\ 1 +will be kept together as +.Dq number\ 1 +on the same output line. +.Pp +On request and macro lines, the normal space character serves as an +argument delimiter. +To include whitespace into arguments, quoting is usually the best choice; +see the MACRO SYNTAX section in +.Xr roff 7 . +In some cases, using the non-breaking space escape sequence +.Pq Sq \e\ \& +may be preferable. +.Pp +To escape macro names and to protect whitespace at the end +of input lines, the zero-width space +.Pq Sq \e& +is often useful. +For example, in +.Xr mdoc 7 , +a normal space character can be displayed in single quotes in either +of the following ways: +.Pp +.Dl .Sq \(dq \(dq +.Dl .Sq \e \e& +.Ss Quotes +On request and macro lines, the double-quote character +.Pq Sq \(dq +is handled specially to allow quoting. +One way to prevent this special handling is by using the +.Sq \e(dq +escape sequence. +.Pp +Note that on text lines, literal double-quote characters can be used +verbatim. +All other quote-like characters can be used verbatim as well, +even on request and macro lines. +.Ss Accents +In output modes supporting such special output characters, for example +.Fl T Cm pdf , +and sometimes less consistently in +.Fl T Cm utf8 , +some +.Xr roff 7 +formatters convert the following ASCII input characters to the +following Unicode special output characters: +.Bl -column x(ga U+2018 -offset indent +.It \(ga Ta U+2018 Ta left single quotation mark +.It \(aq Ta U+2019 Ta right single quotation mark +.It \(ti Ta U+02DC Ta small tilde +.It \(ha Ta U+02C6 Ta modifier letter circumflex +.El +.Pp +In prose, this automatic substitution is often desirable; +but when these characters have to be displayed as plain ASCII +characters, for example in source code samples, they require +escaping to render as follows: +.Bl -column x(ga U+2018 -offset indent +.It \e(ga Ta U+0060 Ta grave accent +.It \e(aq Ta U+0027 Ta apostrophe +.It \e(ti Ta U+007E Ta tilde +.It \e(ha Ta U+005E Ta circumflex accent +.El +.Ss Periods +The period +.Pq Sq \&. +is handled specially at the beginning of an input line, +where it introduces a +.Xr roff 7 +request or a macro, and when appearing alone as a macro argument in +.Xr mdoc 7 . +In such situations, prepend a zero-width space +.Pq Sq \e&. +to make it behave like normal text. +.Pp +Do not use the +.Sq \e. +escape sequence. +It does not prevent special handling of the period. +.Ss Backslashes +To include a literal backslash +.Pq Sq \e +into the output, use the +.Pq Sq \ee +escape sequence. +.Pp +Note that doubling it +.Pq Sq \e\e +is not the right way to output a backslash. +Because +.Xr mandoc 1 +does not implement full +.Xr roff 7 +functionality, it may work with +.Xr mandoc 1 , +but it may have weird effects on complete +.Xr roff 7 +implementations. +.Sh SPECIAL CHARACTERS +Special characters are encoded as +.Sq \eX +.Pq for a one-character escape , +.Sq \e(XX +.Pq two-character , +and +.Sq \e[N] +.Pq N-character . +For details, see the +.Em Special Characters +subsection of the +.Xr roff 7 +manual. +.Pp +Spaces, non-breaking unless stated otherwise: +.Bl -column "Input" "Description" -offset indent -compact +.It Em Input Ta Em Description +.It Sq \e\ \& Ta unpaddable space +.It \e\(ti Ta paddable space +.It \e0 Ta digit-width space +.It \e| Ta one-sixth \e(em narrow space, zero width in nroff mode +.It \e^ Ta one-twelfth \e(em half-narrow space, zero width in nroff +.It \e& Ta zero-width space +.It \e) Ta zero-width space transparent to end-of-sentence detection +.It \e% Ta zero-width space allowing hyphenation +.It \e: Ta zero-width space allowing line break +.El +.Pp +Lines: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(ba Ta \(ba Ta bar +.It \e(br Ta \(br Ta box rule +.It \e(ul Ta \(ul Ta underscore +.It \e(ru Ta \(ru Ta underscore (width 0.5m) +.It \e(rn Ta \(rn Ta overline +.It \e(bb Ta \(bb Ta broken bar +.It \e(sl Ta \(sl Ta forward slash +.It \e(rs Ta \(rs Ta backward slash +.El +.Pp +Text markers: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(ci Ta \(ci Ta circle +.It \e(bu Ta \(bu Ta bullet +.It \e(dd Ta \(dd Ta double dagger +.It \e(dg Ta \(dg Ta dagger +.It \e(lz Ta \(lz Ta lozenge +.It \e(sq Ta \(sq Ta white square +.It \e(ps Ta \(ps Ta paragraph +.It \e(sc Ta \(sc Ta section +.It \e(lh Ta \(lh Ta left hand +.It \e(rh Ta \(rh Ta right hand +.It \e(at Ta \(at Ta at +.It \e(sh Ta \(sh Ta hash (pound) +.It \e(CR Ta \(CR Ta carriage return +.It \e(OK Ta \(OK Ta check mark +.It \e(CL Ta \(CL Ta club suit +.It \e(SP Ta \(SP Ta spade suit +.It \e(HE Ta \(HE Ta heart suit +.It \e(DI Ta \(DI Ta diamond suit +.El +.Pp +Legal symbols: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(co Ta \(co Ta copyright +.It \e(rg Ta \(rg Ta registered +.It \e(tm Ta \(tm Ta trademarked +.El +.Pp +Punctuation: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(em Ta \(em Ta em-dash +.It \e(en Ta \(en Ta en-dash +.It \e(hy Ta \(hy Ta hyphen +.It \ee Ta \e Ta back-slash +.It \e. Ta \. Ta period +.It \e(r! Ta \(r! Ta upside-down exclamation +.It \e(r? Ta \(r? Ta upside-down question +.El +.Pp +Quotes: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(Bq Ta \(Bq Ta right low double-quote +.It \e(bq Ta \(bq Ta right low single-quote +.It \e(lq Ta \(lq Ta left double-quote +.It \e(rq Ta \(rq Ta right double-quote +.It \e(oq Ta \(oq Ta left single-quote +.It \e(cq Ta \(cq Ta right single-quote +.It \e(aq Ta \(aq Ta apostrophe quote (ASCII character) +.It \e(dq Ta \(dq Ta double quote (ASCII character) +.It \e(Fo Ta \(Fo Ta left guillemet +.It \e(Fc Ta \(Fc Ta right guillemet +.It \e(fo Ta \(fo Ta left single guillemet +.It \e(fc Ta \(fc Ta right single guillemet +.El +.Pp +Brackets: +.Bl -column "xxbracketrightbtx" Rendered Description -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(lB Ta \(lB Ta left bracket +.It \e(rB Ta \(rB Ta right bracket +.It \e(lC Ta \(lC Ta left brace +.It \e(rC Ta \(rC Ta right brace +.It \e(la Ta \(la Ta left angle +.It \e(ra Ta \(ra Ta right angle +.It \e(bv Ta \(bv Ta brace extension (special font) +.It \e[braceex] Ta \[braceex] Ta brace extension +.It \e[bracketlefttp] Ta \[bracketlefttp] Ta top-left hooked bracket +.It \e[bracketleftbt] Ta \[bracketleftbt] Ta bottom-left hooked bracket +.It \e[bracketleftex] Ta \[bracketleftex] Ta left hooked bracket extension +.It \e[bracketrighttp] Ta \[bracketrighttp] Ta top-right hooked bracket +.It \e[bracketrightbt] Ta \[bracketrightbt] Ta bottom-right hooked bracket +.It \e[bracketrightex] Ta \[bracketrightex] Ta right hooked bracket extension +.It \e(lt Ta \(lt Ta top-left hooked brace +.It \e[bracelefttp] Ta \[bracelefttp] Ta top-left hooked brace +.It \e(lk Ta \(lk Ta mid-left hooked brace +.It \e[braceleftmid] Ta \[braceleftmid] Ta mid-left hooked brace +.It \e(lb Ta \(lb Ta bottom-left hooked brace +.It \e[braceleftbt] Ta \[braceleftbt] Ta bottom-left hooked brace +.It \e[braceleftex] Ta \[braceleftex] Ta left hooked brace extension +.It \e(rt Ta \(rt Ta top-left hooked brace +.It \e[bracerighttp] Ta \[bracerighttp] Ta top-right hooked brace +.It \e(rk Ta \(rk Ta mid-right hooked brace +.It \e[bracerightmid] Ta \[bracerightmid] Ta mid-right hooked brace +.It \e(rb Ta \(rb Ta bottom-right hooked brace +.It \e[bracerightbt] Ta \[bracerightbt] Ta bottom-right hooked brace +.It \e[bracerightex] Ta \[bracerightex] Ta right hooked brace extension +.It \e[parenlefttp] Ta \[parenlefttp] Ta top-left hooked parenthesis +.It \e[parenleftbt] Ta \[parenleftbt] Ta bottom-left hooked parenthesis +.It \e[parenleftex] Ta \[parenleftex] Ta left hooked parenthesis extension +.It \e[parenrighttp] Ta \[parenrighttp] Ta top-right hooked parenthesis +.It \e[parenrightbt] Ta \[parenrightbt] Ta bottom-right hooked parenthesis +.It \e[parenrightex] Ta \[parenrightex] Ta right hooked parenthesis extension +.El +.Pp +Arrows: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(<- Ta \(<- Ta left arrow +.It \e(-> Ta \(-> Ta right arrow +.It \e(<> Ta \(<> Ta left-right arrow +.It \e(da Ta \(da Ta down arrow +.It \e(ua Ta \(ua Ta up arrow +.It \e(va Ta \(va Ta up-down arrow +.It \e(lA Ta \(lA Ta left double-arrow +.It \e(rA Ta \(rA Ta right double-arrow +.It \e(hA Ta \(hA Ta left-right double-arrow +.It \e(uA Ta \(uA Ta up double-arrow +.It \e(dA Ta \(dA Ta down double-arrow +.It \e(vA Ta \(vA Ta up-down double-arrow +.It \e(an Ta \(an Ta horizontal arrow extension +.El +.Pp +Logical: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(AN Ta \(AN Ta logical and +.It \e(OR Ta \(OR Ta logical or +.It \e[tno] Ta \[tno] Ta logical not (text font) +.It \e(no Ta \(no Ta logical not (special font) +.It \e(te Ta \(te Ta existential quantifier +.It \e(fa Ta \(fa Ta universal quantifier +.It \e(st Ta \(st Ta such that +.It \e(tf Ta \(tf Ta therefore +.It \e(3d Ta \(3d Ta therefore +.It \e(or Ta \(or Ta bitwise or +.El +.Pp +Mathematical: +.Bl -column "xxcoproductxx" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e- Ta \- Ta minus (text font) +.It \e(mi Ta \(mi Ta minus (special font) +.It + Ta + Ta plus (text font) +.It \e(pl Ta \(pl Ta plus (special font) +.It \e(-+ Ta \(-+ Ta minus-plus +.It \e[t+-] Ta \[t+-] Ta plus-minus (text font) +.It \e(+- Ta \(+- Ta plus-minus (special font) +.It \e(pc Ta \(pc Ta center-dot +.It \e[tmu] Ta \[tmu] Ta multiply (text font) +.It \e(mu Ta \(mu Ta multiply (special font) +.It \e(c* Ta \(c* Ta circle-multiply +.It \e(c+ Ta \(c+ Ta circle-plus +.It \e[tdi] Ta \[tdi] Ta divide (text font) +.It \e(di Ta \(di Ta divide (special font) +.It \e(f/ Ta \(f/ Ta fraction +.It \e(** Ta \(** Ta asterisk +.It \e(<= Ta \(<= Ta less-than-equal +.It \e(>= Ta \(>= Ta greater-than-equal +.It \e(<< Ta \(<< Ta much less +.It \e(>> Ta \(>> Ta much greater +.It \e(eq Ta \(eq Ta equal +.It \e(!= Ta \(!= Ta not equal +.It \e(== Ta \(== Ta equivalent +.It \e(ne Ta \(ne Ta not equivalent +.It \e(ap Ta \(ap Ta tilde operator +.It \e(|= Ta \(|= Ta asymptotically equal +.It \e(=\(ti Ta \(=~ Ta approximately equal +.It \e(\(ti\(ti Ta \(~~ Ta almost equal +.It \e(\(ti= Ta \(~= Ta almost equal +.It \e(pt Ta \(pt Ta proportionate +.It \e(es Ta \(es Ta empty set +.It \e(mo Ta \(mo Ta element +.It \e(nm Ta \(nm Ta not element +.It \e(sb Ta \(sb Ta proper subset +.It \e(nb Ta \(nb Ta not subset +.It \e(sp Ta \(sp Ta proper superset +.It \e(nc Ta \(nc Ta not superset +.It \e(ib Ta \(ib Ta reflexive subset +.It \e(ip Ta \(ip Ta reflexive superset +.It \e(ca Ta \(ca Ta intersection +.It \e(cu Ta \(cu Ta union +.It \e(/_ Ta \(/_ Ta angle +.It \e(pp Ta \(pp Ta perpendicular +.It \e(is Ta \(is Ta integral +.It \e[integral] Ta \[integral] Ta integral +.It \e[sum] Ta \[sum] Ta summation +.It \e[product] Ta \[product] Ta product +.It \e[coproduct] Ta \[coproduct] Ta coproduct +.It \e(gr Ta \(gr Ta gradient +.It \e(sr Ta \(sr Ta square root +.It \e[sqrt] Ta \[sqrt] Ta square root +.It \e(lc Ta \(lc Ta left-ceiling +.It \e(rc Ta \(rc Ta right-ceiling +.It \e(lf Ta \(lf Ta left-floor +.It \e(rf Ta \(rf Ta right-floor +.It \e(if Ta \(if Ta infinity +.It \e(Ah Ta \(Ah Ta aleph +.It \e(Im Ta \(Im Ta imaginary +.It \e(Re Ta \(Re Ta real +.It \e(wp Ta \(wp Ta Weierstrass p +.It \e(pd Ta \(pd Ta partial differential +.It \e(-h Ta \(-h Ta Planck constant over 2\(*p +.It \e[hbar] Ta \[hbar] Ta Planck constant over 2\(*p +.It \e(12 Ta \(12 Ta one-half +.It \e(14 Ta \(14 Ta one-fourth +.It \e(34 Ta \(34 Ta three-fourths +.It \e(18 Ta \(18 Ta one-eighth +.It \e(38 Ta \(38 Ta three-eighths +.It \e(58 Ta \(58 Ta five-eighths +.It \e(78 Ta \(78 Ta seven-eighths +.It \e(S1 Ta \(S1 Ta superscript 1 +.It \e(S2 Ta \(S2 Ta superscript 2 +.It \e(S3 Ta \(S3 Ta superscript 3 +.El +.Pp +Ligatures: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(ff Ta \(ff Ta ff ligature +.It \e(fi Ta \(fi Ta fi ligature +.It \e(fl Ta \(fl Ta fl ligature +.It \e(Fi Ta \(Fi Ta ffi ligature +.It \e(Fl Ta \(Fl Ta ffl ligature +.It \e(AE Ta \(AE Ta AE +.It \e(ae Ta \(ae Ta ae +.It \e(OE Ta \(OE Ta OE +.It \e(oe Ta \(oe Ta oe +.It \e(ss Ta \(ss Ta German eszett +.It \e(IJ Ta \(IJ Ta IJ ligature +.It \e(ij Ta \(ij Ta ij ligature +.El +.Pp +Accents: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(a" Ta \(a" Ta Hungarian umlaut +.It \e(a- Ta \(a- Ta macron +.It \e(a. Ta \(a. Ta dotted +.It \e(a^ Ta \(a^ Ta circumflex +.It \e(aa Ta \(aa Ta acute +.It \e\(aq Ta \' Ta acute +.It \e(ga Ta \(ga Ta grave +.It \e\(ga Ta \` Ta grave +.It \e(ab Ta \(ab Ta breve +.It \e(ac Ta \(ac Ta cedilla +.It \e(ad Ta \(ad Ta dieresis +.It \e(ah Ta \(ah Ta caron +.It \e(ao Ta \(ao Ta ring +.It \e(a\(ti Ta \(a~ Ta tilde +.It \e(ho Ta \(ho Ta ogonek +.It \e(ha Ta \(ha Ta hat (ASCII character) +.It \e(ti Ta \(ti Ta tilde (ASCII character) +.El +.Pp +Accented letters: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(\(aqA Ta \('A Ta acute A +.It \e(\(aqE Ta \('E Ta acute E +.It \e(\(aqI Ta \('I Ta acute I +.It \e(\(aqO Ta \('O Ta acute O +.It \e(\(aqU Ta \('U Ta acute U +.It \e(\(aqY Ta \('Y Ta acute Y +.It \e(\(aqa Ta \('a Ta acute a +.It \e(\(aqe Ta \('e Ta acute e +.It \e(\(aqi Ta \('i Ta acute i +.It \e(\(aqo Ta \('o Ta acute o +.It \e(\(aqu Ta \('u Ta acute u +.It \e(\(aqy Ta \('y Ta acute y +.It \e(\(gaA Ta \(`A Ta grave A +.It \e(\(gaE Ta \(`E Ta grave E +.It \e(\(gaI Ta \(`I Ta grave I +.It \e(\(gaO Ta \(`O Ta grave O +.It \e(\(gaU Ta \(`U Ta grave U +.It \e(\(gaa Ta \(`a Ta grave a +.It \e(\(gae Ta \(`e Ta grave e +.It \e(\(gai Ta \(`i Ta grave i +.It \e(\(gao Ta \(`i Ta grave o +.It \e(\(gau Ta \(`u Ta grave u +.It \e(\(tiA Ta \(~A Ta tilde A +.It \e(\(tiN Ta \(~N Ta tilde N +.It \e(\(tiO Ta \(~O Ta tilde O +.It \e(\(tia Ta \(~a Ta tilde a +.It \e(\(tin Ta \(~n Ta tilde n +.It \e(\(tio Ta \(~o Ta tilde o +.It \e(:A Ta \(:A Ta dieresis A +.It \e(:E Ta \(:E Ta dieresis E +.It \e(:I Ta \(:I Ta dieresis I +.It \e(:O Ta \(:O Ta dieresis O +.It \e(:U Ta \(:U Ta dieresis U +.It \e(:a Ta \(:a Ta dieresis a +.It \e(:e Ta \(:e Ta dieresis e +.It \e(:i Ta \(:i Ta dieresis i +.It \e(:o Ta \(:o Ta dieresis o +.It \e(:u Ta \(:u Ta dieresis u +.It \e(:y Ta \(:y Ta dieresis y +.It \e(^A Ta \(^A Ta circumflex A +.It \e(^E Ta \(^E Ta circumflex E +.It \e(^I Ta \(^I Ta circumflex I +.It \e(^O Ta \(^O Ta circumflex O +.It \e(^U Ta \(^U Ta circumflex U +.It \e(^a Ta \(^a Ta circumflex a +.It \e(^e Ta \(^e Ta circumflex e +.It \e(^i Ta \(^i Ta circumflex i +.It \e(^o Ta \(^o Ta circumflex o +.It \e(^u Ta \(^u Ta circumflex u +.It \e(,C Ta \(,C Ta cedilla C +.It \e(,c Ta \(,c Ta cedilla c +.It \e(/L Ta \(/L Ta stroke L +.It \e(/l Ta \(/l Ta stroke l +.It \e(/O Ta \(/O Ta stroke O +.It \e(/o Ta \(/o Ta stroke o +.It \e(oA Ta \(oA Ta ring A +.It \e(oa Ta \(oa Ta ring a +.El +.Pp +Special letters: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(-D Ta \(-D Ta Eth +.It \e(Sd Ta \(Sd Ta eth +.It \e(TP Ta \(TP Ta Thorn +.It \e(Tp Ta \(Tp Ta thorn +.It \e(.i Ta \(.i Ta dotless i +.It \e(.j Ta \(.j Ta dotless j +.El +.Pp +Currency: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(Do Ta \(Do Ta dollar +.It \e(ct Ta \(ct Ta cent +.It \e(Eu Ta \(Eu Ta Euro symbol +.It \e(eu Ta \(eu Ta Euro symbol +.It \e(Ye Ta \(Ye Ta yen +.It \e(Po Ta \(Po Ta pound +.It \e(Cs Ta \(Cs Ta Scandinavian +.It \e(Fn Ta \(Fn Ta florin +.El +.Pp +Units: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(de Ta \(de Ta degree +.It \e(%0 Ta \(%0 Ta per-thousand +.It \e(fm Ta \(fm Ta minute +.It \e(sd Ta \(sd Ta second +.It \e(mc Ta \(mc Ta micro +.It \e(Of Ta \(Of Ta Spanish female ordinal +.It \e(Om Ta \(Om Ta Spanish masculine ordinal +.El +.Pp +Greek letters: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(*A Ta \(*A Ta Alpha +.It \e(*B Ta \(*B Ta Beta +.It \e(*G Ta \(*G Ta Gamma +.It \e(*D Ta \(*D Ta Delta +.It \e(*E Ta \(*E Ta Epsilon +.It \e(*Z Ta \(*Z Ta Zeta +.It \e(*Y Ta \(*Y Ta Eta +.It \e(*H Ta \(*H Ta Theta +.It \e(*I Ta \(*I Ta Iota +.It \e(*K Ta \(*K Ta Kappa +.It \e(*L Ta \(*L Ta Lambda +.It \e(*M Ta \(*M Ta Mu +.It \e(*N Ta \(*N Ta Nu +.It \e(*C Ta \(*C Ta Xi +.It \e(*O Ta \(*O Ta Omicron +.It \e(*P Ta \(*P Ta Pi +.It \e(*R Ta \(*R Ta Rho +.It \e(*S Ta \(*S Ta Sigma +.It \e(*T Ta \(*T Ta Tau +.It \e(*U Ta \(*U Ta Upsilon +.It \e(*F Ta \(*F Ta Phi +.It \e(*X Ta \(*X Ta Chi +.It \e(*Q Ta \(*Q Ta Psi +.It \e(*W Ta \(*W Ta Omega +.It \e(*a Ta \(*a Ta alpha +.It \e(*b Ta \(*b Ta beta +.It \e(*g Ta \(*g Ta gamma +.It \e(*d Ta \(*d Ta delta +.It \e(*e Ta \(*e Ta epsilon +.It \e(*z Ta \(*z Ta zeta +.It \e(*y Ta \(*y Ta eta +.It \e(*h Ta \(*h Ta theta +.It \e(*i Ta \(*i Ta iota +.It \e(*k Ta \(*k Ta kappa +.It \e(*l Ta \(*l Ta lambda +.It \e(*m Ta \(*m Ta mu +.It \e(*n Ta \(*n Ta nu +.It \e(*c Ta \(*c Ta xi +.It \e(*o Ta \(*o Ta omicron +.It \e(*p Ta \(*p Ta pi +.It \e(*r Ta \(*r Ta rho +.It \e(*s Ta \(*s Ta sigma +.It \e(*t Ta \(*t Ta tau +.It \e(*u Ta \(*u Ta upsilon +.It \e(*f Ta \(*f Ta phi +.It \e(*x Ta \(*x Ta chi +.It \e(*q Ta \(*q Ta psi +.It \e(*w Ta \(*w Ta omega +.It \e(+h Ta \(+h Ta theta variant +.It \e(+f Ta \(+f Ta phi variant +.It \e(+p Ta \(+p Ta pi variant +.It \e(+e Ta \(+e Ta epsilon variant +.It \e(ts Ta \(ts Ta sigma terminal +.El +.Sh PREDEFINED STRINGS +Predefined strings are inherited from the macro packages of historical +troff implementations. +They are +.Em not recommended +for use, as they differ across implementations. +Manuals using these predefined strings are almost certainly not +portable. +.Pp +Their syntax is similar to special characters, using +.Sq \e*X +.Pq for a one-character escape , +.Sq \e*(XX +.Pq two-character , +and +.Sq \e*[N] +.Pq N-character . +.Bl -column "Input" "Rendered" "Description" -offset indent +.It Em Input Ta Em Rendered Ta Em Description +.It \e*(Ba Ta \*(Ba Ta vertical bar +.It \e*(Ne Ta \*(Ne Ta not equal +.It \e*(Ge Ta \*(Ge Ta greater-than-equal +.It \e*(Le Ta \*(Le Ta less-than-equal +.It \e*(Gt Ta \*(Gt Ta greater-than +.It \e*(Lt Ta \*(Lt Ta less-than +.It \e*(Pm Ta \*(Pm Ta plus-minus +.It \e*(If Ta \*(If Ta infinity +.It \e*(Pi Ta \*(Pi Ta pi +.It \e*(Na Ta \*(Na Ta NaN +.It \e*(Am Ta \*(Am Ta ampersand +.It \e*R Ta \*R Ta restricted mark +.It \e*(Tm Ta \*(Tm Ta trade mark +.It \e*q Ta \*q Ta double-quote +.It \e*(Rq Ta \*(Rq Ta right-double-quote +.It \e*(Lq Ta \*(Lq Ta left-double-quote +.It \e*(lp Ta \*(lp Ta right-parenthesis +.It \e*(rp Ta \*(rp Ta left-parenthesis +.It \e*(lq Ta \*(lq Ta left double-quote +.It \e*(rq Ta \*(rq Ta right double-quote +.It \e*(ua Ta \*(ua Ta up arrow +.It \e*(va Ta \*(va Ta up-down arrow +.It \e*(<= Ta \*(<= Ta less-than-equal +.It \e*(>= Ta \*(>= Ta greater-than-equal +.It \e*(aa Ta \*(aa Ta acute +.It \e*(ga Ta \*(ga Ta grave +.It \e*(Px Ta \*(Px Ta POSIX standard name +.It \e*(Ai Ta \*(Ai Ta ANSI standard name +.El +.Sh UNICODE CHARACTERS +The escape sequences +.Pp +.Dl \e[uXXXX] and \eC\(aquXXXX\(aq +.Pp +are interpreted as Unicode codepoints. +The codepoint must be in the range above U+0080 and less than U+10FFFF. +For compatibility, the hexadecimal digits +.Sq A +to +.Sq F +must be given as uppercase characters, +and points must be zero-padded to four characters; if +greater than four characters, no zero padding is allowed. +Unicode surrogates are not allowed. +.Sh NUMBERED CHARACTERS +For backward compatibility with existing manuals, +.Xr mandoc 1 +also supports the +.Pp +.Dl \eN\(aq Ns Ar number Ns \(aq and \e[ Ns Cm char Ns Ar number ] +.Pp +escape sequences, inserting the character +.Ar number +from the current character set into the output. +Of course, this is inherently non-portable and is already marked +as deprecated in the Heirloom roff manual; +on top of that, the second form is a GNU extension. +For example, do not use \eN\(aq34\(aq or \e[char34], use \e(dq, +or even the plain +.Sq \(dq +character where possible. +.Sh COMPATIBILITY +This section documents compatibility between mandoc and other +troff implementations, at this time limited to GNU troff +.Pq Qq groff . +.Pp +.Bl -dash -compact +.It +The \eN\(aq\(aq escape sequence is limited to printable characters; in +groff, it accepts arbitrary character numbers. +.It +In +.Fl T Ns Cm ascii , +the +\e(ss, \e(nm, \e(nb, \e(nc, \e(ib, \e(ip, \e(pp, \e[sum], \e[product], +\e[coproduct], \e(gr, \e(-h, and \e(a. special characters render +differently between mandoc and groff. +.It +In +.Fl T Ns Cm html , +the \e(\(ti=, \e(nb, and \e(nc special characters render differently +between mandoc and groff. +.It +The +.Fl T Ns Cm ps +and +.Fl T Ns Cm pdf +modes format like +.Fl T Ns Cm ascii +instead of rendering glyphs as in groff. +.It +The \e[radicalex], \e[sqrtex], and \e(ru special characters have been omitted +from mandoc either because they are poorly documented or they have no +known representation. +.El +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr man 7 , +.Xr mdoc 7 , +.Xr roff 7 +.Sh AUTHORS +The +.Nm +manual page was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . +.Sh CAVEATS +The predefined string +.Sq \e*(Ba +mimics the behaviour of the +.Sq \&| +character in +.Xr mdoc 7 ; +thus, if you wish to render a vertical bar with no side effects, use +the +.Sq \e(ba +escape. diff --git a/static/netbsd/man7/mdoc.7 b/static/netbsd/man7/mdoc.7 new file mode 100644 index 00000000..64d4ff4f --- /dev/null +++ b/static/netbsd/man7/mdoc.7 @@ -0,0 +1,3261 @@ +.\" Id: mdoc.7,v 1.287 2021/07/29 17:32:01 schwarze Exp +.\" +.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons +.\" Copyright (c) 2010, 2011, 2013-2020 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd July 29, 2021 +.Dt MDOC 7 +.Os +.Sh NAME +.Nm mdoc +.Nd semantic markup language for formatting manual pages +.Sh DESCRIPTION +The +.Nm mdoc +language supports authoring of manual pages for the +.Xr man 1 +utility by allowing semantic annotations of words, phrases, +page sections and complete manual pages. +Such annotations are used by formatting tools to achieve a uniform +presentation across all manuals written in +.Nm , +and to support hyperlinking if supported by the output medium. +.Pp +This reference document describes the structure of manual pages +and the syntax and usage of the +.Nm +language. +The reference implementation of a parsing and formatting tool is +.Xr mandoc 1 ; +the +.Sx COMPATIBILITY +section describes compatibility with other implementations. +.Pp +In an +.Nm +document, lines beginning with the control character +.Sq \&. +are called +.Dq macro lines . +The first word is the macro name. +It consists of two or three letters. +Most macro names begin with a capital letter. +For a list of available macros, see +.Sx MACRO OVERVIEW . +The words following the macro name are arguments to the macro, optionally +including the names of other, callable macros; see +.Sx MACRO SYNTAX +for details. +.Pp +Lines not beginning with the control character are called +.Dq text lines . +They provide free-form text to be printed; the formatting of the text +depends on the respective processing context: +.Bd -literal -offset indent +\&.Sh Macro lines change control state. +Text lines are interpreted within the current state. +.Ed +.Pp +Many aspects of the basic syntax of the +.Nm +language are based on the +.Xr roff 7 +language; see the +.Em LANGUAGE SYNTAX +and +.Em MACRO SYNTAX +sections in the +.Xr roff 7 +manual for details, in particular regarding +comments, escape sequences, whitespace, and quoting. +However, using +.Xr roff 7 +requests in +.Nm +documents is discouraged; +.Xr mandoc 1 +supports some of them merely for backward compatibility. +.Sh MANUAL STRUCTURE +A well-formed +.Nm +document consists of a document prologue followed by one or more +sections. +.Pp +The prologue, which consists of the +.Ic \&Dd , +.Ic \&Dt , +and +.Ic \&Os +macros in that order, is required for every document. +.Pp +The first section (sections are denoted by +.Ic \&Sh ) +must be the NAME section, consisting of at least one +.Ic \&Nm +followed by +.Ic \&Nd . +.Pp +Following that, convention dictates specifying at least the +.Em SYNOPSIS +and +.Em DESCRIPTION +sections, although this varies between manual sections. +.Pp +The following is a well-formed skeleton +.Nm +file for a utility +.Qq progname : +.Bd -literal -offset indent +\&.Dd $\&Mdocdate$ +\&.Dt PROGNAME section +\&.Os +\&.Sh NAME +\&.Nm progname +\&.Nd one line about what it does +\&.\e\(dq .Sh LIBRARY +\&.\e\(dq For sections 2, 3, and 9 only. +\&.\e\(dq Not used in OpenBSD. +\&.Sh SYNOPSIS +\&.Nm progname +\&.Op Fl options +\&.Ar +\&.Sh DESCRIPTION +The +\&.Nm +utility processes files ... +\&.\e\(dq .Sh CONTEXT +\&.\e\(dq For section 9 functions only. +\&.\e\(dq .Sh IMPLEMENTATION NOTES +\&.\e\(dq Not used in OpenBSD. +\&.\e\(dq .Sh RETURN VALUES +\&.\e\(dq For sections 2, 3, and 9 function return values only. +\&.\e\(dq .Sh ENVIRONMENT +\&.\e\(dq For sections 1, 6, 7, and 8 only. +\&.\e\(dq .Sh FILES +\&.\e\(dq .Sh EXIT STATUS +\&.\e\(dq For sections 1, 6, and 8 only. +\&.\e\(dq .Sh EXAMPLES +\&.\e\(dq .Sh DIAGNOSTICS +\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. +\&.\e\(dq .Sh ERRORS +\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only. +\&.\e\(dq .Sh SEE ALSO +\&.\e\(dq .Xr foobar 1 +\&.\e\(dq .Sh STANDARDS +\&.\e\(dq .Sh HISTORY +\&.\e\(dq .Sh AUTHORS +\&.\e\(dq .Sh CAVEATS +\&.\e\(dq .Sh BUGS +\&.\e\(dq .Sh SECURITY CONSIDERATIONS +\&.\e\(dq Not used in OpenBSD. +.Ed +.Pp +The sections in an +.Nm +document are conventionally ordered as they appear above. +Sections should be composed as follows: +.Bl -ohang -offset Ds +.It Em NAME +The name(s) and a one line description of the documented material. +The syntax for this as follows: +.Bd -literal -offset indent +\&.Nm name0 , +\&.Nm name1 , +\&.Nm name2 +\&.Nd a one line description +.Ed +.Pp +Multiple +.Sq \&Nm +names should be separated by commas. +.Pp +The +.Ic \&Nm +macro(s) must precede the +.Ic \&Nd +macro. +.Pp +See +.Ic \&Nm +and +.Ic \&Nd . +.It Em LIBRARY +The name of the library containing the documented material, which is +assumed to be a function in a section 2, 3, or 9 manual. +The syntax for this is as follows: +.Bd -literal -offset indent +\&.Lb libarm +.Ed +.Pp +See +.Ic \&Lb . +.It Em SYNOPSIS +Documents the utility invocation syntax, function call syntax, or device +configuration. +.Pp +For the first, utilities (sections 1, 6, and 8), this is +generally structured as follows: +.Bd -literal -offset indent +\&.Nm bar +\&.Op Fl v +\&.Op Fl o Ar file +\&.Op Ar +\&.Nm foo +\&.Op Fl v +\&.Op Fl o Ar file +\&.Op Ar +.Ed +.Pp +Commands should be ordered alphabetically. +.Pp +For the second, function calls (sections 2, 3, 9): +.Bd -literal -offset indent +\&.In header.h +\&.Vt extern const char *global; +\&.Ft "char *" +\&.Fn foo "const char *src" +\&.Ft "char *" +\&.Fn bar "const char *src" +.Ed +.Pp +Ordering of +.Ic \&In , +.Ic \&Vt , +.Ic \&Fn , +and +.Ic \&Fo +macros should follow C header-file conventions. +.Pp +And for the third, configurations (section 4): +.Bd -literal -offset indent +\&.Cd \(dqit* at isa? port 0x2e\(dq +\&.Cd \(dqit* at isa? port 0x4e\(dq +.Ed +.Pp +Manuals not in these sections generally don't need a +.Em SYNOPSIS . +.Pp +Some macros are displayed differently in the +.Em SYNOPSIS +section, particularly +.Ic \&Nm , +.Ic \&Cd , +.Ic \&Fd , +.Ic \&Fn , +.Ic \&Fo , +.Ic \&In , +.Ic \&Vt , +and +.Ic \&Ft . +All of these macros are output on their own line. +If two such dissimilar macros are pairwise invoked (except for +.Ic \&Ft +before +.Ic \&Fo +or +.Ic \&Fn ) , +they are separated by a vertical space, unless in the case of +.Ic \&Fo , +.Ic \&Fn , +and +.Ic \&Ft , +which are always separated by vertical space. +.Pp +When text and macros following an +.Ic \&Nm +macro starting an input line span multiple output lines, +all output lines but the first will be indented to align +with the text immediately following the +.Ic \&Nm +macro, up to the next +.Ic \&Nm , +.Ic \&Sh , +or +.Ic \&Ss +macro or the end of an enclosing block, whichever comes first. +.It Em DESCRIPTION +This begins with an expansion of the brief, one line description in +.Em NAME : +.Bd -literal -offset indent +The +\&.Nm +utility does this, that, and the other. +.Ed +.Pp +It usually follows with a breakdown of the options (if documenting a +command), such as: +.Bd -literal -offset indent +The options are as follows: +\&.Bl \-tag \-width Ds +\&.It Fl v +Print verbose information. +\&.El +.Ed +.Pp +List the options in alphabetical order, +uppercase before lowercase for each letter and +with no regard to whether an option takes an argument. +Put digits in ascending order before all letter options. +.Pp +Manuals not documenting a command won't include the above fragment. +.Pp +Since the +.Em DESCRIPTION +section usually contains most of the text of a manual, longer manuals +often use the +.Ic \&Ss +macro to form subsections. +In very long manuals, the +.Em DESCRIPTION +may be split into multiple sections, each started by an +.Ic \&Sh +macro followed by a non-standard section name, and each having +several subsections, like in the present +.Nm +manual. +.It Em CONTEXT +This section lists the contexts in which functions can be called in section 9. +The contexts are autoconf, process, or interrupt. +.It Em IMPLEMENTATION NOTES +Implementation-specific notes should be kept here. +This is useful when implementing standard functions that may have side +effects or notable algorithmic implications. +.It Em RETURN VALUES +This section documents the +return values of functions in sections 2, 3, and 9. +.Pp +See +.Ic \&Rv . +.It Em ENVIRONMENT +Lists the environment variables used by the utility, +and explains the syntax and semantics of their values. +The +.Xr environ 7 +manual provides examples of typical content and formatting. +.Pp +See +.Ic \&Ev . +.It Em FILES +Documents files used. +It's helpful to document both the file name and a short description of how +the file is used (created, modified, etc.). +.Pp +See +.Ic \&Pa . +.It Em EXIT STATUS +This section documents the +command exit status for section 1, 6, and 8 utilities. +Historically, this information was described in +.Em DIAGNOSTICS , +a practise that is now discouraged. +.Pp +See +.Ic \&Ex . +.It Em EXAMPLES +Example usages. +This often contains snippets of well-formed, well-tested invocations. +Make sure that examples work properly! +.It Em DIAGNOSTICS +Documents error messages. +In section 4 and 9 manuals, these are usually messages printed by the +kernel to the console and to the kernel log. +In section 1, 6, 7, and 8, these are usually messages printed by +userland programs to the standard error output. +.Pp +Historically, this section was used in place of +.Em EXIT STATUS +for manuals in sections 1, 6, and 8; however, this practise is +discouraged. +.Pp +See +.Ic \&Bl +.Fl diag . +.It Em ERRORS +Documents +.Xr errno 2 +settings in sections 2, 3, 4, and 9. +.Pp +See +.Ic \&Er . +.It Em SEE ALSO +References other manuals with related topics. +This section should exist for most manuals. +Cross-references should conventionally be ordered first by section, then +alphabetically (ignoring case). +.Pp +References to other documentation concerning the topic of the manual page, +for example authoritative books or journal articles, may also be +provided in this section. +.Pp +See +.Ic \&Rs +and +.Ic \&Xr . +.It Em STANDARDS +References any standards implemented or used. +If not adhering to any standards, the +.Em HISTORY +section should be used instead. +.Pp +See +.Ic \&St . +.It Em HISTORY +A brief history of the subject, including where it was first implemented, +and when it was ported to or reimplemented for the operating system at hand. +.It Em AUTHORS +Credits to the person or persons who wrote the code and/or documentation. +Authors should generally be noted by both name and email address. +.Pp +See +.Ic \&An . +.It Em CAVEATS +Common misuses and misunderstandings should be explained +in this section. +.It Em BUGS +Known bugs, limitations, and work-arounds should be described +in this section. +.It Em SECURITY CONSIDERATIONS +Documents any security precautions that operators should consider. +.El +.Sh MACRO OVERVIEW +This overview is sorted such that macros of similar purpose are listed +together, to help find the best macro for any given purpose. +Deprecated macros are not included in the overview, but can be found below +in the alphabetical +.Sx MACRO REFERENCE . +.Ss Document preamble and NAME section macros +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year +.It Ic \&Dt Ta document title: Ar TITLE section Op Ar arch +.It Ic \&Os Ta operating system version: Op Ar system Op Ar version +.It Ic \&Nm Ta document name (one argument) +.It Ic \&Nd Ta document description (one line) +.El +.Ss Sections and cross references +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Sh Ta section header (one line) +.It Ic \&Ss Ta subsection header (one line) +.It Ic \&Sx Ta internal cross reference to a section or subsection +.It Ic \&Xr Ta cross reference to another manual page: Ar name section +.It Ic \&Tg Ta tag the definition of a Ar term Pq <= 1 arguments +.It Ic \&Pp Ta start a text paragraph (no arguments) +.El +.Ss Displays and lists +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Bd , \&Ed Ta display block: +.Fl Ar type +.Op Fl offset Ar width +.Op Fl compact +.It Ic \&D1 Ta indented display (one line) +.It Ic \&Dl Ta indented literal display (one line) +.It Ic \&Ql Ta in-line literal display: Ql text +.It Ic \&Bl , \&El Ta list block: +.Fl Ar type +.Op Fl width Ar val +.Op Fl offset Ar val +.Op Fl compact +.It Ic \&It Ta list item (syntax depends on Fl Ar type ) +.It Ic \&Ta Ta table cell separator in Ic \&Bl Fl column No lists +.It Ic \&Rs , \&%* , \&Re Ta bibliographic block (references) +.El +.Ss Spacing control +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Pf Ta prefix, no following horizontal space (one argument) +.It Ic \&Ns Ta roman font, no preceding horizontal space (no arguments) +.It Ic \&Ap Ta apostrophe without surrounding whitespace (no arguments) +.It Ic \&Sm Ta switch horizontal spacing mode: Op Cm on | off +.It Ic \&Bk , \&Ek Ta keep block: Fl words +.El +.Ss Semantic markup for command line utilities +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Nm Ta start a SYNOPSIS block with the name of a utility +.It Ic \&Fl Ta command line options (flags) (>=0 arguments) +.It Ic \&Cm Ta command modifier (>0 arguments) +.It Ic \&Ar Ta command arguments (>=0 arguments) +.It Ic \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure) +.It Ic \&Ic Ta internal or interactive command (>0 arguments) +.It Ic \&Ev Ta environmental variable (>0 arguments) +.It Ic \&Pa Ta file system path (>=0 arguments) +.El +.Ss Semantic markup for function libraries +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Lb Ta function library (one argument) +.It Ic \&In Ta include file (one argument) +.It Ic \&Fd Ta other preprocessor directive (>0 arguments) +.It Ic \&Ft Ta function type (>0 arguments) +.It Ic \&Fo , \&Fc Ta function block: Ar funcname +.It Ic \&Fn Ta function name: Ar funcname Op Ar argument ... +.It Ic \&Fa Ta function argument (>0 arguments) +.It Ic \&Vt Ta variable type (>0 arguments) +.It Ic \&Va Ta variable name (>0 arguments) +.It Ic \&Dv Ta defined variable or preprocessor constant (>0 arguments) +.It Ic \&Er Ta error constant (>0 arguments) +.It Ic \&Ev Ta environmental variable (>0 arguments) +.El +.Ss Various semantic markup +.Bl -column "Brq, Bro, Brc" description +.It Ic \&An Ta author name (>0 arguments) +.It Ic \&Lk Ta hyperlink: Ar uri Op Ar display_name +.It Ic \&Mt Ta Do mailto Dc hyperlink: Ar localpart Ns @ Ns Ar domain +.It Ic \&Cd Ta kernel configuration declaration (>0 arguments) +.It Ic \&Ad Ta memory address (>0 arguments) +.It Ic \&Ms Ta mathematical symbol (>0 arguments) +.El +.Ss Physical markup +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Em Ta italic font or underline (emphasis) (>0 arguments) +.It Ic \&Sy Ta boldface font (symbolic) (>0 arguments) +.It Ic \&No Ta return to roman font (normal) (>0 arguments) +.It Ic \&Bf , \&Ef Ta font block: Fl Ar type | Cm \&Em | \&Li | \&Sy +.El +.Ss Physical enclosures +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text +.It Ic \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text +.It Ic \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text +.It Ic \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text +.It Ic \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text +.It Ic \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text +.It Ic \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text +.It Ic \&Eo , \&Ec Ta generic enclosure +.El +.Ss Text production +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Ex Fl std Ta standard command exit values: Op Ar utility ... +.It Ic \&Rv Fl std Ta standard function return values: Op Ar function ... +.It Ic \&St Ta reference to a standards document (one argument) +.It Ic \&At Ta At +.It Ic \&Bx Ta Bx +.It Ic \&Bsx Ta Bsx +.It Ic \&Nx Ta Nx +.It Ic \&Fx Ta Fx +.It Ic \&Ox Ta Ox +.It Ic \&Dx Ta Dx +.El +.Sh MACRO REFERENCE +This section is a canonical reference of all macros, arranged +alphabetically. +For the scoping of individual macros, see +.Sx MACRO SYNTAX . +.Bl -tag -width 3n +.It Ic \&%A Ar first_name ... last_name +Author name of an +.Ic \&Rs +block. +Multiple authors should each be accorded their own +.Ic \%%A +line. +Author names should be ordered with full or abbreviated forename(s) +first, then full surname. +.It Ic \&%B Ar title +Book title of an +.Ic \&Rs +block. +This macro may also be used in a non-bibliographic context when +referring to book titles. +.It Ic \&%C Ar location +Publication city or location of an +.Ic \&Rs +block. +.It Ic \&%D Oo Ar month day , Oc Ar year +Publication date of an +.Ic \&Rs +block. +Provide the full English name of the +.Ar month +and all four digits of the +.Ar year . +.It Ic \&%I Ar name +Publisher or issuer name of an +.Ic \&Rs +block. +.It Ic \&%J Ar name +Journal name of an +.Ic \&Rs +block. +.It Ic \&%N Ar number +Issue number (usually for journals) of an +.Ic \&Rs +block. +.It Ic \&%O Ar line +Optional information of an +.Ic \&Rs +block. +.It Ic \&%P Ar number +Book or journal page number of an +.Ic \&Rs +block. +Conventionally, the argument starts with +.Ql p.\& +for a single page or +.Ql pp.\& +for a range of pages, for example: +.Pp +.Dl .%P pp. 42\e(en47 +.It Ic \&%Q Ar name +Institutional author (school, government, etc.) of an +.Ic \&Rs +block. +Multiple institutional authors should each be accorded their own +.Ic \&%Q +line. +.It Ic \&%R Ar name +Technical report name of an +.Ic \&Rs +block. +.It Ic \&%T Ar title +Article title of an +.Ic \&Rs +block. +This macro may also be used in a non-bibliographical context when +referring to article titles. +.It Ic \&%U Ar protocol Ns :// Ns Ar path +URI of reference document. +.It Ic \&%V Ar number +Volume number of an +.Ic \&Rs +block. +.It Ic \&Ac +Close an +.Ic \&Ao +block. +Does not have any tail arguments. +.Tg Ad +.It Ic \&Ad Ar address +Memory address. +Do not use this for postal addresses. +.Pp +Examples: +.Dl \&.Ad [0,$] +.Dl \&.Ad 0x00000000 +.Tg An +.It Ic \&An Fl split | nosplit | Ar first_name ... last_name +Author name. +Can be used both for the authors of the program, function, or driver +documented in the manual, or for the authors of the manual itself. +Requires either the name of an author or one of the following arguments: +.Pp +.Bl -tag -width "-nosplitX" -offset indent -compact +.It Fl split +Start a new output line before each subsequent invocation of +.Ic \&An . +.It Fl nosplit +The opposite of +.Fl split . +.El +.Pp +The default is +.Fl nosplit . +The effect of selecting either of the +.Fl split +modes ends at the beginning of the +.Em AUTHORS +section. +In the +.Em AUTHORS +section, the default is +.Fl nosplit +for the first author listing and +.Fl split +for all other author listings. +.Pp +Examples: +.Dl \&.An -nosplit +.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv +.It Ic \&Ao Ar block +Begin a block enclosed by angle brackets. +Does not have any head arguments. +This macro is almost never useful. +See +.Ic \&Aq +for more details. +.Tg Ap +.It Ic \&Ap +Inserts an apostrophe without any surrounding whitespace. +This is generally used as a grammatical device when referring to the verb +form of a function. +.Pp +Examples: +.Dl \&.Fn execve \&Ap d +.Tg Aq +.It Ic \&Aq Ar line +Enclose the rest of the input line in angle brackets. +The only important use case is for email addresses. +See +.Ic \&Mt +for an example. +.Pp +Occasionally, it is used for names of characters and keys, for example: +.Bd -literal -offset indent +Press the +\&.Aq escape +key to ... +.Ed +.Pp +For URIs, use +.Ic \&Lk +instead, and +.Ic \&In +for +.Dq #include +directives. +Never wrap +.Ic \&Ar +in +.Ic \&Aq . +.Pp +Since +.Ic \&Aq +usually renders with non-ASCII characters in non-ASCII output modes, +do not use it where the ASCII characters +.Sq < +and +.Sq > +are required as syntax elements. +Instead, use these characters directly in such cases, combining them +with the macros +.Ic \&Pf , +.Ic \&Ns , +or +.Ic \&Eo +as needed. +.Pp +See also +.Ic \&Ao . +.Tg Ar +.It Ic \&Ar Op Ar placeholder ... +Command arguments. +If an argument is not provided, the string +.Dq file ...\& +is used as a default. +.Pp +Examples: +.Dl ".Fl o Ar file" +.Dl ".Ar" +.Dl ".Ar arg1 , arg2 ." +.Pp +The arguments to the +.Ic \&Ar +macro are names and placeholders for command arguments; +for fixed strings to be passed verbatim as arguments, use +.Ic \&Fl +or +.Ic \&Cm . +.Tg At +.It Ic \&At Op Ar version +Formats an +.At +version. +Accepts one optional argument: +.Pp +.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact +.It Cm v[1-7] | 32v +A version of +.At . +.It Cm III +.At III . +.It Cm V | V.[1-4] +A version of +.At V . +.El +.Pp +Note that these arguments do not begin with a hyphen. +.Pp +Examples: +.Dl \&.At +.Dl \&.At III +.Dl \&.At V.1 +.Pp +See also +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , +.Ic \&Nx , +and +.Ic \&Ox . +.It Ic \&Bc +Close a +.Ic \&Bo +block. +Does not have any tail arguments. +.Tg Bd +.It Ic \&Bd Fl Ns Ar type Oo Fl offset Ar width Oc Op Fl compact +Begin a display block. +Display blocks are used to select a different indentation and +justification than the one used by the surrounding text. +They may contain both macro lines and text lines. +By default, a display block is preceded by a vertical space. +.Pp +The +.Ar type +must be one of the following: +.Bl -tag -width 13n -offset indent +.It Fl centered +Produce one output line from each input line, and center-justify each line. +Using this display type is not recommended; many +.Nm +implementations render it poorly. +.It Fl filled +Change the positions of line breaks to fill each line, and left- and +right-justify the resulting block. +.It Fl literal +Produce one output line from each input line, +and do not justify the block at all. +Preserve white space as it appears in the input. +Always use a constant-width font. +Use this for displaying source code. +.It Fl ragged +Change the positions of line breaks to fill each line, and left-justify +the resulting block. +.It Fl unfilled +The same as +.Fl literal , +but using the same font as for normal text, which is a variable width font +if supported by the output device. +.El +.Pp +The +.Ar type +must be provided first. +Additional arguments may follow: +.Bl -tag -width 13n -offset indent +.It Fl offset Ar width +Indent the display by the +.Ar width , +which may be one of the following: +.Bl -item +.It +One of the pre-defined strings +.Cm indent , +the width of a standard indentation (six constant width characters); +.Cm indent-two , +twice +.Cm indent ; +.Cm left , +which has no effect; +.Cm right , +which justifies to the right margin; or +.Cm center , +which aligns around an imagined center axis. +.It +A macro invocation, which selects a predefined width +associated with that macro. +The most popular is the imaginary macro +.Ar \&Ds , +which resolves to +.Sy 6n . +.It +A scaling width as described in +.Xr roff 7 . +.It +An arbitrary string, which indents by the length of this string. +.El +.Pp +When the argument is missing, +.Fl offset +is ignored. +.It Fl compact +Do not assert vertical space before the display. +.El +.Pp +Examples: +.Bd -literal -offset indent +\&.Bd \-literal \-offset indent \-compact + Hello world. +\&.Ed +.Ed +.Pp +See also +.Ic \&D1 +and +.Ic \&Dl . +.Tg Bf +.It Ic \&Bf Fl emphasis | literal | symbolic | Cm \&Em | \&Li | \&Sy +Change the font mode for a scoped block of text. +The +.Fl emphasis +and +.Cm \&Em +argument are equivalent, as are +.Fl symbolic +and +.Cm \&Sy , +and +.Fl literal +and +.Cm \&Li . +Without an argument, this macro does nothing. +The font mode continues until broken by a new font mode in a nested +scope or +.Ic \&Ef +is encountered. +.Pp +See also +.Ic \&Li , +.Ic \&Ef , +.Ic \&Em , +and +.Ic \&Sy . +.Tg Bk +.It Ic \&Bk Fl words +For each macro, keep its output together on the same output line, +until the end of the macro or the end of the input line is reached, +whichever comes first. +Line breaks in text lines are unaffected. +.Pp +The +.Fl words +argument is required; additional arguments are ignored. +.Pp +The following example will not break within each +.Ic \&Op +macro line: +.Bd -literal -offset indent +\&.Bk \-words +\&.Op Fl f Ar flags +\&.Op Fl o Ar output +\&.Ek +.Ed +.Pp +Be careful in using over-long lines within a keep block! +Doing so will clobber the right margin. +.Tg Bl +.It Xo +.Ic \&Bl +.Fl Ns Ar type +.Op Fl width Ar val +.Op Fl offset Ar val +.Op Fl compact +.Op Ar col ... +.Xc +Begin a list. +Lists consist of items specified using the +.Ic \&It +macro, containing a head or a body or both. +.Pp +The list +.Ar type +is mandatory and must be specified first. +The +.Fl width +and +.Fl offset +arguments accept macro names as described for +.Ic \&Bd +.Fl offset , +scaling widths as described in +.Xr roff 7 , +or use the length of the given string. +The +.Fl offset +is a global indentation for the whole list, affecting both item heads +and bodies. +For those list types supporting it, the +.Fl width +argument requests an additional indentation of item bodies, +to be added to the +.Fl offset . +Unless the +.Fl compact +argument is specified, list entries are separated by vertical space. +.Pp +A list must specify one of the following list types: +.Bl -tag -width 12n -offset indent +.It Fl bullet +No item heads can be specified, but a bullet will be printed at the head +of each item. +Item bodies start on the same output line as the bullet +and are indented according to the +.Fl width +argument. +.It Fl column +A columnated list. +The +.Fl width +argument has no effect; instead, the string length of each argument +specifies the width of one column. +If the first line of the body of a +.Fl column +list is not an +.Ic \&It +macro line, +.Ic \&It +contexts spanning one input line each are implied until an +.Ic \&It +macro line is encountered, at which point items start being interpreted as +described in the +.Ic \&It +documentation. +.It Fl dash +Like +.Fl bullet , +except that dashes are used in place of bullets. +.It Fl diag +Like +.Fl inset , +except that item heads are not parsed for macro invocations. +Most often used in the +.Em DIAGNOSTICS +section with error constants in the item heads. +.It Fl enum +A numbered list. +No item heads can be specified. +Formatted like +.Fl bullet , +except that cardinal numbers are used in place of bullets, +starting at 1. +.It Fl hang +Like +.Fl tag , +except that the first lines of item bodies are not indented, but follow +the item heads like in +.Fl inset +lists. +.It Fl hyphen +Synonym for +.Fl dash . +.It Fl inset +Item bodies follow items heads on the same line, using normal inter-word +spacing. +Bodies are not indented, and the +.Fl width +argument is ignored. +.It Fl item +No item heads can be specified, and none are printed. +Bodies are not indented, and the +.Fl width +argument is ignored. +.It Fl ohang +Item bodies start on the line following item heads and are not indented. +The +.Fl width +argument is ignored. +.It Fl tag +Item bodies are indented according to the +.Fl width +argument. +When an item head fits inside the indentation, the item body follows +this head on the same output line. +Otherwise, the body starts on the output line following the head. +.El +.Pp +Lists may be nested within lists and displays. +Nesting of +.Fl column +and +.Fl enum +lists may not be portable. +.Pp +See also +.Ic \&El +and +.Ic \&It . +.It Ic \&Bo Ar block +Begin a block enclosed by square brackets. +Does not have any head arguments. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Bo 1 , +\&.Dv BUFSIZ \&Bc +.Ed +.Pp +See also +.Ic \&Bq . +.Tg Bq +.It Ic \&Bq Ar line +Encloses its arguments in square brackets. +.Pp +Examples: +.Dl \&.Bq 1 , \&Dv BUFSIZ +.Pp +.Em Remarks : +this macro is sometimes abused to emulate optional arguments for +commands; the correct macros to use for this purpose are +.Ic \&Op , +.Ic \&Oo , +and +.Ic \&Oc . +.Pp +See also +.Ic \&Bo . +.It Ic \&Brc +Close a +.Ic \&Bro +block. +Does not have any tail arguments. +.It Ic \&Bro Ar block +Begin a block enclosed by curly braces. +Does not have any head arguments. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Bro 1 , ... , +\&.Va n \&Brc +.Ed +.Pp +See also +.Ic \&Brq . +.Tg Brq +.It Ic \&Brq Ar line +Encloses its arguments in curly braces. +.Pp +Examples: +.Dl \&.Brq 1 , ... , \&Va n +.Pp +See also +.Ic \&Bro . +.Tg Bsx +.It Ic \&Bsx Op Ar version +Format the +.Bsx +version provided as an argument, or a default value if +no argument is provided. +.Pp +Examples: +.Dl \&.Bsx 1.0 +.Dl \&.Bsx +.Pp +See also +.Ic \&At , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , +.Ic \&Nx , +and +.Ic \&Ox . +.It Ic \&Bt +Supported only for compatibility, do not use this in new manuals. +Prints +.Dq is currently in beta test. +.Tg Bx +.It Ic \&Bx Op Ar version Op Ar variant +Format the +.Bx +version provided as an argument, or a default value if no +argument is provided. +.Pp +Examples: +.Dl \&.Bx 4.3 Tahoe +.Dl \&.Bx 4.4 +.Dl \&.Bx +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Dx , +.Ic \&Fx , +.Ic \&Nx , +and +.Ic \&Ox . +.Tg Cd +.It Ic \&Cd Ar line +Kernel configuration declaration. +This denotes strings accepted by +.Xr config 8 . +It is most often used in section 4 manual pages. +.Pp +Examples: +.Dl \&.Cd device le0 at scode? +.Pp +.Em Remarks : +this macro is commonly abused by using quoted literals to retain +whitespace and align consecutive +.Ic \&Cd +declarations. +This practise is discouraged. +.Tg Cm +.It Ic \&Cm Ar keyword ... +Command modifiers. +Typically used for fixed strings passed as arguments to interactive +commands, to commands in interpreted scripts, or to configuration +file directives, unless +.Ic \&Fl +is more appropriate. +.Pp +Examples: +.Dl ".Nm mt Fl f Ar device Cm rewind" +.Dl ".Nm ps Fl o Cm pid , Ns Cm command" +.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" +.Dl ".Ic set Fl o Cm vi" +.Dl ".Ic lookup Cm file bind" +.Dl ".Ic permit Ar identity Op Cm as Ar target" +.Tg D1 +.It Ic \&D1 Ar line +One-line indented display. +This is formatted by the default rules and is useful for simple indented +statements. +It is followed by a newline. +.Pp +Examples: +.Dl \&.D1 \&Fl abcdefgh +.Pp +See also +.Ic \&Bd +and +.Ic \&Dl . +.It Ic \&Db +This macro is obsolete. +No replacement is needed. +It is ignored by +.Xr mandoc 1 +and groff including its arguments. +It was formerly used to toggle a debugging mode. +.It Ic \&Dc +Close a +.Ic \&Do +block. +Does not have any tail arguments. +.Tg Dd +.It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year +Document date for display in the page footer, +by convention the date of the last change. +This is the mandatory first macro of any +.Nm +manual. +.Pp +The +.Ar month +is the full English month name, the +.Ar day +is an integer number, and the +.Ar year +is the full four-digit year. +.Pp +Other arguments are not portable; the +.Xr mandoc 1 +utility handles them as follows: +.Bl -dash -offset 3n -compact +.It +To have the date automatically filled in by the +.Ox +version of +.Xr cvs 1 , +the special string +.Dq $\&Mdocdate$ +can be given as an argument. +.It +The traditional, purely numeric +.Xr man 7 +format +.Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day +is accepted, too. +.It +If a date string cannot be parsed, it is used verbatim. +.It +If no date string is given, the current date is used. +.El +.Pp +Examples: +.Dl \&.Dd $\&Mdocdate$ +.Dl \&.Dd $\&Mdocdate: July 2 2018$ +.Dl \&.Dd July 2, 2018 +.Pp +See also +.Ic \&Dt +and +.Ic \&Os . +.Tg Dl +.It Ic \&Dl Ar line +One-line indented display. +This is formatted as literal text and is useful for commands and +invocations. +It is followed by a newline. +.Pp +Examples: +.Dl \&.Dl % mandoc mdoc.7 \e(ba less +.Pp +See also +.Ic \&Ql , +.Ic \&Bd Fl literal , +and +.Ic \&D1 . +.It Ic \&Do Ar block +Begin a block enclosed by double quotes. +Does not have any head arguments. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Do +April is the cruellest month +\&.Dc +\e(em T.S. Eliot +.Ed +.Pp +See also +.Ic \&Dq . +.Tg Dq +.It Ic \&Dq Ar line +Encloses its arguments in +.Dq typographic +double-quotes. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Dq April is the cruellest month +\e(em T.S. Eliot +.Ed +.Pp +See also +.Ic \&Qq , +.Ic \&Sq , +and +.Ic \&Do . +.Tg Dt +.It Ic \&Dt Ar TITLE section Op Ar arch +Document title for display in the page header. +This is the mandatory second macro of any +.Nm +file. +.Pp +Its arguments are as follows: +.Bl -tag -width section -offset 2n +.It Ar TITLE +The document's title (name), defaulting to +.Dq UNTITLED +if unspecified. +To achieve a uniform appearance of page header lines, +it should by convention be all caps. +.It Ar section +The manual section. +This may be one of +.Cm 1 +.Pq General Commands , +.Cm 2 +.Pq System Calls , +.Cm 3 +.Pq Library Functions , +.Cm 3p +.Pq Perl Library , +.Cm 4 +.Pq Device Drivers , +.Cm 5 +.Pq File Formats , +.Cm 6 +.Pq Games , +.Cm 7 +.Pq Miscellaneous Information , +.Cm 8 +.Pq System Manager's Manual , +or +.Cm 9 +.Pq Kernel Developer's Manual . +It should correspond to the manual's filename suffix and defaults to +the empty string if unspecified. +.It Ar arch +This specifies the machine architecture a manual page applies to, +where relevant, for example +.Cm alpha , +.Cm amd64 , +.Cm i386 , +or +.Cm sparc64 . +The list of valid architectures varies by operating system. +.El +.Pp +Examples: +.Dl \&.Dt FOO 1 +.Dl \&.Dt FOO 9 i386 +.Pp +See also +.Ic \&Dd +and +.Ic \&Os . +.Tg Dv +.It Ic \&Dv Ar identifier ... +Defined variables such as preprocessor constants, constant symbols, +enumeration values, and so on. +.Pp +Examples: +.Dl \&.Dv NULL +.Dl \&.Dv BUFSIZ +.Dl \&.Dv STDOUT_FILENO +.Pp +See also +.Ic \&Er +and +.Ic \&Ev +for special-purpose constants, +.Ic \&Va +for variable symbols, and +.Ic \&Fd +for listing preprocessor variable definitions in the +.Em SYNOPSIS . +.Tg Dx +.It Ic \&Dx Op Ar version +Format the +.Dx +version provided as an argument, or a default +value if no argument is provided. +.Pp +Examples: +.Dl \&.Dx 2.4.1 +.Dl \&.Dx +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Fx , +.Ic \&Nx , +and +.Ic \&Ox . +.It Ic \&Ec Op Ar closing_delimiter +Close a scope started by +.Ic \&Eo . +.Pp +The +.Ar closing_delimiter +argument is used as the enclosure tail, for example, specifying \e(rq +will emulate +.Ic \&Dc . +.It Ic \&Ed +End a display context started by +.Ic \&Bd . +.It Ic \&Ef +End a font mode context started by +.Ic \&Bf . +.It Ic \&Ek +End a keep context started by +.Ic \&Bk . +.It Ic \&El +End a list context started by +.Ic \&Bl . +See also +.Ic \&It . +.Tg Em +.It Ic \&Em Ar word ... +Request an italic font. +If the output device does not provide that, underline. +.Pp +This is most often used for stress emphasis (not to be confused with +importance, see +.Ic \&Sy ) . +In the rare cases where none of the semantic markup macros fit, +it can also be used for technical terms and placeholders, except +that for syntax elements, +.Ic \&Sy +and +.Ic \&Ar +are preferred, respectively. +.Pp +Examples: +.Bd -literal -compact -offset indent +Selected lines are those +\&.Em not +matching any of the specified patterns. +Some of the functions use a +\&.Em hold space +to save the pattern space for subsequent retrieval. +.Ed +.Pp +See also +.Ic \&No , +.Ic \&Ql , +and +.Ic \&Sy . +.It Ic \&En Ar word ... +This macro is obsolete. +Use +.Ic \&Eo +or any of the other enclosure macros. +.Pp +It encloses its argument in the delimiters specified by the last +.Ic \&Es +macro. +.Tg Eo +.It Ic \&Eo Op Ar opening_delimiter +An arbitrary enclosure. +The +.Ar opening_delimiter +argument is used as the enclosure head, for example, specifying \e(lq +will emulate +.Ic \&Do . +.Tg Er +.It Ic \&Er Ar identifier ... +Error constants for definitions of the +.Va errno +libc global variable. +This is most often used in section 2 and 3 manual pages. +.Pp +Examples: +.Dl \&.Er EPERM +.Dl \&.Er ENOENT +.Pp +See also +.Ic \&Dv +for general constants. +.It Ic \&Es Ar opening_delimiter closing_delimiter +This macro is obsolete. +Use +.Ic \&Eo +or any of the other enclosure macros. +.Pp +It takes two arguments, defining the delimiters to be used by subsequent +.Ic \&En +macros. +.Tg Ev +.It Ic \&Ev Ar identifier ... +Environmental variables such as those specified in +.Xr environ 7 . +.Pp +Examples: +.Dl \&.Ev DISPLAY +.Dl \&.Ev PATH +.Pp +See also +.Ic \&Dv +for general constants. +.Tg Ex +.It Ic \&Ex Fl std Op Ar utility ... +Insert a standard sentence regarding command exit values of 0 on success +and >0 on failure. +This is most often used in section 1, 6, and 8 manual pages. +.Pp +If +.Ar utility +is not specified, the document's name set by +.Ic \&Nm +is used. +Multiple +.Ar utility +arguments are treated as separate utilities. +.Pp +See also +.Ic \&Rv . +.Tg Fa +.It Ic \&Fa Ar argument ... +Function argument or parameter. +Each argument may be a name and a type (recommended for the +.Em SYNOPSIS +section), a name alone (for function invocations), +or a type alone (for function prototypes). +If both a type and a name are given or if the type consists of multiple +words, all words belonging to the same function argument have to be +given in a single argument to the +.Ic \&Fa +macro. +.Pp +This macro is also used to specify the field name of a structure. +.Pp +Most often, the +.Ic \&Fa +macro is used in the +.Em SYNOPSIS +within +.Ic \&Fo +blocks when documenting multi-line function prototypes. +If invoked with multiple arguments, the arguments are separated by a +comma. +Furthermore, if the following macro is another +.Ic \&Fa , +the last argument will also have a trailing comma. +.Pp +Examples: +.Dl \&.Fa \(dqconst char *p\(dq +.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq +.Dl \&.Fa \(dqchar *\(dq size_t +.Pp +See also +.Ic \&Fo . +.It Ic \&Fc +End a function context started by +.Ic \&Fo . +.Tg Fd +.It Ic \&Fd Pf # Ar directive Op Ar argument ... +Preprocessor directive, in particular for listing it in the +.Em SYNOPSIS . +Historically, it was also used to document include files. +The latter usage has been deprecated in favour of +.Ic \&In . +.Pp +Examples: +.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler +.Dl \&.Fd #define SIO_MAXNFDS +.Dl \&.Fd #ifdef FS_DEBUG +.Dl \&.Ft void +.Dl \&.Fn dbg_open \(dqconst char *\(dq +.Dl \&.Fd #endif +.Pp +See also +.Sx MANUAL STRUCTURE , +.Ic \&In , +and +.Ic \&Dv . +.Tg Fl +.It Ic \&Fl Op Ar word ... +Command-line flag or option. +Used when listing arguments to command-line utilities. +For each argument, prints an ASCII hyphen-minus character +.Sq \- , +immediately followed by the argument. +If no arguments are provided, a hyphen-minus is printed followed by a space. +If the argument is a macro, a hyphen-minus is prefixed +to the subsequent macro output. +.Pp +Examples: +.Dl ".Nm du Op Fl H | L | P" +.Dl ".Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" +.Dl ".Nm route Cm add Fl inet Ar destination gateway" +.Dl ".Nm locate.updatedb Op Fl \e-fcodes Ns = Ns Ar dbfile" +.Dl ".Nm aucat Fl o Fl" +.Dl ".Nm kill Fl Ar signal_number" +.Pp +For GNU-sytle long options, escaping the additional hyphen-minus is not +strictly required, but may be safer with future versions of GNU troff; see +.Xr mandoc_char 7 +for details. +.Pp +See also +.Ic \&Cm . +.Tg Fn +.It Ic \&Fn Ar funcname Op Ar argument ... +A function name. +.Pp +Function arguments are surrounded in parenthesis and +are delimited by commas. +If no arguments are specified, blank parenthesis are output. +In the +.Em SYNOPSIS +section, this macro starts a new output line, +and a blank line is automatically inserted between function definitions. +.Pp +Examples: +.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq +.Dl \&.Fn funcname \(dqint arg0\(dq +.Dl \&.Fn funcname arg0 +.Bd -literal -offset indent +\&.Ft functype +\&.Fn funcname +.Ed +.Pp +When referring to a function documented in another manual page, use +.Ic \&Xr +instead. +See also +.Sx MANUAL STRUCTURE , +.Ic \&Fo , +and +.Ic \&Ft . +.Tg Fo +.It Ic \&Fo Ar funcname +Begin a function block. +This is a multi-line version of +.Ic \&Fn . +.Pp +Invocations usually occur in the following context: +.Bd -ragged -offset indent +.Pf \. Ic \&Ft Ar functype +.br +.Pf \. Ic \&Fo Ar funcname +.br +.Pf \. Ic \&Fa Qq Ar argtype Ar argname +.br +\&.\.\. +.br +.Pf \. Ic \&Fc +.Ed +.Pp +A +.Ic \&Fo +scope is closed by +.Ic \&Fc . +.Pp +See also +.Sx MANUAL STRUCTURE , +.Ic \&Fa , +.Ic \&Fc , +and +.Ic \&Ft . +.It Ic \&Fr Ar number +This macro is obsolete. +No replacement markup is needed. +.Pp +It was used to show numerical function return values in an italic font. +.Tg Ft +.It Ic \&Ft Ar functype +A function type. +.Pp +In the +.Em SYNOPSIS +section, a new output line is started after this macro. +.Pp +Examples: +.Dl \&.Ft int +.Bd -literal -offset indent -compact +\&.Ft functype +\&.Fn funcname +.Ed +.Pp +See also +.Sx MANUAL STRUCTURE , +.Ic \&Fn , +and +.Ic \&Fo . +.Tg Fx +.It Ic \&Fx Op Ar version +Format the +.Fx +version provided as an argument, or a default value +if no argument is provided. +.Pp +Examples: +.Dl \&.Fx 7.1 +.Dl \&.Fx +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Nx , +and +.Ic \&Ox . +.It Ic \&Hf Ar filename +This macro is not implemented in +.Xr mandoc 1 . +It was used to include the contents of a (header) file literally. +.Tg Ic +.It Ic \&Ic Ar keyword ... +Internal or interactive command, or configuration instruction +in a configuration file. +See also +.Ic \&Cm . +.Pp +Examples: +.Dl \&.Ic :wq +.Dl \&.Ic hash +.Dl \&.Ic alias +.Pp +Note that using +.Ic \&Ql , +.Ic \&Dl , +or +.Ic \&Bd Fl literal +is preferred for displaying code samples; the +.Ic \&Ic +macro is used when referring to an individual command name. +.Tg In +.It Ic \&In Ar filename +The name of an include file. +This macro is most often used in section 2, 3, and 9 manual pages. +.Pp +When invoked as the first macro on an input line in the +.Em SYNOPSIS +section, the argument is displayed in angle brackets +and preceded by +.Qq #include , +and a blank line is inserted in front if there is a preceding +function declaration. +In other sections, it only encloses its argument in angle brackets +and causes no line break. +.Pp +Examples: +.Dl \&.In sys/types.h +.Pp +See also +.Sx MANUAL STRUCTURE . +.Tg It +.It Ic \&It Op Ar head +A list item. +The syntax of this macro depends on the list type. +.Pp +Lists +of type +.Fl hang , +.Fl ohang , +.Fl inset , +and +.Fl diag +have the following syntax: +.Pp +.D1 Pf \. Ic \&It Ar args +.Pp +Lists of type +.Fl bullet , +.Fl dash , +.Fl enum , +.Fl hyphen +and +.Fl item +have the following syntax: +.Pp +.D1 Pf \. Ic \&It +.Pp +with subsequent lines interpreted within the scope of the +.Ic \&It +until either a closing +.Ic \&El +or another +.Ic \&It . +.Pp +The +.Fl tag +list has the following syntax: +.Pp +.D1 Pf \. Ic \&It Op Cm args +.Pp +Subsequent lines are interpreted as with +.Fl bullet +and family. +The line arguments correspond to the list's left-hand side; body +arguments correspond to the list's contents. +.Pp +The +.Fl column +list is the most complicated. +Its syntax is as follows: +.Pp +.D1 Pf \. Ic \&It Ar cell Op Ic \&Ta Ar cell ... +.D1 Pf \. Ic \&It Ar cell Op Ar cell ... +.Pp +The arguments consist of one or more lines of text and macros +representing a complete table line. +Cells within the line are delimited by the special +.Ic \&Ta +block macro or by literal tab characters. +.Pp +Using literal tabs is strongly discouraged because they are very +hard to use correctly and +.Nm +code using them is very hard to read. +In particular, a blank character is syntactically significant +before and after the literal tab character. +If a word precedes or follows the tab without an intervening blank, +that word is never interpreted as a macro call, but always output +literally. +.Pp +The tab cell delimiter may only be used within the +.Ic \&It +line itself; on following lines, only the +.Ic \&Ta +macro can be used to delimit cells, and portability requires that +.Ic \&Ta +is called by other macros: some parsers do not recognize it when +it appears as the first macro on a line. +.Pp +Note that quoted strings may span tab-delimited cells on an +.Ic \&It +line. +For example, +.Pp +.Dl .It \(dqcol1 ,\& col2 ,\(dq \&; +.Pp +will preserve the whitespace before both commas, +but not the whitespace before the semicolon. +.Pp +See also +.Ic \&Bl . +.Tg Lb +.It Ic \&Lb Cm lib Ns Ar name +Specify a library. +.Pp +The +.Ar name +parameter may be a system library, such as +.Cm z +or +.Cm pam , +in which case a small library description is printed next to the linker +invocation; or a custom library, in which case the library name is +printed in quotes. +This is most commonly used in the +.Em SYNOPSIS +section as described in +.Sx MANUAL STRUCTURE . +.Pp +Examples: +.Dl \&.Lb libz +.Dl \&.Lb libmandoc +.Tg Li +.It Ic \&Li Ar word ... +Request a typewriter (literal) font. +Deprecated because on terminal output devices, this is usually +indistinguishable from normal text. +For literal displays, use +.Ic \&Ql Pq in-line , +.Ic \&Dl Pq single line , +or +.Ic \&Bd Fl literal Pq multi-line +instead. +.Tg Lk +.It Ic \&Lk Ar uri Op Ar display_name +Format a hyperlink. +.Pp +Examples: +.Dl \&.Lk https://bsd.lv \(dqThe BSD.lv Project\(dq +.Dl \&.Lk https://bsd.lv +.Pp +See also +.Ic \&Mt . +.It Ic \&Lp +Deprecated synonym for +.Ic \&Pp . +.Tg Ms +.It Ic \&Ms Ar name +Display a mathematical symbol. +.Pp +Examples: +.Dl \&.Ms sigma +.Dl \&.Ms aleph +.Tg Mt +.It Ic \&Mt Ar localpart Ns @ Ns Ar domain +Format a +.Dq mailto: +hyperlink. +.Pp +Examples: +.Dl \&.Mt discuss@manpages.bsd.lv +.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv +.Tg Nd +.It Ic \&Nd Ar line +A one line description of the manual's content. +This is the mandatory last macro of the +.Em NAME +section and not appropriate for other sections. +.Pp +Examples: +.Dl Pf . Ic \&Nd mdoc language reference +.Dl Pf . Ic \&Nd format and display UNIX manuals +.Pp +The +.Ic \&Nd +macro technically accepts child macros and terminates with a subsequent +.Ic \&Sh +invocation. +Do not assume this behaviour: some +.Xr whatis 1 +database generators are not smart enough to parse more than the line +arguments and will display macros verbatim. +.Pp +See also +.Ic \&Nm . +.Tg Nm +.It Ic \&Nm Op Ar name +The name of the manual page, or \(em in particular in section 1, 6, +and 8 pages \(em of an additional command or feature documented in +the manual page. +When first invoked, the +.Ic \&Nm +macro expects a single argument, the name of the manual page. +Usually, the first invocation happens in the +.Em NAME +section of the page. +The specified name will be remembered and used whenever the macro is +called again without arguments later in the page. +The +.Ic \&Nm +macro uses +.Sx Block full-implicit +semantics when invoked as the first macro on an input line in the +.Em SYNOPSIS +section; otherwise, it uses ordinary +.Sx In-line +semantics. +.Pp +Examples: +.Bd -literal -offset indent +\&.Sh SYNOPSIS +\&.Nm cat +\&.Op Fl benstuv +\&.Op Ar +.Ed +.Pp +In the +.Em SYNOPSIS +of section 2, 3 and 9 manual pages, use the +.Ic \&Fn +macro rather than +.Ic \&Nm +to mark up the name of the manual page. +.Tg No +.It Ic \&No Ar word ... +Normal text. +Closes the scope of any preceding in-line macro. +When used after physical formatting macros like +.Ic \&Em +or +.Ic \&Sy , +switches back to the standard font face and weight. +Can also be used to embed plain text strings in macro lines +using semantic annotation macros. +.Pp +Examples: +.Dl ".Em italic , Sy bold , No and roman" +.Bd -literal -offset indent +\&.Sm off +\&.Cm :C No / Ar pattern No / Ar replacement No / +\&.Sm on +.Ed +.Pp +See also +.Ic \&Em , +.Ic \&Ql , +and +.Ic \&Sy . +.Tg Ns +.It Ic \&Ns +Suppress a space between the output of the preceding macro +and the following text or macro. +Following invocation, input is interpreted as normal text +just like after an +.Ic \&No +macro. +.Pp +This has no effect when invoked at the start of a macro line. +.Pp +Examples: +.Dl ".Ar name Ns = Ns Ar value" +.Dl ".Cm :M Ns Ar pattern" +.Dl ".Fl o Ns Ar output" +.Pp +See also +.Ic \&No +and +.Ic \&Sm . +.Tg Nx +.It Ic \&Nx Op Ar version +Format the +.Nx +version provided as an argument, or a default value if +no argument is provided. +.Pp +Examples: +.Dl \&.Nx 5.01 +.Dl \&.Nx +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , +and +.Ic \&Ox . +.It Ic \&Oc +Close multi-line +.Ic \&Oo +context. +.It Ic \&Oo Ar block +Multi-line version of +.Ic \&Op . +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Oo +\&.Op Fl flag Ns Ar value +\&.Oc +.Ed +.Tg Op +.It Ic \&Op Ar line +Optional part of a command line. +Prints the argument(s) in brackets. +This is most often used in the +.Em SYNOPSIS +section of section 1 and 8 manual pages. +.Pp +Examples: +.Dl \&.Op \&Fl a \&Ar b +.Dl \&.Op \&Ar a | b +.Pp +See also +.Ic \&Oo . +.Tg Os +.It Ic \&Os Op Ar system Op Ar version +Operating system version for display in the page footer. +This is the mandatory third macro of +any +.Nm +file. +.Pp +The optional +.Ar system +parameter specifies the relevant operating system or environment. +It is suggested to leave it unspecified, in which case +.Xr mandoc 1 +uses its +.Fl Ios +argument or, if that isn't specified either, +.Fa sysname +and +.Fa release +as returned by +.Xr uname 3 . +.Pp +Examples: +.Dl \&.Os +.Dl \&.Os KTH/CSC/TCS +.Dl \&.Os BSD 4.3 +.Pp +See also +.Ic \&Dd +and +.Ic \&Dt . +.It Ic \&Ot Ar functype +This macro is obsolete. +Use +.Ic \&Ft +instead; with +.Xr mandoc 1 , +both have the same effect. +.Pp +Historical +.Nm +packages described it as +.Dq "old function type (FORTRAN)" . +.Tg Ox +.It Ic \&Ox Op Ar version +Format the +.Ox +version provided as an argument, or a default value +if no argument is provided. +.Pp +Examples: +.Dl \&.Ox 4.5 +.Dl \&.Ox +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , +and +.Ic \&Nx . +.Tg Pa +.It Ic \&Pa Ar name ... +An absolute or relative file system path, or a file or directory name. +If an argument is not provided, the character +.Sq \(ti +is used as a default. +.Pp +Examples: +.Dl \&.Pa /usr/bin/mandoc +.Dl \&.Pa /usr/share/man/man7/mdoc.7 +.Pp +See also +.Ic \&Lk . +.It Ic \&Pc +Close parenthesised context opened by +.Ic \&Po . +.Tg Pf +.It Ic \&Pf Ar prefix macro Op Ar argument ... +Removes the space between its argument and the following macro. +It is equivalent to: +.Pp +.D1 Ic \&No Pf \e& Ar prefix Ic \&Ns Ar macro Op Ar argument ... +.Pp +The +.Ar prefix +argument is not parsed for macro names or delimiters, +but used verbatim as if it were escaped. +.Pp +Examples: +.Dl ".Pf $ Ar variable_name" +.Dl ".Pf . Ar macro_name" +.Dl ".Pf 0x Ar hex_digits" +.Pp +See also +.Ic \&Ns +and +.Ic \&Sm . +.It Ic \&Po Ar block +Multi-line version of +.Ic \&Pq . +.Tg Pp +.It Ic \&Pp +Break a paragraph. +This will assert vertical space between prior and subsequent macros +and/or text. +.Pp +Paragraph breaks are not needed before or after +.Ic \&Sh +or +.Ic \&Ss +macros or before displays +.Pq Ic \&Bd Ar line +or lists +.Pq Ic \&Bl +unless the +.Fl compact +flag is given. +.Tg Pq +.It Ic \&Pq Ar line +Parenthesised enclosure. +.Pp +See also +.Ic \&Po . +.It Ic \&Qc +Close quoted context opened by +.Ic \&Qo . +.Tg Ql +.It Ic \&Ql Ar line +In-line literal display. +This can be used for complete command invocations and for multi-word +code examples when an indented display is not desired. +.Pp +See also +.Ic \&Dl +and +.Ic \&Bd +.Fl literal . +.It Ic \&Qo Ar block +Multi-line version of +.Ic \&Qq . +.Tg Qq +.It Ic \&Qq Ar line +Encloses its arguments in +.Qq typewriter +double-quotes. +Consider using +.Ic \&Dq . +.Pp +See also +.Ic \&Dq , +.Ic \&Sq , +and +.Ic \&Qo . +.It Ic \&Re +Close an +.Ic \&Rs +block. +Does not have any tail arguments. +.Tg Rs +.It Ic \&Rs +Begin a bibliographic +.Pq Dq reference +block. +Does not have any head arguments. +The block macro may only contain +.Ic \&%A , +.Ic \&%B , +.Ic \&%C , +.Ic \&%D , +.Ic \&%I , +.Ic \&%J , +.Ic \&%N , +.Ic \&%O , +.Ic \&%P , +.Ic \&%Q , +.Ic \&%R , +.Ic \&%T , +.Ic \&%U , +and +.Ic \&%V +child macros (at least one must be specified). +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Rs +\&.%A J. E. Hopcroft +\&.%A J. D. Ullman +\&.%B Introduction to Automata Theory, Languages, and Computation +\&.%I Addison-Wesley +\&.%C Reading, Massachusetts +\&.%D 1979 +\&.Re +.Ed +.Pp +If an +.Ic \&Rs +block is used within a SEE ALSO section, a vertical space is asserted +before the rendered output, else the block continues on the current +line. +.Tg Rv +.It Ic \&Rv Fl std Op Ar function ... +Insert a standard sentence regarding a function call's return value of 0 +on success and \-1 on error, with the +.Va errno +libc global variable set on error. +.Pp +If +.Ar function +is not specified, the document's name set by +.Ic \&Nm +is used. +Multiple +.Ar function +arguments are treated as separate functions. +.Pp +See also +.Ic \&Ex . +.It Ic \&Sc +Close single-quoted context opened by +.Ic \&So . +.Tg Sh +.It Ic \&Sh Ar TITLE LINE +Begin a new section. +For a list of conventional manual sections, see +.Sx MANUAL STRUCTURE . +These sections should be used unless it's absolutely necessary that +custom sections be used. +.Pp +Section names should be unique so that they may be keyed by +.Ic \&Sx . +Although this macro is parsed, it should not consist of child node or it +may not be linked with +.Ic \&Sx . +.Pp +See also +.Ic \&Pp , +.Ic \&Ss , +and +.Ic \&Sx . +.Tg Sm +.It Ic \&Sm Op Cm on | off +Switches the spacing mode for output generated from macros. +.Pp +By default, spacing is +.Cm on . +When switched +.Cm off , +no white space is inserted between macro arguments and between the +output generated from adjacent macros, but text lines +still get normal spacing between words and sentences. +.Pp +When called without an argument, the +.Ic \&Sm +macro toggles the spacing mode. +Using this is not recommended because it makes the code harder to read. +.It Ic \&So Ar block +Multi-line version of +.Ic \&Sq . +.Tg Sq +.It Ic \&Sq Ar line +Encloses its arguments in +.Sq typewriter +single-quotes. +.Pp +See also +.Ic \&Dq , +.Ic \&Qq , +and +.Ic \&So . +.Tg Ss +.It Ic \&Ss Ar Title line +Begin a new subsection. +Unlike with +.Ic \&Sh , +there is no convention for the naming of subsections. +Except +.Em DESCRIPTION , +the conventional sections described in +.Sx MANUAL STRUCTURE +rarely have subsections. +.Pp +Sub-section names should be unique so that they may be keyed by +.Ic \&Sx . +Although this macro is parsed, it should not consist of child node or it +may not be linked with +.Ic \&Sx . +.Pp +See also +.Ic \&Pp , +.Ic \&Sh , +and +.Ic \&Sx . +.Tg St +.It Ic \&St Fl Ns Ar abbreviation +Replace an abbreviation for a standard with the full form. +The following standards are recognised. +Where multiple lines are given without a blank line in between, +they all refer to the same standard, and using the first form +is recommended. +.Bl -tag -width 1n +.It C language standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-ansiC +.St -ansiC +.It \-ansiC-89 +.St -ansiC-89 +.It \-isoC +.St -isoC +.It \-isoC-90 +.St -isoC-90 +.br +The original C standard. +.Pp +.It \-isoC-amd1 +.St -isoC-amd1 +.Pp +.It \-isoC-tcor1 +.St -isoC-tcor1 +.Pp +.It \-isoC-tcor2 +.St -isoC-tcor2 +.Pp +.It \-isoC-99 +.St -isoC-99 +.br +Edition 2 of the C language standard. +.Pp +.It \-isoC-2011 +.St -isoC-2011 +.br +Edition 3 of the C language standard. +.Pp +.It \-isoC-2023 +.St -isoC-2023 +.br +Edition 5 of the C language standard. +.El +.It POSIX.1 before the Single UNIX Specification +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-p1003.1-88 +.St -p1003.1-88 +.It \-p1003.1 +.St -p1003.1 +.br +The original POSIX standard, based on ANSI C. +.Pp +.It \-p1003.1-90 +.St -p1003.1-90 +.It \-iso9945-1-90 +.St -iso9945-1-90 +.br +The first update of POSIX.1. +.Pp +.It \-p1003.1b-93 +.St -p1003.1b-93 +.It \-p1003.1b +.St -p1003.1b +.br +Real-time extensions. +.Pp +.It \-p1003.1c-95 +.St -p1003.1c-95 +.br +POSIX thread interfaces. +.Pp +.It \-p1003.1i-95 +.St -p1003.1i-95 +.br +Technical Corrigendum. +.Pp +.It \-p1003.1-96 +.St -p1003.1-96 +.It \-iso9945-1-96 +.St -iso9945-1-96 +.br +Includes POSIX.1-1990, 1b, 1c, and 1i. +.El +.It X/Open Portability Guide version 4 and related standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-xpg3 +.St -xpg3 +.br +An XPG4 precursor, published in 1989. +.Pp +.It \-p1003.2 +.St -p1003.2 +.It \-p1003.2-92 +.St -p1003.2-92 +.It \-iso9945-2-93 +.St -iso9945-2-93 +.br +An XCU4 precursor. +.Pp +.It \-p1003.2a-92 +.St -p1003.2a-92 +.br +Updates to POSIX.2. +.Pp +.It \-xpg4 +.St -xpg4 +.br +Based on POSIX.1 and POSIX.2, published in 1992. +.El +.It Single UNIX Specification version 1 and related standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-susv1 +.St -susv1 +.It \-xpg4.2 +.St -xpg4.2 +.br +This standard was published in 1994. +It was used as the basis for UNIX 95 certification. +The following three refer to parts of it. +.Pp +.It \-xsh4.2 +.St -xsh4.2 +.Pp +.It \-xcurses4.2 +.St -xcurses4.2 +.Pp +.It \-p1003.1g-2000 +.St -p1003.1g-2000 +.br +Networking APIs, including sockets. +.Pp +.It \-svid4 +.St -svid4 , +.br +Published in 1995. +.El +.It Single UNIX Specification version 2 and related standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-susv2 +.St -susv2 +This Standard was published in 1997 +and is also called X/Open Portability Guide version 5. +It was used as the basis for UNIX 98 certification. +The following refer to parts of it. +.Pp +.It \-xbd5 +.St -xbd5 +.Pp +.It \-xsh5 +.St -xsh5 +.Pp +.It \-xcu5 +.St -xcu5 +.Pp +.It \-xns5 +.St -xns5 +.It \-xns5.2 +.St -xns5.2 +.El +.It Single UNIX Specification version 3 +.Pp +.Bl -tag -width "-p1003.1-2001" -compact +.It \-p1003.1-2001 +.St -p1003.1-2001 +.It \-susv3 +.St -susv3 +.br +This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j. +It is also called X/Open Portability Guide version 6. +It is used as the basis for UNIX 03 certification. +.Pp +.It \-p1003.1-2004 +.St -p1003.1-2004 +.br +The second and last Technical Corrigendum. +.El +.It POSIX issues 7 and 8 +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-p1003.1-2008 +.St -p1003.1-2008 +.It \-susv4 +.St -susv4 +.br +This standard is based on C99. +It is also called the +Open Group Standard Base Specifications, Issue 7. +.El +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-p1003.1-2024 +.St -p1003.1-2024 +.br +This standard is based on C17. +It is also called the +Open Group Standard Base Specifications, Issue 8. +.El +.It Other standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-ieee754 +.St -ieee754 +.br +Floating-point arithmetic. +.Pp +.It \-iso8601 +.St -iso8601 +.br +Representation of dates and times, published in 1988. +.Pp +.It \-iso8802-3 +.St -iso8802-3 +.br +Ethernet local area networks. +.Pp +.It \-ieee1275-94 +.St -ieee1275-94 +.El +.El +.Tg Sx +.It Ic \&Sx Ar Title line +Reference a section or subsection in the same manual page. +The referenced section or subsection name must be identical to the +enclosed argument, including whitespace. +.Pp +Examples: +.Dl \&.Sx MANUAL STRUCTURE +.Pp +See also +.Ic \&Sh +and +.Ic \&Ss . +.Tg Sy +.It Ic \&Sy Ar word ... +Request a boldface font. +.Pp +This is most often used to indicate importance or seriousness (not to be +confused with stress emphasis, see +.Ic \&Em ) . +When none of the semantic macros fit, it is also adequate for syntax +elements that have to be given or that appear verbatim. +.Pp +Examples: +.Bd -literal -compact -offset indent +\&.Sy Warning : +If +\&.Sy s +appears in the owner permissions, set-user-ID mode is set. +This utility replaces the former +\&.Sy dumpdir +program. +.Ed +.Pp +See also +.Ic \&Em , +.Ic \&No , +and +.Ic \&Ql . +.Tg Ta +.It Ic \&Ta +Table cell separator in +.Ic \&Bl Fl column +lists; can only be used below +.Ic \&It . +.Tg Tg +.It Ic \&Tg Op Ar term +Announce that the next input line starts a definition of the +.Ar term . +This macro must appear alone on its own input line. +The argument defaults to the first argument of the first macro +on the next line. +The argument may not contain whitespace characters, not even when it is quoted. +This macro is a +.Xr mandoc 1 +extension and is typically ignored by other formatters. +.Pp +When viewing terminal output with +.Xr less 1 , +the interactive +.Ic :t +command can be used to go to the definition of the +.Ar term +as described for the +.Ev MANPAGER +variable in +.Xr man 1 ; +when producing HTML output, a fragment identifier +.Pq Ic id No attribute +is generated, to be used for deep linking to this place of the document. +.Pp +In most cases, adding a +.Ic \&Tg +macro would be redundant because +.Xr mandoc 1 +is able to automatically tag most definitions. +This macro is intended for cases where automatic tagging of a +.Ar term +is unsatisfactory, for example if a definition is not tagged +automatically (false negative) or if places are tagged that do +not define the +.Ar term +(false positives). +When there is at least one +.Ic \&Tg +macro for a +.Ar term , +no other places are automatically marked as definitions of that +.Ar term . +.It Ic \&Tn Ar word ... +Supported only for compatibility, do not use this in new manuals. +Even though the macro name +.Pq Dq tradename +suggests a semantic function, historic usage is inconsistent, mostly +using it as a presentation-level macro to request a small caps font. +.It Ic \&Ud +Supported only for compatibility, do not use this in new manuals. +Prints out +.Dq currently under development. +.It Ic \&Ux +Supported only for compatibility, do not use this in new manuals. +Prints out +.Dq Ux . +.Tg Va +.It Ic \&Va Oo Ar type Oc Ar identifier ... +A variable name. +.Pp +Examples: +.Dl \&.Va foo +.Dl \&.Va const char *bar ; +.Pp +For function arguments and parameters, use +.Ic \&Fa +instead. +For declarations of global variables in the +.Em SYNOPSIS +section, use +.Ic \&Vt . +.Tg Vt +.It Ic \&Vt Ar type Op Ar identifier +A variable type. +.Pp +This is also used for indicating global variables in the +.Em SYNOPSIS +section, in which case a variable name is also specified. +Note that it accepts +.Sx Block partial-implicit +syntax when invoked as the first macro on an input line in the +.Em SYNOPSIS +section, else it accepts ordinary +.Sx In-line +syntax. +In the former case, this macro starts a new output line, +and a blank line is inserted in front if there is a preceding +function definition or include directive. +.Pp +Examples: +.Dl \&.Vt unsigned char +.Dl \&.Vt extern const char * const sys_signame[] \&; +.Pp +For parameters in function prototypes, use +.Ic \&Fa +instead, for function return types +.Ic \&Ft , +and for variable names outside the +.Em SYNOPSIS +section +.Ic \&Va , +even when including a type with the name. +See also +.Sx MANUAL STRUCTURE . +.It Ic \&Xc +Close a scope opened by +.Ic \&Xo . +.It Ic \&Xo Ar block +Extend the header of an +.Ic \&It +macro or the body of a partial-implicit block macro +beyond the end of the input line. +This macro originally existed to work around the 9-argument limit +of historic +.Xr roff 7 . +.Tg Xr +.It Ic \&Xr Ar name section +Link to another manual +.Pq Qq cross-reference . +.Pp +Cross reference the +.Ar name +and +.Ar section +number of another man page. +.Pp +Examples: +.Dl \&.Xr mandoc 1 +.Dl \&.Xr mandoc 1 \&; +.Dl \&.Xr mandoc 1 \&Ns s behaviour +.El +.Sh MACRO SYNTAX +The syntax of a macro depends on its classification. +In this section, +.Sq \-arg +refers to macro arguments, which may be followed by zero or more +.Sq parm +parameters; +.Sq \&Yo +opens the scope of a macro; and if specified, +.Sq \&Yc +closes it out. +.Pp +The +.Em Callable +column indicates that the macro may also be called by passing its name +as an argument to another macro. +For example, +.Sq \&.Op \&Fl O \&Ar file +produces +.Sq Op Fl O Ar file . +To prevent a macro call and render the macro name literally, +escape it by prepending a zero-width space, +.Sq \e& . +For example, +.Sq \&Op \e&Fl O +produces +.Sq Op \&Fl O . +If a macro is not callable but its name appears as an argument +to another macro, it is interpreted as opaque text. +For example, +.Sq \&.Fl \&Sh +produces +.Sq Fl \&Sh . +.Pp +The +.Em Parsed +column indicates whether the macro may call other macros by receiving +their names as arguments. +If a macro is not parsed but the name of another macro appears +as an argument, it is interpreted as opaque text. +.Pp +The +.Em Scope +column, if applicable, describes closure rules. +.Ss Block full-explicit +Multi-line scope closed by an explicit closing macro. +All macros contains bodies; only +.Ic \&Bf +and +.Pq optionally +.Ic \&Bl +contain a head. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB +\&.Yc +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&Bd Ta \&No Ta \&No Ta closed by Ic \&Ed +.It Ic \&Bf Ta \&No Ta \&No Ta closed by Ic \&Ef +.It Ic \&Bk Ta \&No Ta \&No Ta closed by Ic \&Ek +.It Ic \&Bl Ta \&No Ta \&No Ta closed by Ic \&El +.It Ic \&Ed Ta \&No Ta \&No Ta opened by Ic \&Bd +.It Ic \&Ef Ta \&No Ta \&No Ta opened by Ic \&Bf +.It Ic \&Ek Ta \&No Ta \&No Ta opened by Ic \&Bk +.It Ic \&El Ta \&No Ta \&No Ta opened by Ic \&Bl +.El +.Ss Block full-implicit +Multi-line scope closed by end-of-file or implicitly by another macro. +All macros have bodies; some +.Po +.Ic \&It Fl bullet , +.Fl hyphen , +.Fl dash , +.Fl enum , +.Fl item +.Pc +don't have heads; only one +.Po +.Ic \&It +in +.Ic \&Bl Fl column +.Pc +has multiple heads. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB +\(lBbody...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&It Ta \&No Ta Yes Ta closed by Ic \&It , Ic \&El +.It Ic \&Nd Ta \&No Ta \&No Ta closed by Ic \&Sh +.It Ic \&Nm Ta \&No Ta Yes Ta closed by Ic \&Nm , Ic \&Sh , Ic \&Ss +.It Ic \&Sh Ta \&No Ta Yes Ta closed by Ic \&Sh +.It Ic \&Ss Ta \&No Ta Yes Ta closed by Ic \&Sh , Ic \&Ss +.El +.Pp +Note that the +.Ic \&Nm +macro is a +.Sx Block full-implicit +macro only when invoked as the first macro +in a +.Em SYNOPSIS +section line, else it is +.Sx In-line . +.Ss Block partial-explicit +Like block full-explicit, but also with single-line scope. +Each has at least a body and, in limited circumstances, a head +.Po +.Ic \&Fo , +.Ic \&Eo +.Pc +and/or tail +.Pq Ic \&Ec . +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB +\&.Yc \(lBtail...\(rB + +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ +\(lBbody...\(rB \&Yc \(lBtail...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&Ac Ta Yes Ta Yes Ta opened by Ic \&Ao +.It Ic \&Ao Ta Yes Ta Yes Ta closed by Ic \&Ac +.It Ic \&Bc Ta Yes Ta Yes Ta closed by Ic \&Bo +.It Ic \&Bo Ta Yes Ta Yes Ta opened by Ic \&Bc +.It Ic \&Brc Ta Yes Ta Yes Ta opened by Ic \&Bro +.It Ic \&Bro Ta Yes Ta Yes Ta closed by Ic \&Brc +.It Ic \&Dc Ta Yes Ta Yes Ta opened by Ic \&Do +.It Ic \&Do Ta Yes Ta Yes Ta closed by Ic \&Dc +.It Ic \&Ec Ta Yes Ta Yes Ta opened by Ic \&Eo +.It Ic \&Eo Ta Yes Ta Yes Ta closed by Ic \&Ec +.It Ic \&Fc Ta Yes Ta Yes Ta opened by Ic \&Fo +.It Ic \&Fo Ta \&No Ta \&No Ta closed by Ic \&Fc +.It Ic \&Oc Ta Yes Ta Yes Ta closed by Ic \&Oo +.It Ic \&Oo Ta Yes Ta Yes Ta opened by Ic \&Oc +.It Ic \&Pc Ta Yes Ta Yes Ta closed by Ic \&Po +.It Ic \&Po Ta Yes Ta Yes Ta opened by Ic \&Pc +.It Ic \&Qc Ta Yes Ta Yes Ta opened by Ic \&Oo +.It Ic \&Qo Ta Yes Ta Yes Ta closed by Ic \&Oc +.It Ic \&Re Ta \&No Ta \&No Ta opened by Ic \&Rs +.It Ic \&Rs Ta \&No Ta \&No Ta closed by Ic \&Re +.It Ic \&Sc Ta Yes Ta Yes Ta opened by Ic \&So +.It Ic \&So Ta Yes Ta Yes Ta closed by Ic \&Sc +.It Ic \&Xc Ta Yes Ta Yes Ta opened by Ic \&Xo +.It Ic \&Xo Ta Yes Ta Yes Ta closed by Ic \&Xc +.El +.Ss Block partial-implicit +Like block full-implicit, but with single-line scope closed by the +end of the line. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed +.It Ic \&Aq Ta Yes Ta Yes +.It Ic \&Bq Ta Yes Ta Yes +.It Ic \&Brq Ta Yes Ta Yes +.It Ic \&D1 Ta \&No Ta \&Yes +.It Ic \&Dl Ta \&No Ta Yes +.It Ic \&Dq Ta Yes Ta Yes +.It Ic \&En Ta Yes Ta Yes +.It Ic \&Op Ta Yes Ta Yes +.It Ic \&Pq Ta Yes Ta Yes +.It Ic \&Ql Ta Yes Ta Yes +.It Ic \&Qq Ta Yes Ta Yes +.It Ic \&Sq Ta Yes Ta Yes +.It Ic \&Vt Ta Yes Ta Yes +.El +.Pp +Note that the +.Ic \&Vt +macro is a +.Sx Block partial-implicit +only when invoked as the first macro +in a +.Em SYNOPSIS +section line, else it is +.Sx In-line . +.Ss Special block macro +The +.Ic \&Ta +macro can only be used below +.Ic \&It +in +.Ic \&Bl Fl column +lists. +It delimits blocks representing table cells; +these blocks have bodies, but no heads. +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&Ta Ta Yes Ta Yes Ta closed by Ic \&Ta , Ic \&It +.El +.Ss In-line +Closed by the end of the line, fixed argument lengths, +and/or subsequent macros. +In-line macros have only text children. +If a number (or inequality) of arguments is +.Pq n , +then the macro accepts an arbitrary number of arguments. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB + +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... + +\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments +.It Ic \&%A Ta \&No Ta \&No Ta >0 +.It Ic \&%B Ta \&No Ta \&No Ta >0 +.It Ic \&%C Ta \&No Ta \&No Ta >0 +.It Ic \&%D Ta \&No Ta \&No Ta >0 +.It Ic \&%I Ta \&No Ta \&No Ta >0 +.It Ic \&%J Ta \&No Ta \&No Ta >0 +.It Ic \&%N Ta \&No Ta \&No Ta >0 +.It Ic \&%O Ta \&No Ta \&No Ta >0 +.It Ic \&%P Ta \&No Ta \&No Ta >0 +.It Ic \&%Q Ta \&No Ta \&No Ta >0 +.It Ic \&%R Ta \&No Ta \&No Ta >0 +.It Ic \&%T Ta \&No Ta \&No Ta >0 +.It Ic \&%U Ta \&No Ta \&No Ta >0 +.It Ic \&%V Ta \&No Ta \&No Ta >0 +.It Ic \&Ad Ta Yes Ta Yes Ta >0 +.It Ic \&An Ta Yes Ta Yes Ta >0 +.It Ic \&Ap Ta Yes Ta Yes Ta 0 +.It Ic \&Ar Ta Yes Ta Yes Ta n +.It Ic \&At Ta Yes Ta Yes Ta 1 +.It Ic \&Bsx Ta Yes Ta Yes Ta n +.It Ic \&Bt Ta \&No Ta \&No Ta 0 +.It Ic \&Bx Ta Yes Ta Yes Ta n +.It Ic \&Cd Ta Yes Ta Yes Ta >0 +.It Ic \&Cm Ta Yes Ta Yes Ta >0 +.It Ic \&Db Ta \&No Ta \&No Ta 1 +.It Ic \&Dd Ta \&No Ta \&No Ta n +.It Ic \&Dt Ta \&No Ta \&No Ta n +.It Ic \&Dv Ta Yes Ta Yes Ta >0 +.It Ic \&Dx Ta Yes Ta Yes Ta n +.It Ic \&Em Ta Yes Ta Yes Ta >0 +.It Ic \&Er Ta Yes Ta Yes Ta >0 +.It Ic \&Es Ta Yes Ta Yes Ta 2 +.It Ic \&Ev Ta Yes Ta Yes Ta >0 +.It Ic \&Ex Ta \&No Ta \&No Ta n +.It Ic \&Fa Ta Yes Ta Yes Ta >0 +.It Ic \&Fd Ta \&No Ta \&No Ta >0 +.It Ic \&Fl Ta Yes Ta Yes Ta n +.It Ic \&Fn Ta Yes Ta Yes Ta >0 +.It Ic \&Fr Ta Yes Ta Yes Ta >0 +.It Ic \&Ft Ta Yes Ta Yes Ta >0 +.It Ic \&Fx Ta Yes Ta Yes Ta n +.It Ic \&Hf Ta \&No Ta \&No Ta n +.It Ic \&Ic Ta Yes Ta Yes Ta >0 +.It Ic \&In Ta \&No Ta \&No Ta 1 +.It Ic \&Lb Ta \&No Ta \&No Ta 1 +.It Ic \&Li Ta Yes Ta Yes Ta >0 +.It Ic \&Lk Ta Yes Ta Yes Ta >0 +.It Ic \&Lp Ta \&No Ta \&No Ta 0 +.It Ic \&Ms Ta Yes Ta Yes Ta >0 +.It Ic \&Mt Ta Yes Ta Yes Ta >0 +.It Ic \&Nm Ta Yes Ta Yes Ta n +.It Ic \&No Ta Yes Ta Yes Ta >0 +.It Ic \&Ns Ta Yes Ta Yes Ta 0 +.It Ic \&Nx Ta Yes Ta Yes Ta n +.It Ic \&Os Ta \&No Ta \&No Ta n +.It Ic \&Ot Ta Yes Ta Yes Ta >0 +.It Ic \&Ox Ta Yes Ta Yes Ta n +.It Ic \&Pa Ta Yes Ta Yes Ta n +.It Ic \&Pf Ta Yes Ta Yes Ta 1 +.It Ic \&Pp Ta \&No Ta \&No Ta 0 +.It Ic \&Rv Ta \&No Ta \&No Ta n +.It Ic \&Sm Ta \&No Ta \&No Ta <2 +.It Ic \&St Ta \&No Ta Yes Ta 1 +.It Ic \&Sx Ta Yes Ta Yes Ta >0 +.It Ic \&Sy Ta Yes Ta Yes Ta >0 +.It Ic \&Tg Ta \&No Ta \&No Ta <2 +.It Ic \&Tn Ta Yes Ta Yes Ta >0 +.It Ic \&Ud Ta \&No Ta \&No Ta 0 +.It Ic \&Ux Ta Yes Ta Yes Ta n +.It Ic \&Va Ta Yes Ta Yes Ta n +.It Ic \&Vt Ta Yes Ta Yes Ta >0 +.It Ic \&Xr Ta Yes Ta Yes Ta 2 +.El +.Ss Delimiters +When a macro argument consists of one single input character +considered as a delimiter, the argument gets special handling. +This does not apply when delimiters appear in arguments containing +more than one character. +Consequently, to prevent special handling and just handle it +like any other argument, a delimiter can be escaped by prepending +a zero-width space +.Pq Sq \e& . +In text lines, delimiters never need escaping, but may be used +as normal punctuation. +.Pp +For many macros, when the leading arguments are opening delimiters, +these delimiters are put before the macro scope, +and when the trailing arguments are closing delimiters, +these delimiters are put after the macro scope. +Spacing is suppressed after opening delimiters +and before closing delimiters. +For example, +.Pp +.D1 Pf \. \&Aq "( [ word ] ) ." +.Pp +renders as: +.Pp +.D1 Aq ( [ word ] ) . +.Pp +Opening delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&( +left parenthesis +.It \&[ +left bracket +.El +.Pp +Closing delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&. +period +.It \&, +comma +.It \&: +colon +.It \&; +semicolon +.It \&) +right parenthesis +.It \&] +right bracket +.It \&? +question mark +.It \&! +exclamation mark +.El +.Pp +Note that even a period preceded by a backslash +.Pq Sq \e.\& +gets this special handling; use +.Sq \e&.\& +to prevent that. +.Pp +Many in-line macros interrupt their scope when they encounter +delimiters, and resume their scope when more arguments follow that +are not delimiters. +For example, +.Pp +.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" +.Pp +renders as: +.Pp +.D1 Fl a ( b | c \*(Ba d ) e +.Pp +This applies to both opening and closing delimiters, +and also to the middle delimiter, which does not suppress spacing: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&| +vertical bar +.El +.Pp +As a special case, the predefined string \e*(Ba is handled and rendered +in the same way as a plain +.Sq \&| +character. +Using this predefined string is not recommended in new manuals. +.Pp +Appending a zero-width space +.Pq Sq \e& +to the end of an input line is also useful to prevent the interpretation +of a trailing period, exclamation or question mark as the end of a +sentence, for example when an abbreviation happens to occur +at the end of a text or macro input line. +.Ss Font handling +In +.Nm +documents, usage of semantic markup is recommended in order to have +proper fonts automatically selected; only when no fitting semantic markup +is available, consider falling back to +.Sx Physical markup +macros. +Whenever any +.Nm +macro switches the +.Xr roff 7 +font mode, it will automatically restore the previous font when exiting +its scope. +Manually switching the font using the +.Xr roff 7 +.Ql \ef +font escape sequences is never required. +.Sh COMPATIBILITY +This section provides an incomplete list of compatibility issues +between mandoc and GNU troff +.Pq Qq groff . +.Pp +The following problematic behaviour is found in groff: +.Pp +.Bl -dash -compact +.It +.Ic \&Pa +does not format its arguments when used in the FILES section under +certain list types. +.It +.Ic \&Ta +can only be called by other macros, but not at the beginning of a line. +.It +.Sq \ef +.Pq font face +and +.Sq \eF +.Pq font family face +.Sx Text Decoration +escapes behave irregularly when specified within line-macro scopes. +.It +Negative scaling units return to prior lines. +Instead, mandoc truncates them to zero. +.El +.Pp +The following features are unimplemented in mandoc: +.Pp +.Bl -dash -compact +.It +.Ic \&Bd Fl file Ar file +is unsupported for security reasons. +.It +.Ic \&Bd +.Fl filled +does not adjust the right margin, but is an alias for +.Ic \&Bd +.Fl ragged . +.It +.Ic \&Bd +.Fl literal +does not use a literal font, but is an alias for +.Ic \&Bd +.Fl unfilled . +.It +.Ic \&Bd +.Fl offset Cm center +and +.Fl offset Cm right +don't work. +Groff does not implement centered and flush-right rendering either, +but produces large indentations. +.El +.Sh SEE ALSO +.Xr man 1 , +.Xr mandoc 1 , +.Xr eqn 7 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr roff 7 , +.Xr tbl 7 +.Pp +The web page +.Lk https://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language" +provides a few tutorial-style pages for beginners, an extensive style +guide for advanced authors, and an alphabetic index helping to choose +the best macros for various kinds of content. +.Pp +The manual page +.Lk https://man.voidlinux.org/groff_mdoc "groff_mdoc(7)" +contained in the +.Dq groff +package documents exactly the same language in a somewhat different style. +.Sh HISTORY +The +.Nm +language first appeared as a troff macro package in +.Bx 4.4 . +It was later significantly updated by Werner Lemberg and Ruslan Ermilov +in groff-1.17. +The standalone implementation that is part of the +.Xr mandoc 1 +utility written by Kristaps Dzonsons appeared in +.Ox 4.6 . +.Sh AUTHORS +The +.Nm +reference was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . diff --git a/static/netbsd/man7/me.7 b/static/netbsd/man7/me.7 new file mode 100644 index 00000000..f1fccdc5 --- /dev/null +++ b/static/netbsd/man7/me.7 @@ -0,0 +1,315 @@ +.\" $NetBSD: me.7,v 1.11 2013/02/12 20:50:22 pgoyette Exp $ +.\" +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)me.7 8.1 (Berkeley) 6/5/93 +.\" +.hc % +.TH ME 7 "June 5, 1993" +.UC 3 +.SH NAME +me \- macros for formatting papers +.SH SYNOPSIS +.B "nroff \-me" +[ options ] +file ... +.br +.B "troff \-me" +[ options ] +file ... +.SH DESCRIPTION +This package of +.I nroff +and +.I troff +macro definitions provides a canned formatting +facility for technical papers in various formats. +When producing 2-column output on a terminal, filter +the output through +.IR col (1). +.PP +The macro requests are defined below. +Many +.I nroff +and +.I troff +requests are unsafe in conjunction with +this package, however, these requests may be used with +impunity after the first .pp: +.nf +.IP +.ta \w'.sz +n 'u +\&.bp begin new page +\&.br break output line here +\&.sp n insert n spacing lines +\&.ls n (line spacing) n=1 single, n=2 double space +\&.na no alignment of right margin +\&.ce n center next n lines +\&.ul n underline next n lines +\&.sz +n add n to point size +.fi +.PP +Output of the +.I eqn, +.I neqn, +.I refer, +and +.IR tbl (1) +preprocessors +for equations and tables is acceptable as input. +.SH FILES +/usr/share/tmac/tmac.e +.br +/usr/share/me/* +.SH "SEE ALSO" +eqn(1), troff(1), refer(1), tbl(1) +.br +\-me Reference Manual, Eric P. Allman +.br +Writing Papers with Nroff Using \-me +.tr &. +.SH REQUESTS +In the following list, +\*(lqinitialization\*(rq +refers to the first .pp, .lp, .ip, .np, .sh, or .uh macro. +This list is incomplete; +see +.I "The \-me Reference Manual" +for interesting details. +.PP +.ta \w'.eh \'x\'y\'z\' 'u +\w'Initial 'u +\w'Cause 'u +.br +.di x + \ka +.br +.di +.in \nau +.ti 0 +Request Initial Cause Explanation +.ti 0 + Value Break +.br +.in \nau +.ti 0 +\&.(c - yes Begin centered block +.ti 0 +\&.(d - no Begin delayed text +.ti 0 +\&.(f - no Begin footnote +.ti 0 +\&.(l - yes Begin list +.ti 0 +\&.(q - yes Begin major quote +.ti 0 +\&.(x \fIx\fR - no Begin indexed item in index +.I x +.ti 0 +\&.(z - no Begin floating keep +.ti 0 +\&.)c - yes End centered block +.ti 0 +\&.)d - yes End delayed text +.ti 0 +\&.)f - yes End footnote +.ti 0 +\&.)l - yes End list +.ti 0 +\&.)q - yes End major quote +.ti 0 +\&.)x - yes End index item +.ti 0 +\&.)z - yes End floating keep +.ti 0 +\&.++ \fIm H\fR - no Define paper section. +.I m +defines the part of the paper, and can be +.B C +(chapter), +.B A +(appendix), +.B P +(preliminary, e.g., abstract, table of contents, etc.), +.B B +(bibliography), +.B RC +(chapters renumbered from page one each chapter), +or +.B RA +(appendix renumbered from page one). +.ti 0 +\&.+c \fIT\fR - yes Begin chapter (or appendix, etc., as +set by .++). +.I T +is the chapter title. +.ti 0 +\&.1c 1 yes One column format on a new page. +.ti 0 +\&.2c 1 yes Two column format. +.ti 0 +\&.EN - yes Space after equation +produced by +.I eqn +or +.IR neqn . +.ti 0 +\&.EQ \fIx y\fR - yes Precede equation; break out and +add space. +Equation number is +.IR y . +The optional argument \fIx\fR +may be +.I I +to indent equation (default), +.I L +to left-adjust the equation, or +.I C +to center the equation. +.ti 0 +\&.GE - yes End \fIgremlin\fP picture. +.ti 0 +\&.GS - yes Begin \fIgremlin\fP picture. +.ti 0 +\&.PE - yes End \fIpic\fP picture. +.ti 0 +\&.PS - yes Begin \fIpic\fP picture. +.ti 0 +\&.TE - yes End table. +.ti 0 +\&.TH - yes End heading section of table. +.ti 0 +\&.TS \fIx\fR - yes Begin table; if \fIx\fR is +.I H +table has repeated heading. +.ti 0 +\&.ac \fIA N\fR - no Set up for ACM style output. +.I A +is the Author's name(s), +.I N +is the total number of pages. +Must be given before the first initialization. +.ti 0 +\&.b \fIx\fR no no Print +.I x +in boldface; if no argument switch to boldface. +.ti 0 +\&.ba \fI+n\fR 0 yes Augments the base indent by +.I n. +This indent is used to set the indent on regular text +(like paragraphs). +.ti 0 +\&.bc no yes Begin new column +.ti 0 +\&.bi \fIx\fR no no Print +.I x +in bold italics (nofill only) +.ti 0 +\&.bu - yes Begin bulleted paragraph +.ti 0 +\&.bx \fIx\fR no no Print \fIx\fR in a box (nofill only). +.ti 0 +\&.ef \fI\'x\'y\'z\'\fR \'\'\'\' no Set even footer to x y z +.ti 0 +\&.eh \fI\'x\'y\'z\'\fR \'\'\'\' no Set even header to x y z +.ti 0 +\&.fo \fI\'x\'y\'z\'\fR \'\'\'\' no Set footer to x y z +.ti 0 +\&.hx - no Suppress headers and footers on next page. +.ti 0 +\&.he \fI\'x\'y\'z\'\fR \'\'\'\' no Set header to x y z +.ti 0 +\&.hl - yes Draw a horizontal line +.ti 0 +\&.i \fIx\fR no no Italicize +.I x; +if +.I x +missing, italic text follows. +.ti 0 +\&.ip \fIx y\fR no yes Start indented paragraph, +with hanging tag +.IR x . +Indentation is +.I y +ens (default 5). +.ti 0 +\&.lp yes yes Start left-blocked paragraph. +.ti 0 +\&.lo - no Read in a file of local macros of the +form +.BI \&.* x. +Must be given before initialization. +.ti 0 +\&.np 1 yes Start numbered paragraph. +.ti 0 +\&.of \fI\'x\'y\'z\'\fR \'\'\'\' no Set odd footer to x y z +.ti 0 +\&.oh \fI\'x\'y\'z\'\fR \'\'\'\' no Set odd header to x y z +.ti 0 +\&.pd - yes Print delayed text. +.ti 0 +\&.pp no yes Begin paragraph. +First line indented. +.ti 0 +\&.r yes no Roman text follows. +.ti 0 +\&.re - no Reset tabs to default values. +.ti 0 +\&.sc no no Read in a file of special characters +and diacritical marks. +Must be given before initialization. +.ti 0 +\&.sh \fIn x\fR - yes Section head follows, +font automatically bold. +.I n +is level of section, +.I x +is title of section. +.ti 0 +\&.sk no no Leave the next page blank. +Only one page is remembered ahead. +.ti 0 +\&.sm \fIx\fR - no Set +.I x +in a smaller pointsize. +.ti 0 +\&.sz \fI+n\fR 10p no Augment the point size by +.I n +points. +.ti 0 +\&.th no no Produce the paper in thesis format. +Must be given before initialization. +.ti 0 +\&.tp no yes Begin title page. +.ti 0 +\&.u \fIx\fR - no Underline argument (even in \fItroff\fR). +(Nofill only). +.ti 0 +\&.uh - yes Like .sh but unnumbered. +.ti 0 +\&.xp \fIx\fR - no Print index +.I x. diff --git a/static/netbsd/man7/migration_guide.7 b/static/netbsd/man7/migration_guide.7 new file mode 100644 index 00000000..3a95155f --- /dev/null +++ b/static/netbsd/man7/migration_guide.7 @@ -0,0 +1,2092 @@ +.\" $NetBSD: migration_guide.7,v 1.6 2025/04/16 15:23:17 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "MIGRATION_GUIDE 7" +.TH MIGRATION_GUIDE 7 2025-02-11 3.0.16 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +migration_guide \- OpenSSL migration guide +.SH SYNOPSIS +.IX Header "SYNOPSIS" +See the individual manual pages for details. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This guide details the changes required to migrate to new versions of OpenSSL. +Currently this covers OpenSSL 3.0. For earlier versions refer to +. +For an overview of some of the key concepts introduced in OpenSSL 3.0 see +\&\fBcrypto\fR\|(7). +.SH "OPENSSL 3.0" +.IX Header "OPENSSL 3.0" +.SS "Main Changes from OpenSSL 1.1.1" +.IX Subsection "Main Changes from OpenSSL 1.1.1" +\fIMajor Release\fR +.IX Subsection "Major Release" +.PP +OpenSSL 3.0 is a major release and consequently any application that currently +uses an older version of OpenSSL will at the very least need to be recompiled in +order to work with the new version. It is the intention that the large majority +of applications will work unchanged with OpenSSL 3.0 if those applications +previously worked with OpenSSL 1.1.1. However this is not guaranteed and some +changes may be required in some cases. Changes may also be required if +applications need to take advantage of some of the new features available in +OpenSSL 3.0 such as the availability of the FIPS module. +.PP +\fILicense Change\fR +.IX Subsection "License Change" +.PP +In previous versions, OpenSSL was licensed under the dual OpenSSL and SSLeay +licenses +(both licenses apply). From OpenSSL 3.0 this is replaced by the +Apache License v2 . +.PP +\fIProviders and FIPS support\fR +.IX Subsection "Providers and FIPS support" +.PP +One of the key changes from OpenSSL 1.1.1 is the introduction of the Provider +concept. Providers collect together and make available algorithm implementations. +With OpenSSL 3.0 it is possible to specify, either programmatically or via a +config file, which providers you want to use for any given application. +OpenSSL 3.0 comes with 5 different providers as standard. Over time third +parties may distribute additional providers that can be plugged into OpenSSL. +All algorithm implementations available via providers are accessed through the +"high level" APIs (for example those functions prefixed with \f(CW\*(C`EVP\*(C'\fR). They cannot +be accessed using the "Low Level APIs". +.PP +One of the standard providers available is the FIPS provider. This makes +available FIPS validated cryptographic algorithms. +The FIPS provider is disabled by default and needs to be enabled explicitly +at configuration time using the \f(CW\*(C`enable\-fips\*(C'\fR option. If it is enabled, +the FIPS provider gets built and installed in addition to the other standard +providers. No separate installation procedure is necessary. +There is however a dedicated \f(CW\*(C`install_fips\*(C'\fR make target, which serves the +special purpose of installing only the FIPS provider into an existing +OpenSSL installation. +.PP +Not all algorithms may be available for the application at a particular moment. +If the application code uses any digest or cipher algorithm via the EVP interface, +the application should verify the result of the \fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_EncryptInit_ex\fR\|(3), and \fBEVP_DigestInit\fR\|(3) functions. In case when +the requested algorithm is not available, these functions will fail. +.PP +See also "Legacy Algorithms" for information on the legacy provider. +.PP +See also "Completing the installation of the FIPS Module" and +"Using the FIPS Module in applications". +.PP +\fILow Level APIs\fR +.IX Subsection "Low Level APIs" +.PP +OpenSSL has historically provided two sets of APIs for invoking cryptographic +algorithms: the "high level" APIs (such as the \f(CW\*(C`EVP\*(C'\fR APIs) and the "low level" +APIs. The high level APIs are typically designed to work across all algorithm +types. The "low level" APIs are targeted at a specific algorithm implementation. +For example, the EVP APIs provide the functions \fBEVP_EncryptInit_ex\fR\|(3), +\&\fBEVP_EncryptUpdate\fR\|(3) and \fBEVP_EncryptFinal\fR\|(3) to perform symmetric +encryption. Those functions can be used with the algorithms AES, CHACHA, 3DES etc. +On the other hand, to do AES encryption using the low level APIs you would have +to call AES specific functions such as \fBAES_set_encrypt_key\fR\|(3), +\&\fBAES_encrypt\fR\|(3), and so on. The functions for 3DES are different. +Use of the low level APIs has been informally discouraged by the OpenSSL +development team for a long time. However in OpenSSL 3.0 this is made more +formal. All such low level APIs have been deprecated. You may still use them in +your applications, but you may start to see deprecation warnings during +compilation (dependent on compiler support for this). Deprecated APIs may be +removed from future versions of OpenSSL so you are strongly encouraged to update +your code to use the high level APIs instead. +.PP +This is described in more detail in "Deprecation of Low Level Functions" +.PP +\fILegacy Algorithms\fR +.IX Subsection "Legacy Algorithms" +.PP +Some cryptographic algorithms such as \fBMD2\fR and \fBDES\fR that were available via +the EVP APIs are now considered legacy and their use is strongly discouraged. +These legacy EVP algorithms are still available in OpenSSL 3.0 but not by +default. If you want to use them then you must load the legacy provider. +This can be as simple as a config file change, or can be done programmatically. +See \fBOSSL_PROVIDER\-legacy\fR\|(7) for a complete list of algorithms. +Applications using the EVP APIs to access these algorithms should instead use +more modern algorithms. If that is not possible then these applications +should ensure that the legacy provider has been loaded. This can be achieved +either programmatically or via configuration. See \fBcrypto\fR\|(7) man page for +more information about providers. +.PP +\fIEngines and "METHOD" APIs\fR +.IX Subsection "Engines and ""METHOD"" APIs" +.PP +The refactoring to support Providers conflicts internally with the APIs used to +support engines, including the ENGINE API and any function that creates or +modifies custom "METHODS" (for example \fBEVP_MD_meth_new\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3), \fBEVP_PKEY_meth_new\fR\|(3), \fBRSA_meth_new\fR\|(3), +\&\fBEC_KEY_METHOD_new\fR\|(3), etc.). These functions are being deprecated in +OpenSSL 3.0, and users of these APIs should know that their use can likely +bypass provider selection and configuration, with unintended consequences. +This is particularly relevant for applications written to use the OpenSSL 3.0 +FIPS module, as detailed below. Authors and maintainers of external engines are +strongly encouraged to refactor their code transforming engines into providers +using the new Provider API and avoiding deprecated methods. +.PP +\fISupport of legacy engines\fR +.IX Subsection "Support of legacy engines" +.PP +If openssl is not built without engine support or deprecated API support, engines +will still work. However, their applicability will be limited. +.PP +New algorithms provided via engines will still work. +.PP +Engine-backed keys can be loaded via custom \fBOSSL_STORE\fR implementation. +In this case the \fBEVP_PKEY\fR objects created via \fBENGINE_load_private_key\fR\|(3) +will be considered legacy and will continue to work. +.PP +To ensure the future compatibility, the engines should be turned to providers. +To prefer the provider-based hardware offload, you can specify the default +properties to prefer your provider. +.PP +Setting engine-based or application-based default low-level crypto method such +as \fBRSA_METHOD\fR or \fBEC_KEY_METHOD\fR is still possible and keys inside the +default provider will use the engine-based implementation for the crypto +operations. However \fBEVP_PKEY\fRs created by decoding by using \fBOSSL_DECODER\fR, +\&\fBPEM_\fR or \fBd2i_\fR APIs will be provider-based. To create a fully legacy +\&\fBEVP_PKEY\fRs \fBEVP_PKEY_set1_RSA\fR\|(3), \fBEVP_PKEY_set1_EC_KEY\fR\|(3) or similar +functions must be used. +.PP +\fIVersioning Scheme\fR +.IX Subsection "Versioning Scheme" +.PP +The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release. The new +versioning scheme has this format: +.PP +MAJOR.MINOR.PATCH +.PP +For OpenSSL 1.1.1 and below, different patch levels were indicated by a letter +at the end of the release version number. This will no longer be used and +instead the patch level is indicated by the final number in the version. A +change in the second (MINOR) number indicates that new features may have been +added. OpenSSL versions with the same major number are API and ABI compatible. +If the major number changes then API and ABI compatibility is not guaranteed. +.PP +For more information, see \fBOpenSSL_version\fR\|(3). +.PP +\fIOther major new features\fR +.IX Subsection "Other major new features" +.PP +Certificate Management Protocol (CMP, RFC 4210) +.IX Subsection "Certificate Management Protocol (CMP, RFC 4210)" +.PP +This also covers CRMF (RFC 4211) and HTTP transfer (RFC 6712) +See \fBopenssl\-cmp\fR\|(1) and \fBOSSL_CMP_exec_certreq\fR\|(3) as starting points. +.PP +HTTP(S) client +.IX Subsection "HTTP(S) client" +.PP +A proper HTTP(S) client that supports GET and POST, redirection, plain and +ASN.1\-encoded contents, proxies, and timeouts. +.PP +Key Derivation Function API (EVP_KDF) +.IX Subsection "Key Derivation Function API (EVP_KDF)" +.PP +This simplifies the process of adding new KDF and PRF implementations. +.PP +Previously KDF algorithms had been shoe-horned into using the EVP_PKEY object +which was not a logical mapping. +Existing applications that use KDF algorithms using EVP_PKEY +(scrypt, TLS1 PRF and HKDF) may be slower as they use an EVP_KDF bridge +internally. +All new applications should use the new \fBEVP_KDF\fR\|(3) interface. +See also "Key Derivation Function (KDF)" in \fBOSSL_PROVIDER\-default\fR\|(7) and +"Key Derivation Function (KDF)" in \fBOSSL_PROVIDER\-FIPS\fR\|(7). +.PP +Message Authentication Code API (EVP_MAC) +.IX Subsection "Message Authentication Code API (EVP_MAC)" +.PP +This simplifies the process of adding MAC implementations. +.PP +This includes a generic EVP_PKEY to EVP_MAC bridge, to facilitate the continued +use of MACs through raw private keys in functionality such as +\&\fBEVP_DigestSign\fR\|(3) and \fBEVP_DigestVerify\fR\|(3). +.PP +All new applications should use the new \fBEVP_MAC\fR\|(3) interface. +See also "Message Authentication Code (MAC)" in \fBOSSL_PROVIDER\-default\fR\|(7) +and "Message Authentication Code (MAC)" in \fBOSSL_PROVIDER\-FIPS\fR\|(7). +.PP +Algorithm Fetching +.IX Subsection "Algorithm Fetching" +.PP +Using calls to convenience functions such as \fBEVP_sha256()\fR and \fBEVP_aes_256_gcm()\fR may +incur a performance penalty when using providers. +Retrieving algorithms from providers involves searching for an algorithm by name. +This is much slower than directly accessing a method table. +It is recommended to prefetch algorithms if an algorithm is used many times. +See "Performance" in \fBcrypto\fR\|(7), "Explicit fetching" in \fBcrypto\fR\|(7) and "Implicit fetching" in \fBcrypto\fR\|(7). +.PP +Support for Linux Kernel TLS +.IX Subsection "Support for Linux Kernel TLS" +.PP +In order to use KTLS, support for it must be compiled in using the +\&\f(CW\*(C`enable\-ktls\*(C'\fR configuration option. It must also be enabled at run time using +the \fBSSL_OP_ENABLE_KTLS\fR option. +.PP +New Algorithms +.IX Subsection "New Algorithms" +.IP \(bu 4 +KDF algorithms "SINGLE STEP" and "SSH" +.Sp +See \fBEVP_KDF\-SS\fR\|(7) and \fBEVP_KDF\-SSHKDF\fR\|(7) +.IP \(bu 4 +MAC Algorithms "GMAC" and "KMAC" +.Sp +See \fBEVP_MAC\-GMAC\fR\|(7) and \fBEVP_MAC\-KMAC\fR\|(7). +.IP \(bu 4 +KEM Algorithm "RSASVE" +.Sp +See \fBEVP_KEM\-RSA\fR\|(7). +.IP \(bu 4 +Cipher Algorithm "AES-SIV" +.Sp +See "SIV Mode" in \fBEVP_EncryptInit\fR\|(3). +.IP \(bu 4 +AES Key Wrap inverse ciphers supported by EVP layer. +.Sp +The inverse ciphers use AES decryption for wrapping, and AES encryption for +unwrapping. The algorithms are: "AES\-128\-WRAP\-INV", "AES\-192\-WRAP\-INV", +"AES\-256\-WRAP\-INV", "AES\-128\-WRAP\-PAD\-INV", "AES\-192\-WRAP\-PAD\-INV" and +"AES\-256\-WRAP\-PAD\-INV". +.IP \(bu 4 +CTS ciphers added to EVP layer. +.Sp +The algorithms are "AES\-128\-CBC\-CTS", "AES\-192\-CBC\-CTS", "AES\-256\-CBC\-CTS", +"CAMELLIA\-128\-CBC\-CTS", "CAMELLIA\-192\-CBC\-CTS" and "CAMELLIA\-256\-CBC\-CTS". +CS1, CS2 and CS3 variants are supported. +.PP +CMS and PKCS#7 updates +.IX Subsection "CMS and PKCS#7 updates" +.IP \(bu 4 +Added CAdES-BES signature verification support. +.IP \(bu 4 +Added CAdES-BES signature scheme and attributes support (RFC 5126) to CMS API. +.IP \(bu 4 +Added AuthEnvelopedData content type structure (RFC 5083) using AES_GCM +.Sp +This uses the AES-GCM parameter (RFC 5084) for the Cryptographic Message Syntax. +Its purpose is to support encryption and decryption of a digital envelope that +is both authenticated and encrypted using AES GCM mode. +.IP \(bu 4 +\&\fBPKCS7_get_octet_string\fR\|(3) and \fBPKCS7_type_is_other\fR\|(3) were made public. +.PP +PKCS#12 API updates +.IX Subsection "PKCS#12 API updates" +.PP +The default algorithms for pkcs12 creation with the \fBPKCS12_create()\fR function +were changed to more modern PBKDF2 and AES based algorithms. The default +MAC iteration count was changed to PKCS12_DEFAULT_ITER to make it equal +with the password-based encryption iteration count. The default digest +algorithm for the MAC computation was changed to SHA\-256. The pkcs12 +application now supports \-legacy option that restores the previous +default algorithms to support interoperability with legacy systems. +.PP +Added enhanced PKCS#12 APIs which accept a library context \fBOSSL_LIB_CTX\fR +and (where relevant) a property query. Other APIs which handle PKCS#7 and +PKCS#8 objects have also been enhanced where required. This includes: +.PP +\&\fBPKCS12_add_key_ex\fR\|(3), \fBPKCS12_add_safe_ex\fR\|(3), \fBPKCS12_add_safes_ex\fR\|(3), +\&\fBPKCS12_create_ex\fR\|(3), \fBPKCS12_decrypt_skey_ex\fR\|(3), \fBPKCS12_init_ex\fR\|(3), +\&\fBPKCS12_item_decrypt_d2i_ex\fR\|(3), \fBPKCS12_item_i2d_encrypt_ex\fR\|(3), +\&\fBPKCS12_key_gen_asc_ex\fR\|(3), \fBPKCS12_key_gen_uni_ex\fR\|(3), \fBPKCS12_key_gen_utf8_ex\fR\|(3), +\&\fBPKCS12_pack_p7encdata_ex\fR\|(3), \fBPKCS12_pbe_crypt_ex\fR\|(3), \fBPKCS12_PBE_keyivgen_ex\fR\|(3), +\&\fBPKCS12_SAFEBAG_create_pkcs8_encrypt_ex\fR\|(3), \fBPKCS5_pbe2_set_iv_ex\fR\|(3), +\&\fBPKCS5_pbe_set0_algor_ex\fR\|(3), \fBPKCS5_pbe_set_ex\fR\|(3), \fBPKCS5_pbkdf2_set_ex\fR\|(3), +\&\fBPKCS5_v2_PBE_keyivgen_ex\fR\|(3), \fBPKCS5_v2_scrypt_keyivgen_ex\fR\|(3), +\&\fBPKCS8_decrypt_ex\fR\|(3), \fBPKCS8_encrypt_ex\fR\|(3), \fBPKCS8_set0_pbe_ex\fR\|(3). +.PP +As part of this change the EVP_PBE_xxx APIs can also accept a library +context and property query and will call an extended version of the key/IV +derivation function which supports these parameters. This includes +\&\fBEVP_PBE_CipherInit_ex\fR\|(3), \fBEVP_PBE_find_ex\fR\|(3) and \fBEVP_PBE_scrypt_ex\fR\|(3). +.PP +PKCS#12 KDF versus FIPS +.IX Subsection "PKCS#12 KDF versus FIPS" +.PP +Unlike in 1.x.y, the PKCS12KDF algorithm used when a PKCS#12 structure +is created with a MAC that does not work with the FIPS provider as the PKCS12KDF +is not a FIPS approvable mechanism. +.PP +See \fBEVP_KDF\-PKCS12KDF\fR\|(7), \fBPKCS12_create\fR\|(3), \fBopenssl\-pkcs12\fR\|(1), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7). +.PP +Windows thread synchronization changes +.IX Subsection "Windows thread synchronization changes" +.PP +Windows thread synchronization uses read/write primitives (SRWLock) when +supported by the OS, otherwise CriticalSection continues to be used. +.PP +Trace API +.IX Subsection "Trace API" +.PP +A new generic trace API has been added which provides support for enabling +instrumentation through trace output. This feature is mainly intended as an aid +for developers and is disabled by default. To utilize it, OpenSSL needs to be +configured with the \f(CW\*(C`enable\-trace\*(C'\fR option. +.PP +If the tracing API is enabled, the application can activate trace output by +registering BIOs as trace channels for a number of tracing and debugging +categories. See \fBOSSL_trace_enabled\fR\|(3). +.PP +Key validation updates +.IX Subsection "Key validation updates" +.PP +\&\fBEVP_PKEY_public_check\fR\|(3) and \fBEVP_PKEY_param_check\fR\|(3) now work for +more key types. This includes RSA, DSA, ED25519, X25519, ED448 and X448. +Previously (in 1.1.1) they would return \-2. For key types that do not have +parameters then \fBEVP_PKEY_param_check\fR\|(3) will always return 1. +.PP +\fIOther notable deprecations and changes\fR +.IX Subsection "Other notable deprecations and changes" +.PP +The function code part of an OpenSSL error code is no longer relevant +.IX Subsection "The function code part of an OpenSSL error code is no longer relevant" +.PP +This code is now always set to zero. Related functions are deprecated. +.PP +STACK and HASH macros have been cleaned up +.IX Subsection "STACK and HASH macros have been cleaned up" +.PP +The type-safe wrappers are declared everywhere and implemented once. +See \fBDEFINE_STACK_OF\fR\|(3) and \fBDECLARE_LHASH_OF\fR\|(3). +.PP +The RAND_DRBG subsystem has been removed +.IX Subsection "The RAND_DRBG subsystem has been removed" +.PP +The new \fBEVP_RAND\fR\|(3) is a partial replacement: the DRBG callback framework is +absent. The RAND_DRBG API did not fit well into the new provider concept as +implemented by EVP_RAND and EVP_RAND_CTX. +.PP +Removed \fBFIPS_mode()\fR and \fBFIPS_mode_set()\fR +.IX Subsection "Removed FIPS_mode() and FIPS_mode_set()" +.PP +These functions are legacy APIs that are not applicable to the new provider +model. Applications should instead use +\&\fBEVP_default_properties_is_fips_enabled\fR\|(3) and +\&\fBEVP_default_properties_enable_fips\fR\|(3). +.PP +Key generation is slower +.IX Subsection "Key generation is slower" +.PP +The Miller-Rabin test now uses 64 rounds, which is used for all prime generation, +including RSA key generation. This affects the time for larger keys sizes. +.PP +The default key generation method for the regular 2\-prime RSA keys was changed +to the FIPS186\-4 B.3.6 method (Generation of Probable Primes with Conditions +Based on Auxiliary Probable Primes). This method is slower than the original +method. +.PP +Change PBKDF2 to conform to SP800\-132 instead of the older PKCS5 RFC2898 +.IX Subsection "Change PBKDF2 to conform to SP800-132 instead of the older PKCS5 RFC2898" +.PP +This checks that the salt length is at least 128 bits, the derived key length is +at least 112 bits, and that the iteration count is at least 1000. +For backwards compatibility these checks are disabled by default in the +default provider, but are enabled by default in the FIPS provider. +.PP +To enable or disable the checks see \fBOSSL_KDF_PARAM_PKCS5\fR in +\&\fBEVP_KDF\-PBKDF2\fR\|(7). The parameter can be set using \fBEVP_KDF_derive\fR\|(3). +.PP +Enforce a minimum DH modulus size of 512 bits +.IX Subsection "Enforce a minimum DH modulus size of 512 bits" +.PP +Smaller sizes now result in an error. +.PP +SM2 key changes +.IX Subsection "SM2 key changes" +.PP +EC EVP_PKEYs with the SM2 curve have been reworked to automatically become +EVP_PKEY_SM2 rather than EVP_PKEY_EC. +.PP +Unlike in previous OpenSSL versions, this means that applications cannot +call \f(CW\*(C`EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)\*(C'\fR to get SM2 computations. +.PP +Parameter and key generation is also reworked to make it possible +to generate EVP_PKEY_SM2 parameters and keys. Applications must now generate +SM2 keys directly and must not create an EVP_PKEY_EC key first. It is no longer +possible to import an SM2 key with domain parameters other than the SM2 elliptic +curve ones. +.PP +Validation of SM2 keys has been separated from the validation of regular EC +keys, allowing to improve the SM2 validation process to reject loaded private +keys that are not conforming to the SM2 ISO standard. +In particular, a private scalar \fIk\fR outside the range \fI1 <= k < n\-1\fR is +now correctly rejected. +.PP +\fBEVP_PKEY_set_alias_type()\fR method has been removed +.IX Subsection "EVP_PKEY_set_alias_type() method has been removed" +.PP +This function made a \fBEVP_PKEY\fR object mutable after it had been set up. In +OpenSSL 3.0 it was decided that a provided key should not be able to change its +type, so this function has been removed. +.PP +Functions that return an internal key should be treated as read only +.IX Subsection "Functions that return an internal key should be treated as read only" +.PP +Functions such as \fBEVP_PKEY_get0_RSA\fR\|(3) behave slightly differently in +OpenSSL 3.0. Previously they returned a pointer to the low-level key used +internally by libcrypto. From OpenSSL 3.0 this key may now be held in a +provider. Calling these functions will only return a handle on the internal key +where the EVP_PKEY was constructed using this key in the first place, for +example using a function or macro such as \fBEVP_PKEY_assign_RSA\fR\|(3), +\&\fBEVP_PKEY_set1_RSA\fR\|(3), etc. +Where the EVP_PKEY holds a provider managed key, then these functions now return +a cached copy of the key. Changes to the internal provider key that take place +after the first time the cached key is accessed will not be reflected back in +the cached copy. Similarly any changes made to the cached copy by application +code will not be reflected back in the internal provider key. +.PP +For the above reasons the keys returned from these functions should typically be +treated as read-only. To emphasise this the value returned from +\&\fBEVP_PKEY_get0_RSA\fR\|(3), \fBEVP_PKEY_get0_DSA\fR\|(3), \fBEVP_PKEY_get0_EC_KEY\fR\|(3) and +\&\fBEVP_PKEY_get0_DH\fR\|(3) have been made const. This may break some existing code. +Applications broken by this change should be modified. The preferred solution is +to refactor the code to avoid the use of these deprecated functions. Failing +this the code should be modified to use a const pointer instead. +The \fBEVP_PKEY_get1_RSA\fR\|(3), \fBEVP_PKEY_get1_DSA\fR\|(3), \fBEVP_PKEY_get1_EC_KEY\fR\|(3) +and \fBEVP_PKEY_get1_DH\fR\|(3) functions continue to return a non-const pointer to +enable them to be "freed". However they should also be treated as read-only. +.PP +The public key check has moved from \fBEVP_PKEY_derive()\fR to \fBEVP_PKEY_derive_set_peer()\fR +.IX Subsection "The public key check has moved from EVP_PKEY_derive() to EVP_PKEY_derive_set_peer()" +.PP +This may mean result in an error in \fBEVP_PKEY_derive_set_peer\fR\|(3) rather than +during \fBEVP_PKEY_derive\fR\|(3). +To disable this check use EVP_PKEY_derive_set_peer_ex(dh, peer, 0). +.PP +The print format has cosmetic changes for some functions +.IX Subsection "The print format has cosmetic changes for some functions" +.PP +The output from numerous "printing" functions such as \fBX509_signature_print\fR\|(3), +\&\fBX509_print_ex\fR\|(3), \fBX509_CRL_print_ex\fR\|(3), and other similar functions has been +amended such that there may be cosmetic differences between the output +observed in 1.1.1 and 3.0. This also applies to the \fB\-text\fR output from the +\&\fBopenssl x509\fR and \fBopenssl crl\fR applications. +.PP +Interactive mode from the \fBopenssl\fR program has been removed +.IX Subsection "Interactive mode from the openssl program has been removed" +.PP +From now on, running it without arguments is equivalent to \fBopenssl help\fR. +.PP +The error return values from some control calls (ctrl) have changed +.IX Subsection "The error return values from some control calls (ctrl) have changed" +.PP +One significant change is that controls which used to return \-2 for +invalid inputs, now return \-1 indicating a generic error condition instead. +.PP +DH and DHX key types have different settable parameters +.IX Subsection "DH and DHX key types have different settable parameters" +.PP +Previously (in 1.1.1) these conflicting parameters were allowed, but will now +result in errors. See \fBEVP_PKEY\-DH\fR\|(7) for further details. This affects the +behaviour of \fBopenssl\-genpkey\fR\|(1) for DH parameter generation. +.PP +\fBEVP_CIPHER_CTX_set_flags()\fR ordering change +.IX Subsection "EVP_CIPHER_CTX_set_flags() ordering change" +.PP +If using a cipher from a provider the \fBEVP_CIPH_FLAG_LENGTH_BITS\fR flag can only +be set \fBafter\fR the cipher has been assigned to the cipher context. +See "FLAGS" in \fBEVP_EncryptInit\fR\|(3) for more information. +.PP +Validation of operation context parameters +.IX Subsection "Validation of operation context parameters" +.PP +Due to move of the implementation of cryptographic operations to the +providers, validation of various operation parameters can be postponed until +the actual operation is executed where previously it happened immediately +when an operation parameter was set. +.PP +For example when setting an unsupported curve with +\&\fBEVP_PKEY_CTX_set_ec_paramgen_curve_nid()\fR this function call will not fail +but later keygen operations with the EVP_PKEY_CTX will fail. +.PP +Removal of function code from the error codes +.IX Subsection "Removal of function code from the error codes" +.PP +The function code part of the error code is now always set to 0. For that +reason the \fBERR_GET_FUNC()\fR macro was removed. Applications must resolve +the error codes only using the library number and the reason code. +.PP +ChaCha20\-Poly1305 cipher does not allow a truncated IV length to be used +.IX Subsection "ChaCha20-Poly1305 cipher does not allow a truncated IV length to be used" +.PP +In OpenSSL 3.0 setting the IV length to any value other than 12 will result in an +error. +Prior to OpenSSL 3.0 the ivlen could be smaller that the required 12 byte length, +using EVP_CIPHER_CTX_ctrl(ctx, EVP_CRTL_AEAD_SET_IVLEN, ivlen, NULL). This resulted +in an IV that had leading zero padding. +.SS "Installation and Compilation" +.IX Subsection "Installation and Compilation" +Please refer to the INSTALL.md file in the top of the distribution for +instructions on how to build and install OpenSSL 3.0. Please also refer to the +various platform specific NOTES files for your specific platform. +.SS "Upgrading from OpenSSL 1.1.1" +.IX Subsection "Upgrading from OpenSSL 1.1.1" +Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively straight +forward in most cases. The most likely area where you will encounter problems +is if you have used low level APIs in your code (as discussed above). In that +case you are likely to start seeing deprecation warnings when compiling your +application. If this happens you have 3 options: +.IP 1. 4 +Ignore the warnings. They are just warnings. The deprecated functions are still present and you may still use them. However be aware that they may be removed from a future version of OpenSSL. +.IP 2. 4 +Suppress the warnings. Refer to your compiler documentation on how to do this. +.IP 3. 4 +Remove your usage of the low level APIs. In this case you will need to rewrite your code to use the high level APIs instead +.PP +\fIError code changes\fR +.IX Subsection "Error code changes" +.PP +As OpenSSL 3.0 provides a brand new Encoder/Decoder mechanism for working with +widely used file formats, application code that checks for particular error +reason codes on key loading failures might need an update. +.PP +Password-protected keys may deserve special attention. If only some errors +are treated as an indicator that the user should be asked about the password again, +it's worth testing these scenarios and processing the newly relevant codes. +.PP +There may be more cases to treat specially, depending on the calling application code. +.SS "Upgrading from OpenSSL 1.0.2" +.IX Subsection "Upgrading from OpenSSL 1.0.2" +Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more +difficult. In addition to the issues discussed above in the section about +"Upgrading from OpenSSL 1.1.1", the main things to be aware of are: +.IP 1. 4 +The build and installation procedure has changed significantly. +.Sp +Check the file INSTALL.md in the top of the installation for instructions on how +to build and install OpenSSL for your platform. Also read the various NOTES +files in the same directory, as applicable for your platform. +.IP 2. 4 +Many structures have been made opaque in OpenSSL 3.0. +.Sp +The structure definitions have been removed from the public header files and +moved to internal header files. In practice this means that you can no longer +stack allocate some structures. Instead they must be heap allocated through some +function call (typically those function names have a \f(CW\*(C`_new\*(C'\fR suffix to them). +Additionally you must use "setter" or "getter" functions to access the fields +within those structures. +.Sp +For example code that previously looked like this: +.Sp +.Vb 1 +\& EVP_MD_CTX md_ctx; +\& +\& /* This line will now generate compiler errors */ +\& EVP_MD_CTX_init(&md_ctx); +.Ve +.Sp +The code needs to be amended to look like this: +.Sp +.Vb 1 +\& EVP_MD_CTX *md_ctx; +\& +\& md_ctx = EVP_MD_CTX_new(); +\& ... +\& ... +\& EVP_MD_CTX_free(md_ctx); +.Ve +.IP 3. 4 +Support for TLSv1.3 has been added. +.Sp +This has a number of implications for SSL/TLS applications. See the +TLS1.3 page for further details. +.PP +More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0 +can be found on the +OpenSSL 1.1.0 Changes page . +.PP +\fIUpgrading from the OpenSSL 2.0 FIPS Object Module\fR +.IX Subsection "Upgrading from the OpenSSL 2.0 FIPS Object Module" +.PP +The OpenSSL 2.0 FIPS Object Module was a separate download that had to be built +separately and then integrated into your main OpenSSL 1.0.2 build. +In OpenSSL 3.0 the FIPS support is fully integrated into the mainline version of +OpenSSL and is no longer a separate download. For further information see +"Completing the installation of the FIPS Module". +.PP +The function calls \fBFIPS_mode()\fR and \fBFIPS_mode_set()\fR have been removed +from OpenSSL 3.0. You should rewrite your application to not use them. +See \fBfips_module\fR\|(7) and \fBOSSL_PROVIDER\-FIPS\fR\|(7) for details. +.SS "Completing the installation of the FIPS Module" +.IX Subsection "Completing the installation of the FIPS Module" +The FIPS Module will be built and installed automatically if FIPS support has +been configured. The current documentation can be found in the +README-FIPS file. +.SS Programming +.IX Subsection "Programming" +Applications written to work with OpenSSL 1.1.1 will mostly just work with +OpenSSL 3.0. However changes will be required if you want to take advantage of +some of the new features that OpenSSL 3.0 makes available. In order to do that +you need to understand some new concepts introduced in OpenSSL 3.0. +Read "Library contexts" in \fBcrypto\fR\|(7) for further information. +.PP +\fILibrary Context\fR +.IX Subsection "Library Context" +.PP +A library context allows different components of a complex application to each +use a different library context and have different providers loaded with +different configuration settings. +See "Library contexts" in \fBcrypto\fR\|(7) for further info. +.PP +If the user creates an \fBOSSL_LIB_CTX\fR via \fBOSSL_LIB_CTX_new\fR\|(3) then many +functions may need to be changed to pass additional parameters to handle the +library context. +.PP +Using a Library Context \- Old functions that should be changed +.IX Subsection "Using a Library Context - Old functions that should be changed" +.PP +If a library context is needed then all EVP_* digest functions that return a +\&\fBconst EVP_MD *\fR such as \fBEVP_sha256()\fR should be replaced with a call to +\&\fBEVP_MD_fetch\fR\|(3). See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7). +.PP +If a library context is needed then all EVP_* cipher functions that return a +\&\fBconst EVP_CIPHER *\fR such as \fBEVP_aes_128_cbc()\fR should be replaced vith a call to +\&\fBEVP_CIPHER_fetch\fR\|(3). See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7). +.PP +Some functions can be passed an object that has already been set up with a library +context such as \fBd2i_X509\fR\|(3), \fBd2i_X509_CRL\fR\|(3), \fBd2i_X509_REQ\fR\|(3) and +\&\fBd2i_X509_PUBKEY\fR\|(3). If NULL is passed instead then the created object will be +set up with the default library context. Use \fBX509_new_ex\fR\|(3), +\&\fBX509_CRL_new_ex\fR\|(3), \fBX509_REQ_new_ex\fR\|(3) and \fBX509_PUBKEY_new_ex\fR\|(3) if a +library context is required. +.PP +All functions listed below with a \fINAME\fR have a replacement function \fINAME_ex\fR +that takes \fBOSSL_LIB_CTX\fR as an additional argument. Functions that have other +mappings are listed along with the respective name. +.IP \(bu 4 +\&\fBASN1_item_new\fR\|(3), \fBASN1_item_d2i\fR\|(3), \fBASN1_item_d2i_fp\fR\|(3), +\&\fBASN1_item_d2i_bio\fR\|(3), \fBASN1_item_sign\fR\|(3) and \fBASN1_item_verify\fR\|(3) +.IP \(bu 4 +\&\fBBIO_new\fR\|(3) +.IP \(bu 4 +\&\fBb2i_RSA_PVK_bio()\fR and \fBi2b_PVK_bio()\fR +.IP \(bu 4 +\&\fBBN_CTX_new\fR\|(3) and \fBBN_CTX_secure_new\fR\|(3) +.IP \(bu 4 +\&\fBCMS_AuthEnvelopedData_create\fR\|(3), \fBCMS_ContentInfo_new\fR\|(3), \fBCMS_data_create\fR\|(3), +\&\fBCMS_digest_create\fR\|(3), \fBCMS_EncryptedData_encrypt\fR\|(3), \fBCMS_encrypt\fR\|(3), +\&\fBCMS_EnvelopedData_create\fR\|(3), \fBCMS_ReceiptRequest_create0\fR\|(3) and \fBCMS_sign\fR\|(3) +.IP \(bu 4 +\&\fBCONF_modules_load_file\fR\|(3) +.IP \(bu 4 +\&\fBCTLOG_new\fR\|(3), \fBCTLOG_new_from_base64\fR\|(3) and \fBCTLOG_STORE_new\fR\|(3) +.IP \(bu 4 +\&\fBCT_POLICY_EVAL_CTX_new\fR\|(3) +.IP \(bu 4 +\&\fBd2i_AutoPrivateKey\fR\|(3), \fBd2i_PrivateKey\fR\|(3) and \fBd2i_PUBKEY\fR\|(3) +.IP \(bu 4 +\&\fBd2i_PrivateKey_bio\fR\|(3) and \fBd2i_PrivateKey_fp\fR\|(3) +.Sp +Use \fBd2i_PrivateKey_ex_bio\fR\|(3) and \fBd2i_PrivateKey_ex_fp\fR\|(3) +.IP \(bu 4 +\&\fBEC_GROUP_new\fR\|(3) +.Sp +Use \fBEC_GROUP_new_by_curve_name_ex\fR\|(3) or \fBEC_GROUP_new_from_params\fR\|(3). +.IP \(bu 4 +\&\fBEVP_DigestSignInit\fR\|(3) and \fBEVP_DigestVerifyInit\fR\|(3) +.IP \(bu 4 +\&\fBEVP_PBE_CipherInit\fR\|(3), \fBEVP_PBE_find\fR\|(3) and \fBEVP_PBE_scrypt\fR\|(3) +.IP \(bu 4 +\&\fBPKCS5_PBE_keyivgen\fR\|(3) +.IP \(bu 4 +\&\fBEVP_PKCS82PKEY\fR\|(3) +.IP \(bu 4 +\&\fBEVP_PKEY_CTX_new_id\fR\|(3) +.Sp +Use \fBEVP_PKEY_CTX_new_from_name\fR\|(3) +.IP \(bu 4 +\&\fBEVP_PKEY_derive_set_peer\fR\|(3), \fBEVP_PKEY_new_raw_private_key\fR\|(3) +and \fBEVP_PKEY_new_raw_public_key\fR\|(3) +.IP \(bu 4 +\&\fBEVP_SignFinal\fR\|(3) and \fBEVP_VerifyFinal\fR\|(3) +.IP \(bu 4 +\&\fBNCONF_new\fR\|(3) +.IP \(bu 4 +\&\fBOCSP_RESPID_match\fR\|(3) and \fBOCSP_RESPID_set_by_key\fR\|(3) +.IP \(bu 4 +\&\fBOPENSSL_thread_stop\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_STORE_open\fR\|(3) +.IP \(bu 4 +\&\fBPEM_read_bio_Parameters\fR\|(3), \fBPEM_read_bio_PrivateKey\fR\|(3), \fBPEM_read_bio_PUBKEY\fR\|(3), +\&\fBPEM_read_PrivateKey\fR\|(3) and \fBPEM_read_PUBKEY\fR\|(3) +.IP \(bu 4 +\&\fBPEM_write_bio_PrivateKey\fR\|(3), \fBPEM_write_bio_PUBKEY\fR\|(3), \fBPEM_write_PrivateKey\fR\|(3) +and \fBPEM_write_PUBKEY\fR\|(3) +.IP \(bu 4 +\&\fBPEM_X509_INFO_read_bio\fR\|(3) and \fBPEM_X509_INFO_read\fR\|(3) +.IP \(bu 4 +\&\fBPKCS12_add_key\fR\|(3), \fBPKCS12_add_safe\fR\|(3), \fBPKCS12_add_safes\fR\|(3), +\&\fBPKCS12_create\fR\|(3), \fBPKCS12_decrypt_skey\fR\|(3), \fBPKCS12_init\fR\|(3), \fBPKCS12_item_decrypt_d2i\fR\|(3), +\&\fBPKCS12_item_i2d_encrypt\fR\|(3), \fBPKCS12_key_gen_asc\fR\|(3), \fBPKCS12_key_gen_uni\fR\|(3), +\&\fBPKCS12_key_gen_utf8\fR\|(3), \fBPKCS12_pack_p7encdata\fR\|(3), \fBPKCS12_pbe_crypt\fR\|(3), +\&\fBPKCS12_PBE_keyivgen\fR\|(3), \fBPKCS12_SAFEBAG_create_pkcs8_encrypt\fR\|(3) +.IP \(bu 4 +\&\fBPKCS5_pbe_set0_algor\fR\|(3), \fBPKCS5_pbe_set\fR\|(3), \fBPKCS5_pbe2_set_iv\fR\|(3), +\&\fBPKCS5_pbkdf2_set\fR\|(3) and \fBPKCS5_v2_scrypt_keyivgen\fR\|(3) +.IP \(bu 4 +\&\fBPKCS7_encrypt\fR\|(3), \fBPKCS7_new\fR\|(3) and \fBPKCS7_sign\fR\|(3) +.IP \(bu 4 +\&\fBPKCS8_decrypt\fR\|(3), \fBPKCS8_encrypt\fR\|(3) and \fBPKCS8_set0_pbe\fR\|(3) +.IP \(bu 4 +\&\fBRAND_bytes\fR\|(3) and \fBRAND_priv_bytes\fR\|(3) +.IP \(bu 4 +\&\fBSMIME_write_ASN1\fR\|(3) +.IP \(bu 4 +\&\fBSSL_load_client_CA_file\fR\|(3) +.IP \(bu 4 +\&\fBSSL_CTX_new\fR\|(3) +.IP \(bu 4 +\&\fBTS_RESP_CTX_new\fR\|(3) +.IP \(bu 4 +\&\fBX509_CRL_new\fR\|(3) +.IP \(bu 4 +\&\fBX509_load_cert_crl_file\fR\|(3) and \fBX509_load_cert_file\fR\|(3) +.IP \(bu 4 +\&\fBX509_LOOKUP_by_subject\fR\|(3) and \fBX509_LOOKUP_ctrl\fR\|(3) +.IP \(bu 4 +\&\fBX509_NAME_hash\fR\|(3) +.IP \(bu 4 +\&\fBX509_new\fR\|(3) +.IP \(bu 4 +\&\fBX509_REQ_new\fR\|(3) and \fBX509_REQ_verify\fR\|(3) +.IP \(bu 4 +\&\fBX509_STORE_CTX_new\fR\|(3), \fBX509_STORE_set_default_paths\fR\|(3), \fBX509_STORE_load_file\fR\|(3), +\&\fBX509_STORE_load_locations\fR\|(3) and \fBX509_STORE_load_store\fR\|(3) +.PP +New functions that use a Library context +.IX Subsection "New functions that use a Library context" +.PP +The following functions can be passed a library context if required. +Passing NULL will use the default library context. +.IP \(bu 4 +\&\fBBIO_new_from_core_bio\fR\|(3) +.IP \(bu 4 +\&\fBEVP_ASYM_CIPHER_fetch\fR\|(3) and \fBEVP_ASYM_CIPHER_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_CIPHER_fetch\fR\|(3) and \fBEVP_CIPHER_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_default_properties_enable_fips\fR\|(3) and +\&\fBEVP_default_properties_is_fips_enabled\fR\|(3) +.IP \(bu 4 +\&\fBEVP_KDF_fetch\fR\|(3) and \fBEVP_KDF_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_KEM_fetch\fR\|(3) and \fBEVP_KEM_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_KEYEXCH_fetch\fR\|(3) and \fBEVP_KEYEXCH_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_KEYMGMT_fetch\fR\|(3) and \fBEVP_KEYMGMT_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_MAC_fetch\fR\|(3) and \fBEVP_MAC_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_MD_fetch\fR\|(3) and \fBEVP_MD_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_PKEY_CTX_new_from_pkey\fR\|(3) +.IP \(bu 4 +\&\fBEVP_PKEY_Q_keygen\fR\|(3) +.IP \(bu 4 +\&\fBEVP_Q_mac\fR\|(3) and \fBEVP_Q_digest\fR\|(3) +.IP \(bu 4 +\&\fBEVP_RAND\fR\|(3) and \fBEVP_RAND_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_set_default_properties\fR\|(3) +.IP \(bu 4 +\&\fBEVP_SIGNATURE_fetch\fR\|(3) and \fBEVP_SIGNATURE_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_CMP_CTX_new\fR\|(3) and \fBOSSL_CMP_SRV_CTX_new\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_CRMF_ENCRYPTEDVALUE_get1_encCert\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_CRMF_MSG_create_popo\fR\|(3) and \fBOSSL_CRMF_MSGS_verify_popo\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_CRMF_pbm_new\fR\|(3) and \fBOSSL_CRMF_pbmp_new\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_DECODER_CTX_add_extra\fR\|(3) and \fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_DECODER_fetch\fR\|(3) and \fBOSSL_DECODER_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_ENCODER_CTX_add_extra\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_ENCODER_fetch\fR\|(3) and \fBOSSL_ENCODER_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_LIB_CTX_free\fR\|(3), \fBOSSL_LIB_CTX_load_config\fR\|(3) and \fBOSSL_LIB_CTX_set0_default\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_PROVIDER_add_builtin\fR\|(3), \fBOSSL_PROVIDER_available\fR\|(3), +\&\fBOSSL_PROVIDER_do_all\fR\|(3), \fBOSSL_PROVIDER_load\fR\|(3), +\&\fBOSSL_PROVIDER_set_default_search_path\fR\|(3) and \fBOSSL_PROVIDER_try_load\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_SELF_TEST_get_callback\fR\|(3) and \fBOSSL_SELF_TEST_set_callback\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_STORE_attach\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_STORE_LOADER_fetch\fR\|(3) and \fBOSSL_STORE_LOADER_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBRAND_get0_primary\fR\|(3), \fBRAND_get0_private\fR\|(3), \fBRAND_get0_public\fR\|(3), +\&\fBRAND_set_DRBG_type\fR\|(3) and \fBRAND_set_seed_source_type\fR\|(3) +.PP +\fIProviders\fR +.IX Subsection "Providers" +.PP +Providers are described in detail here "Providers" in \fBcrypto\fR\|(7). +See also "OPENSSL PROVIDERS" in \fBcrypto\fR\|(7). +.PP +\fIFetching algorithms and property queries\fR +.IX Subsection "Fetching algorithms and property queries" +.PP +Implicit and Explicit Fetching is described in detail here +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7). +.PP +\fIMapping EVP controls and flags to provider \fR\f(BIOSSL_PARAM\fR\fI\|(3) parameters\fR +.IX Subsection "Mapping EVP controls and flags to provider OSSL_PARAM parameters" +.PP +The existing functions for controls (such as \fBEVP_CIPHER_CTX_ctrl\fR\|(3)) and +manipulating flags (such as \fBEVP_MD_CTX_set_flags\fR\|(3))internally use +\&\fBOSSL_PARAMS\fR to pass information to/from provider objects. +See \fBOSSL_PARAM\fR\|(3) for additional information related to parameters. +.PP +For ciphers see "CONTROLS" in \fBEVP_EncryptInit\fR\|(3), "FLAGS" in \fBEVP_EncryptInit\fR\|(3) and +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.PP +For digests see "CONTROLS" in \fBEVP_DigestInit\fR\|(3), "FLAGS" in \fBEVP_DigestInit\fR\|(3) and +"PARAMETERS" in \fBEVP_DigestInit\fR\|(3). +.PP +\fIDeprecation of Low Level Functions\fR +.IX Subsection "Deprecation of Low Level Functions" +.PP +A significant number of APIs have been deprecated in OpenSSL 3.0. +This section describes some common categories of deprecations. +See "Deprecated function mappings" for the list of deprecated functions +that refer to these categories. +.PP +Providers are a replacement for engines and low-level method overrides +.IX Subsection "Providers are a replacement for engines and low-level method overrides" +.PP +Any accessor that uses an ENGINE is deprecated (such as \fBEVP_PKEY_set1_engine()\fR). +Applications using engines should instead use providers. +.PP +Before providers were added algorithms were overridden by changing the methods +used by algorithms. All these methods such as \fBRSA_new_method()\fR and \fBRSA_meth_new()\fR +are now deprecated and can be replaced by using providers instead. +.PP +Deprecated i2d and d2i functions for low-level key types +.IX Subsection "Deprecated i2d and d2i functions for low-level key types" +.PP +Any i2d and d2i functions such as \fBd2i_DHparams()\fR that take a low-level key type +have been deprecated. Applications should instead use the \fBOSSL_DECODER\fR\|(3) and +\&\fBOSSL_ENCODER\fR\|(3) APIs to read and write files. +See "Migration" in \fBd2i_RSAPrivateKey\fR\|(3) for further details. +.PP +Deprecated low-level key object getters and setters +.IX Subsection "Deprecated low-level key object getters and setters" +.PP +Applications that set or get low-level key objects (such as \fBEVP_PKEY_set1_DH()\fR +or \fBEVP_PKEY_get0()\fR) should instead use the OSSL_ENCODER +(See \fBOSSL_ENCODER_to_bio\fR\|(3)) or OSSL_DECODER (See \fBOSSL_DECODER_from_bio\fR\|(3)) +APIs, or alternatively use \fBEVP_PKEY_fromdata\fR\|(3) or \fBEVP_PKEY_todata\fR\|(3). +.PP +Deprecated low-level key parameter getters +.IX Subsection "Deprecated low-level key parameter getters" +.PP +Functions that access low-level objects directly such as \fBRSA_get0_n\fR\|(3) are now +deprecated. Applications should use one of \fBEVP_PKEY_get_bn_param\fR\|(3), +\&\fBEVP_PKEY_get_int_param\fR\|(3), l<\fBEVP_PKEY_get_size_t_param\fR\|(3)>, +\&\fBEVP_PKEY_get_utf8_string_param\fR\|(3), \fBEVP_PKEY_get_octet_string_param\fR\|(3) or +\&\fBEVP_PKEY_get_params\fR\|(3) to access fields from an EVP_PKEY. +Gettable parameters are listed in "Common RSA parameters" in \fBEVP_PKEY\-RSA\fR\|(7), +"DH parameters" in \fBEVP_PKEY\-DH\fR\|(7), "DSA parameters" in \fBEVP_PKEY\-DSA\fR\|(7), +"FFC parameters" in \fBEVP_PKEY\-FFC\fR\|(7), "Common EC parameters" in \fBEVP_PKEY\-EC\fR\|(7) and +"Common X25519, X448, ED25519 and ED448 parameters" in \fBEVP_PKEY\-X25519\fR\|(7). +Applications may also use \fBEVP_PKEY_todata\fR\|(3) to return all fields. +.PP +Deprecated low-level key parameter setters +.IX Subsection "Deprecated low-level key parameter setters" +.PP +Functions that access low-level objects directly such as \fBRSA_set0_crt_params\fR\|(3) +are now deprecated. Applications should use \fBEVP_PKEY_fromdata\fR\|(3) to create +new keys from user provided key data. Keys should be immutable once they are +created, so if required the user may use \fBEVP_PKEY_todata\fR\|(3), \fBOSSL_PARAM_merge\fR\|(3), +and \fBEVP_PKEY_fromdata\fR\|(3) to create a modified key. +See "Examples" in \fBEVP_PKEY\-DH\fR\|(7) for more information. +See "Deprecated low-level key generation functions" for information on +generating a key using parameters. +.PP +Deprecated low-level object creation +.IX Subsection "Deprecated low-level object creation" +.PP +Low-level objects were created using methods such as \fBRSA_new\fR\|(3), +\&\fBRSA_up_ref\fR\|(3) and \fBRSA_free\fR\|(3). Applications should instead use the +high-level EVP_PKEY APIs, e.g. \fBEVP_PKEY_new\fR\|(3), \fBEVP_PKEY_up_ref\fR\|(3) and +\&\fBEVP_PKEY_free\fR\|(3). +See also \fBEVP_PKEY_CTX_new_from_name\fR\|(3) and \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3). +.PP +EVP_PKEYs may be created in a variety of ways: +See also "Deprecated low-level key generation functions", +"Deprecated low-level key reading and writing functions" and +"Deprecated low-level key parameter setters". +.PP +Deprecated low-level encryption functions +.IX Subsection "Deprecated low-level encryption functions" +.PP +Low-level encryption functions such as \fBAES_encrypt\fR\|(3) and \fBAES_decrypt\fR\|(3) +have been informally discouraged from use for a long time. Applications should +instead use the high level EVP APIs \fBEVP_EncryptInit_ex\fR\|(3), +\&\fBEVP_EncryptUpdate\fR\|(3), and \fBEVP_EncryptFinal_ex\fR\|(3) or +\&\fBEVP_DecryptInit_ex\fR\|(3), \fBEVP_DecryptUpdate\fR\|(3) and \fBEVP_DecryptFinal_ex\fR\|(3). +.PP +Deprecated low-level digest functions +.IX Subsection "Deprecated low-level digest functions" +.PP +Use of low-level digest functions such as \fBSHA1_Init\fR\|(3) have been +informally discouraged from use for a long time. Applications should instead +use the the high level EVP APIs \fBEVP_DigestInit_ex\fR\|(3), \fBEVP_DigestUpdate\fR\|(3) +and \fBEVP_DigestFinal_ex\fR\|(3), or the quick one-shot \fBEVP_Q_digest\fR\|(3). +.PP +Note that the functions \fBSHA1\fR\|(3), \fBSHA224\fR\|(3), \fBSHA256\fR\|(3), \fBSHA384\fR\|(3) +and \fBSHA512\fR\|(3) have changed to macros that use \fBEVP_Q_digest\fR\|(3). +.PP +Deprecated low-level signing functions +.IX Subsection "Deprecated low-level signing functions" +.PP +Use of low-level signing functions such as \fBDSA_sign\fR\|(3) have been +informally discouraged for a long time. Instead applications should use +\&\fBEVP_DigestSign\fR\|(3) and \fBEVP_DigestVerify\fR\|(3). +See also \fBEVP_SIGNATURE\-RSA\fR\|(7), \fBEVP_SIGNATURE\-DSA\fR\|(7), +\&\fBEVP_SIGNATURE\-ECDSA\fR\|(7) and \fBEVP_SIGNATURE\-ED25519\fR\|(7). +.PP +Deprecated low-level MAC functions +.IX Subsection "Deprecated low-level MAC functions" +.PP +Low-level mac functions such as \fBCMAC_Init\fR\|(3) are deprecated. +Applications should instead use the new \fBEVP_MAC\fR\|(3) interface, using +\&\fBEVP_MAC_CTX_new\fR\|(3), \fBEVP_MAC_CTX_free\fR\|(3), \fBEVP_MAC_init\fR\|(3), +\&\fBEVP_MAC_update\fR\|(3) and \fBEVP_MAC_final\fR\|(3) or the single-shot MAC function +\&\fBEVP_Q_mac\fR\|(3). +See \fBEVP_MAC\fR\|(3), \fBEVP_MAC\-HMAC\fR\|(7), \fBEVP_MAC\-CMAC\fR\|(7), \fBEVP_MAC\-GMAC\fR\|(7), +\&\fBEVP_MAC\-KMAC\fR\|(7), \fBEVP_MAC\-BLAKE2\fR\|(7), \fBEVP_MAC\-Poly1305\fR\|(7) and +\&\fBEVP_MAC\-Siphash\fR\|(7) for additional information. +.PP +Note that the one-shot method \fBHMAC()\fR is still available for compatibility purposes, +but this can also be replaced by using EVP_Q_MAC if a library context is required. +.PP +Deprecated low-level validation functions +.IX Subsection "Deprecated low-level validation functions" +.PP +Low-level validation functions such as \fBDH_check\fR\|(3) have been informally +discouraged from use for a long time. Applications should instead use the high-level +EVP_PKEY APIs such as \fBEVP_PKEY_check\fR\|(3), \fBEVP_PKEY_param_check\fR\|(3), +\&\fBEVP_PKEY_param_check_quick\fR\|(3), \fBEVP_PKEY_public_check\fR\|(3), +\&\fBEVP_PKEY_public_check_quick\fR\|(3), \fBEVP_PKEY_private_check\fR\|(3), +and \fBEVP_PKEY_pairwise_check\fR\|(3). +.PP +Deprecated low-level key exchange functions +.IX Subsection "Deprecated low-level key exchange functions" +.PP +Many low-level functions have been informally discouraged from use for a long +time. Applications should instead use \fBEVP_PKEY_derive\fR\|(3). +See \fBEVP_KEYEXCH\-DH\fR\|(7), \fBEVP_KEYEXCH\-ECDH\fR\|(7) and \fBEVP_KEYEXCH\-X25519\fR\|(7). +.PP +Deprecated low-level key generation functions +.IX Subsection "Deprecated low-level key generation functions" +.PP +Many low-level functions have been informally discouraged from use for a long +time. Applications should instead use \fBEVP_PKEY_keygen_init\fR\|(3) and +\&\fBEVP_PKEY_generate\fR\|(3) as described in \fBEVP_PKEY\-DSA\fR\|(7), \fBEVP_PKEY\-DH\fR\|(7), +\&\fBEVP_PKEY\-RSA\fR\|(7), \fBEVP_PKEY\-EC\fR\|(7) and \fBEVP_PKEY\-X25519\fR\|(7). +The 'quick' one-shot function \fBEVP_PKEY_Q_keygen\fR\|(3) and macros for the most +common cases: <\fBEVP_RSA_gen\fR\|(3)> and \fBEVP_EC_gen\fR\|(3) may also be used. +.PP +Deprecated low-level key reading and writing functions +.IX Subsection "Deprecated low-level key reading and writing functions" +.PP +Use of low-level objects (such as DSA) has been informally discouraged from use +for a long time. Functions to read and write these low-level objects (such as +\&\fBPEM_read_DSA_PUBKEY()\fR) should be replaced. Applications should instead use +\&\fBOSSL_ENCODER_to_bio\fR\|(3) and \fBOSSL_DECODER_from_bio\fR\|(3). +.PP +Deprecated low-level key printing functions +.IX Subsection "Deprecated low-level key printing functions" +.PP +Use of low-level objects (such as DSA) has been informally discouraged from use +for a long time. Functions to print these low-level objects such as +\&\fBDSA_print()\fR should be replaced with the equivalent EVP_PKEY functions. +Application should use one of \fBEVP_PKEY_print_public\fR\|(3), +\&\fBEVP_PKEY_print_private\fR\|(3), \fBEVP_PKEY_print_params\fR\|(3), +\&\fBEVP_PKEY_print_public_fp\fR\|(3), \fBEVP_PKEY_print_private_fp\fR\|(3) or +\&\fBEVP_PKEY_print_params_fp\fR\|(3). Note that internally these use +\&\fBOSSL_ENCODER_to_bio\fR\|(3) and \fBOSSL_DECODER_from_bio\fR\|(3). +.PP +\fIDeprecated function mappings\fR +.IX Subsection "Deprecated function mappings" +.PP +The following functions have been deprecated in 3.0. +.IP \(bu 4 +\&\fBAES_bi_ige_encrypt()\fR and \fBAES_ige_encrypt()\fR +.Sp +There is no replacement for the IGE functions. New code should not use these modes. +These undocumented functions were never integrated into the EVP layer. +They implemented the AES Infinite Garble Extension (IGE) mode and AES +Bi-directional IGE mode. These modes were never formally standardised and +usage of these functions is believed to be very small. In particular +\&\fBAES_bi_ige_encrypt()\fR has a known bug. It accepts 2 AES keys, but only one +is ever used. The security implications are believed to be minimal, but +this issue was never fixed for backwards compatibility reasons. +.IP \(bu 4 +\&\fBAES_encrypt()\fR, \fBAES_decrypt()\fR, \fBAES_set_encrypt_key()\fR, \fBAES_set_decrypt_key()\fR, +\&\fBAES_cbc_encrypt()\fR, \fBAES_cfb128_encrypt()\fR, \fBAES_cfb1_encrypt()\fR, \fBAES_cfb8_encrypt()\fR, +\&\fBAES_ecb_encrypt()\fR, \fBAES_ofb128_encrypt()\fR +.IP \(bu 4 +\&\fBAES_unwrap_key()\fR, \fBAES_wrap_key()\fR +.Sp +See "Deprecated low-level encryption functions" +.IP \(bu 4 +\&\fBAES_options()\fR +.Sp +There is no replacement. It returned a string indicating if the AES code was unrolled. +.IP \(bu 4 +\&\fBASN1_digest()\fR, \fBASN1_sign()\fR, \fBASN1_verify()\fR +.Sp +There are no replacements. These old functions are not used, and could be +disabled with the macro NO_ASN1_OLD since OpenSSL 0.9.7. +.IP \(bu 4 +\&\fBASN1_STRING_length_set()\fR +.Sp +Use \fBASN1_STRING_set\fR\|(3) or \fBASN1_STRING_set0\fR\|(3) instead. +This was a potentially unsafe function that could change the bounds of a +previously passed in pointer. +.IP \(bu 4 +\&\fBBF_encrypt()\fR, \fBBF_decrypt()\fR, \fBBF_set_key()\fR, \fBBF_cbc_encrypt()\fR, \fBBF_cfb64_encrypt()\fR, +\&\fBBF_ecb_encrypt()\fR, \fBBF_ofb64_encrypt()\fR +.Sp +See "Deprecated low-level encryption functions". +The Blowfish algorithm has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBBF_options()\fR +.Sp +There is no replacement. This option returned a constant string. +.IP \(bu 4 +\&\fBBIO_get_callback()\fR, \fBBIO_set_callback()\fR, \fBBIO_debug_callback()\fR +.Sp +Use the respective non-deprecated \fB_ex()\fR functions. +.IP \(bu 4 +\&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR +.Sp +Use \fBBN_check_prime\fR\|(3) which avoids possible misuse and always uses at least +64 rounds of the Miller-Rabin primality test. +.IP \(bu 4 +\&\fBBN_pseudo_rand()\fR, \fBBN_pseudo_rand_range()\fR +.Sp +Use \fBBN_rand\fR\|(3) and \fBBN_rand_range\fR\|(3). +.IP \(bu 4 +\&\fBBN_X931_derive_prime_ex()\fR, \fBBN_X931_generate_prime_ex()\fR, \fBBN_X931_generate_Xpq()\fR +.Sp +There are no replacements for these low-level functions. They were used internally +by \fBRSA_X931_derive_ex()\fR and \fBRSA_X931_generate_key_ex()\fR which are also deprecated. +Use \fBEVP_PKEY_keygen\fR\|(3) instead. +.IP \(bu 4 +\&\fBCamellia_encrypt()\fR, \fBCamellia_decrypt()\fR, \fBCamellia_set_key()\fR, +\&\fBCamellia_cbc_encrypt()\fR, \fBCamellia_cfb128_encrypt()\fR, \fBCamellia_cfb1_encrypt()\fR, +\&\fBCamellia_cfb8_encrypt()\fR, \fBCamellia_ctr128_encrypt()\fR, \fBCamellia_ecb_encrypt()\fR, +\&\fBCamellia_ofb128_encrypt()\fR +.Sp +See "Deprecated low-level encryption functions". +.IP \(bu 4 +\&\fBCAST_encrypt()\fR, \fBCAST_decrypt()\fR, \fBCAST_set_key()\fR, \fBCAST_cbc_encrypt()\fR, +\&\fBCAST_cfb64_encrypt()\fR, \fBCAST_ecb_encrypt()\fR, \fBCAST_ofb64_encrypt()\fR +.Sp +See "Deprecated low-level encryption functions". +The CAST algorithm has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBCMAC_CTX_new()\fR, \fBCMAC_CTX_cleanup()\fR, \fBCMAC_CTX_copy()\fR, \fBCMAC_CTX_free()\fR, +\&\fBCMAC_CTX_get0_cipher_ctx()\fR +.Sp +See "Deprecated low-level MAC functions". +.IP \(bu 4 +\&\fBCMAC_Init()\fR, \fBCMAC_Update()\fR, \fBCMAC_Final()\fR, \fBCMAC_resume()\fR +.Sp +See "Deprecated low-level MAC functions". +.IP \(bu 4 +\&\fBCRYPTO_mem_ctrl()\fR, \fBCRYPTO_mem_debug_free()\fR, \fBCRYPTO_mem_debug_malloc()\fR, +\&\fBCRYPTO_mem_debug_pop()\fR, \fBCRYPTO_mem_debug_push()\fR, \fBCRYPTO_mem_debug_realloc()\fR, +\&\fBCRYPTO_mem_leaks()\fR, \fBCRYPTO_mem_leaks_cb()\fR, \fBCRYPTO_mem_leaks_fp()\fR, +\&\fBCRYPTO_set_mem_debug()\fR +.Sp +Memory-leak checking has been deprecated in favor of more modern development +tools, such as compiler memory and leak sanitizers or Valgrind. +.IP \(bu 4 +\&\fBCRYPTO_cts128_encrypt_block()\fR, \fBCRYPTO_cts128_encrypt()\fR, +\&\fBCRYPTO_cts128_decrypt_block()\fR, \fBCRYPTO_cts128_decrypt()\fR, +\&\fBCRYPTO_nistcts128_encrypt_block()\fR, \fBCRYPTO_nistcts128_encrypt()\fR, +\&\fBCRYPTO_nistcts128_decrypt_block()\fR, \fBCRYPTO_nistcts128_decrypt()\fR +.Sp +Use the higher level functions \fBEVP_CipherInit_ex2()\fR, \fBEVP_CipherUpdate()\fR and +\&\fBEVP_CipherFinal_ex()\fR instead. +See the "cts_mode" parameter in +"Gettable and Settable EVP_CIPHER_CTX parameters" in \fBEVP_EncryptInit\fR\|(3). +See "EXAMPLES" in \fBEVP_EncryptInit\fR\|(3) for a AES\-256\-CBC\-CTS example. +.IP \(bu 4 +\&\fBd2i_DHparams()\fR, \fBd2i_DHxparams()\fR, \fBd2i_DSAparams()\fR, \fBd2i_DSAPrivateKey()\fR, +\&\fBd2i_DSAPrivateKey_bio()\fR, \fBd2i_DSAPrivateKey_fp()\fR, \fBd2i_DSA_PUBKEY()\fR, +\&\fBd2i_DSA_PUBKEY_bio()\fR, \fBd2i_DSA_PUBKEY_fp()\fR, \fBd2i_DSAPublicKey()\fR, +\&\fBd2i_ECParameters()\fR, \fBd2i_ECPrivateKey()\fR, \fBd2i_ECPrivateKey_bio()\fR, +\&\fBd2i_ECPrivateKey_fp()\fR, \fBd2i_EC_PUBKEY()\fR, \fBd2i_EC_PUBKEY_bio()\fR, +\&\fBd2i_EC_PUBKEY_fp()\fR, \fBd2i_RSAPrivateKey()\fR, +\&\fBd2i_RSAPrivateKey_bio()\fR, \fBd2i_RSAPrivateKey_fp()\fR, \fBd2i_RSA_PUBKEY()\fR, +\&\fBd2i_RSA_PUBKEY_bio()\fR, \fBd2i_RSA_PUBKEY_fp()\fR, \fBd2i_RSAPublicKey()\fR, +\&\fBd2i_RSAPublicKey_bio()\fR, \fBd2i_RSAPublicKey_fp()\fR +.Sp +See "Deprecated i2d and d2i functions for low-level key types" +.IP \(bu 4 +\&\fBo2i_ECPublicKey()\fR +.Sp +Use \fBEVP_PKEY_set1_encoded_public_key\fR\|(3). +See "Deprecated low-level key parameter setters" +.IP \(bu 4 +\&\fBDES_crypt()\fR, \fBDES_fcrypt()\fR, \fBDES_encrypt1()\fR, \fBDES_encrypt2()\fR, \fBDES_encrypt3()\fR, +\&\fBDES_decrypt3()\fR, \fBDES_ede3_cbc_encrypt()\fR, \fBDES_ede3_cfb64_encrypt()\fR, +\&\fBDES_ede3_cfb_encrypt()\fR,\fBDES_ede3_ofb64_encrypt()\fR, +\&\fBDES_ecb_encrypt()\fR, \fBDES_ecb3_encrypt()\fR, \fBDES_ofb64_encrypt()\fR, \fBDES_ofb_encrypt()\fR, +DES_cfb64_encrypt \fBDES_cfb_encrypt()\fR, \fBDES_cbc_encrypt()\fR, \fBDES_ncbc_encrypt()\fR, +\&\fBDES_pcbc_encrypt()\fR, \fBDES_xcbc_encrypt()\fR, \fBDES_cbc_cksum()\fR, \fBDES_quad_cksum()\fR, +\&\fBDES_check_key_parity()\fR, \fBDES_is_weak_key()\fR, \fBDES_key_sched()\fR, \fBDES_options()\fR, +\&\fBDES_random_key()\fR, \fBDES_set_key()\fR, \fBDES_set_key_checked()\fR, \fBDES_set_key_unchecked()\fR, +\&\fBDES_set_odd_parity()\fR, \fBDES_string_to_2keys()\fR, \fBDES_string_to_key()\fR +.Sp +See "Deprecated low-level encryption functions". +Algorithms for "DESX-CBC", "DES-ECB", "DES-CBC", "DES-OFB", "DES-CFB", +"DES\-CFB1" and "DES\-CFB8" have been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBDH_bits()\fR, \fBDH_security_bits()\fR, \fBDH_size()\fR +.Sp +Use \fBEVP_PKEY_get_bits\fR\|(3), \fBEVP_PKEY_get_security_bits\fR\|(3) and +\&\fBEVP_PKEY_get_size\fR\|(3). +.IP \(bu 4 +\&\fBDH_check()\fR, \fBDH_check_ex()\fR, \fBDH_check_params()\fR, \fBDH_check_params_ex()\fR, +\&\fBDH_check_pub_key()\fR, \fBDH_check_pub_key_ex()\fR +.Sp +See "Deprecated low-level validation functions" +.IP \(bu 4 +\&\fBDH_clear_flags()\fR, \fBDH_test_flags()\fR, \fBDH_set_flags()\fR +.Sp +The \fBDH_FLAG_CACHE_MONT_P\fR flag has been deprecated without replacement. +The \fBDH_FLAG_TYPE_DH\fR and \fBDH_FLAG_TYPE_DHX\fR have been deprecated. +Use \fBEVP_PKEY_is_a()\fR to determine the type of a key. +There is no replacement for setting these flags. +.IP \(bu 4 +\&\fBDH_compute_key()\fR \fBDH_compute_key_padded()\fR +.Sp +See "Deprecated low-level key exchange functions". +.IP \(bu 4 +\&\fBDH_new()\fR, \fBDH_new_by_nid()\fR, \fBDH_free()\fR, \fBDH_up_ref()\fR +.Sp +See "Deprecated low-level object creation" +.IP \(bu 4 +\&\fBDH_generate_key()\fR, \fBDH_generate_parameters_ex()\fR +.Sp +See "Deprecated low-level key generation functions". +.IP \(bu 4 +\&\fBDH_get0_pqg()\fR, \fBDH_get0_p()\fR, \fBDH_get0_q()\fR, \fBDH_get0_g()\fR, \fBDH_get0_key()\fR, +\&\fBDH_get0_priv_key()\fR, \fBDH_get0_pub_key()\fR, \fBDH_get_length()\fR, \fBDH_get_nid()\fR +.Sp +See "Deprecated low-level key parameter getters" +.IP \(bu 4 +\&\fBDH_get_1024_160()\fR, \fBDH_get_2048_224()\fR, \fBDH_get_2048_256()\fR +.Sp +Applications should instead set the \fBOSSL_PKEY_PARAM_GROUP_NAME\fR as specified in +"DH parameters" in \fBEVP_PKEY\-DH\fR\|(7)) to one of "dh_1024_160", "dh_2048_224" or +"dh_2048_256" when generating a DH key. +.IP \(bu 4 +\&\fBDH_KDF_X9_42()\fR +.Sp +Applications should use \fBEVP_PKEY_CTX_set_dh_kdf_type\fR\|(3) instead. +.IP \(bu 4 +\&\fBDH_get_default_method()\fR, \fBDH_get0_engine()\fR, DH_meth_*(), \fBDH_new_method()\fR, +\&\fBDH_OpenSSL()\fR, \fBDH_get_ex_data()\fR, \fBDH_set_default_method()\fR, \fBDH_set_method()\fR, +\&\fBDH_set_ex_data()\fR +.Sp +See "Providers are a replacement for engines and low-level method overrides" +.IP \(bu 4 +\&\fBDHparams_print()\fR, \fBDHparams_print_fp()\fR +.Sp +See "Deprecated low-level key printing functions" +.IP \(bu 4 +\&\fBDH_set0_key()\fR, \fBDH_set0_pqg()\fR, \fBDH_set_length()\fR +.Sp +See "Deprecated low-level key parameter setters" +.IP \(bu 4 +\&\fBDSA_bits()\fR, \fBDSA_security_bits()\fR, \fBDSA_size()\fR +.Sp +Use \fBEVP_PKEY_get_bits\fR\|(3), \fBEVP_PKEY_get_security_bits\fR\|(3) and +\&\fBEVP_PKEY_get_size\fR\|(3). +.IP \(bu 4 +\&\fBDHparams_dup()\fR, \fBDSA_dup_DH()\fR +.Sp +There is no direct replacement. Applications may use \fBEVP_PKEY_copy_parameters\fR\|(3) +and \fBEVP_PKEY_dup\fR\|(3) instead. +.IP \(bu 4 +\&\fBDSA_generate_key()\fR, \fBDSA_generate_parameters_ex()\fR +.Sp +See "Deprecated low-level key generation functions". +.IP \(bu 4 +\&\fBDSA_get0_engine()\fR, \fBDSA_get_default_method()\fR, \fBDSA_get_ex_data()\fR, +\&\fBDSA_get_method()\fR, DSA_meth_*(), \fBDSA_new_method()\fR, \fBDSA_OpenSSL()\fR, +\&\fBDSA_set_default_method()\fR, \fBDSA_set_ex_data()\fR, \fBDSA_set_method()\fR +.Sp +See "Providers are a replacement for engines and low-level method overrides". +.IP \(bu 4 +\&\fBDSA_get0_p()\fR, \fBDSA_get0_q()\fR, \fBDSA_get0_g()\fR, \fBDSA_get0_pqg()\fR, \fBDSA_get0_key()\fR, +\&\fBDSA_get0_priv_key()\fR, \fBDSA_get0_pub_key()\fR +.Sp +See "Deprecated low-level key parameter getters". +.IP \(bu 4 +\&\fBDSA_new()\fR, \fBDSA_free()\fR, \fBDSA_up_ref()\fR +.Sp +See "Deprecated low-level object creation" +.IP \(bu 4 +\&\fBDSAparams_dup()\fR +.Sp +There is no direct replacement. Applications may use \fBEVP_PKEY_copy_parameters\fR\|(3) +and \fBEVP_PKEY_dup\fR\|(3) instead. +.IP \(bu 4 +\&\fBDSAparams_print()\fR, \fBDSAparams_print_fp()\fR, \fBDSA_print()\fR, \fBDSA_print_fp()\fR +.Sp +See "Deprecated low-level key printing functions" +.IP \(bu 4 +\&\fBDSA_set0_key()\fR, \fBDSA_set0_pqg()\fR +.Sp +See "Deprecated low-level key parameter setters" +.IP \(bu 4 +\&\fBDSA_set_flags()\fR, \fBDSA_clear_flags()\fR, \fBDSA_test_flags()\fR +.Sp +The \fBDSA_FLAG_CACHE_MONT_P\fR flag has been deprecated without replacement. +.IP \(bu 4 +\&\fBDSA_sign()\fR, \fBDSA_do_sign()\fR, \fBDSA_sign_setup()\fR, \fBDSA_verify()\fR, \fBDSA_do_verify()\fR +.Sp +See "Deprecated low-level signing functions". +.IP \(bu 4 +\&\fBECDH_compute_key()\fR +.Sp +See "Deprecated low-level key exchange functions". +.IP \(bu 4 +\&\fBECDH_KDF_X9_62()\fR +.Sp +Applications may either set this using the helper function +\&\fBEVP_PKEY_CTX_set_ecdh_kdf_type\fR\|(3) or by setting an \fBOSSL_PARAM\fR\|(3) using the +"kdf-type" as shown in "EXAMPLES" in \fBEVP_KEYEXCH\-ECDH\fR\|(7) +.IP \(bu 4 +\&\fBECDSA_sign()\fR, \fBECDSA_sign_ex()\fR, \fBECDSA_sign_setup()\fR, \fBECDSA_do_sign()\fR, +\&\fBECDSA_do_sign_ex()\fR, \fBECDSA_verify()\fR, \fBECDSA_do_verify()\fR +.Sp +See "Deprecated low-level signing functions". +.IP \(bu 4 +\&\fBECDSA_size()\fR +.Sp +Applications should use \fBEVP_PKEY_get_size\fR\|(3). +.IP \(bu 4 +\&\fBEC_GF2m_simple_method()\fR, \fBEC_GFp_mont_method()\fR, \fBEC_GFp_nist_method()\fR, +\&\fBEC_GFp_nistp224_method()\fR, \fBEC_GFp_nistp256_method()\fR, \fBEC_GFp_nistp521_method()\fR, +\&\fBEC_GFp_simple_method()\fR +.Sp +There are no replacements for these functions. Applications should rely on the +library automatically assigning a suitable method internally when an EC_GROUP +is constructed. +.IP \(bu 4 +\&\fBEC_GROUP_clear_free()\fR +.Sp +Use \fBEC_GROUP_free\fR\|(3) instead. +.IP \(bu 4 +\&\fBEC_GROUP_get_curve_GF2m()\fR, \fBEC_GROUP_get_curve_GFp()\fR, \fBEC_GROUP_set_curve_GF2m()\fR, +\&\fBEC_GROUP_set_curve_GFp()\fR +.Sp +Applications should use \fBEC_GROUP_get_curve\fR\|(3) and \fBEC_GROUP_set_curve\fR\|(3). +.IP \(bu 4 +\&\fBEC_GROUP_have_precompute_mult()\fR, \fBEC_GROUP_precompute_mult()\fR, +\&\fBEC_KEY_precompute_mult()\fR +.Sp +These functions are not widely used. Applications should instead switch to +named curves which OpenSSL has hardcoded lookup tables for. +.IP \(bu 4 +\&\fBEC_GROUP_new()\fR, \fBEC_GROUP_method_of()\fR, \fBEC_POINT_method_of()\fR +.Sp +EC_METHOD is now an internal-only concept and a suitable EC_METHOD is assigned +internally without application intervention. +Users of \fBEC_GROUP_new()\fR should switch to a different suitable constructor. +.IP \(bu 4 +\&\fBEC_KEY_can_sign()\fR +.Sp +Applications should use \fBEVP_PKEY_can_sign\fR\|(3) instead. +.IP \(bu 4 +\&\fBEC_KEY_check_key()\fR +.Sp +See "Deprecated low-level validation functions" +.IP \(bu 4 +\&\fBEC_KEY_set_flags()\fR, \fBEC_KEY_get_flags()\fR, \fBEC_KEY_clear_flags()\fR +.Sp +See "Common EC parameters" in \fBEVP_PKEY\-EC\fR\|(7) which handles flags as separate +parameters for \fBOSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT\fR, +\&\fBOSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE\fR, \fBOSSL_PKEY_PARAM_EC_ENCODING\fR, +\&\fBOSSL_PKEY_PARAM_USE_COFACTOR_ECDH\fR and +\&\fBOSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC\fR. +See also "EXAMPLES" in \fBEVP_PKEY\-EC\fR\|(7) +.IP \(bu 4 +\&\fBEC_KEY_dup()\fR, \fBEC_KEY_copy()\fR +.Sp +There is no direct replacement. Applications may use \fBEVP_PKEY_copy_parameters\fR\|(3) +and \fBEVP_PKEY_dup\fR\|(3) instead. +.IP \(bu 4 +\&\fBEC_KEY_decoded_from_explicit_params()\fR +.Sp +There is no replacement. +.IP \(bu 4 +\&\fBEC_KEY_generate_key()\fR +.Sp +See "Deprecated low-level key generation functions". +.IP \(bu 4 +\&\fBEC_KEY_get0_group()\fR, \fBEC_KEY_get0_private_key()\fR, \fBEC_KEY_get0_public_key()\fR, +\&\fBEC_KEY_get_conv_form()\fR, \fBEC_KEY_get_enc_flags()\fR +.Sp +See "Deprecated low-level key parameter getters". +.IP \(bu 4 +\&\fBEC_KEY_get0_engine()\fR, \fBEC_KEY_get_default_method()\fR, \fBEC_KEY_get_method()\fR, +\&\fBEC_KEY_new_method()\fR, \fBEC_KEY_get_ex_data()\fR, \fBEC_KEY_OpenSSL()\fR, +\&\fBEC_KEY_set_ex_data()\fR, \fBEC_KEY_set_default_method()\fR, EC_KEY_METHOD_*(), +\&\fBEC_KEY_set_method()\fR +.Sp +See "Providers are a replacement for engines and low-level method overrides" +.IP \(bu 4 +\&\fBEC_METHOD_get_field_type()\fR +.Sp +Use \fBEC_GROUP_get_field_type\fR\|(3) instead. +See "Providers are a replacement for engines and low-level method overrides" +.IP \(bu 4 +\&\fBEC_KEY_key2buf()\fR, \fBEC_KEY_oct2key()\fR, \fBEC_KEY_oct2priv()\fR, \fBEC_KEY_priv2buf()\fR, +\&\fBEC_KEY_priv2oct()\fR +.Sp +There are no replacements for these. +.IP \(bu 4 +\&\fBEC_KEY_new()\fR, \fBEC_KEY_new_by_curve_name()\fR, \fBEC_KEY_free()\fR, \fBEC_KEY_up_ref()\fR +.Sp +See "Deprecated low-level object creation" +.IP \(bu 4 +\&\fBEC_KEY_print()\fR, \fBEC_KEY_print_fp()\fR +.Sp +See "Deprecated low-level key printing functions" +.IP \(bu 4 +\&\fBEC_KEY_set_asn1_flag()\fR, \fBEC_KEY_set_conv_form()\fR, \fBEC_KEY_set_enc_flags()\fR +.Sp +See "Deprecated low-level key parameter setters". +.IP \(bu 4 +\&\fBEC_KEY_set_group()\fR, \fBEC_KEY_set_private_key()\fR, \fBEC_KEY_set_public_key()\fR, +\&\fBEC_KEY_set_public_key_affine_coordinates()\fR +.Sp +See "Deprecated low-level key parameter setters". +.IP \(bu 4 +\&\fBECParameters_print()\fR, \fBECParameters_print_fp()\fR, \fBECPKParameters_print()\fR, +\&\fBECPKParameters_print_fp()\fR +.Sp +See "Deprecated low-level key printing functions" +.IP \(bu 4 +\&\fBEC_POINT_bn2point()\fR, \fBEC_POINT_point2bn()\fR +.Sp +These functions were not particularly useful, since EC point serialization +formats are not individual big-endian integers. +.IP \(bu 4 +\&\fBEC_POINT_get_affine_coordinates_GF2m()\fR, \fBEC_POINT_get_affine_coordinates_GFp()\fR, +\&\fBEC_POINT_set_affine_coordinates_GF2m()\fR, \fBEC_POINT_set_affine_coordinates_GFp()\fR +.Sp +Applications should use \fBEC_POINT_get_affine_coordinates\fR\|(3) and +\&\fBEC_POINT_set_affine_coordinates\fR\|(3) instead. +.IP \(bu 4 +\&\fBEC_POINT_get_Jprojective_coordinates_GFp()\fR, \fBEC_POINT_set_Jprojective_coordinates_GFp()\fR +.Sp +These functions are not widely used. Applications should instead use the +\&\fBEC_POINT_set_affine_coordinates\fR\|(3) and \fBEC_POINT_get_affine_coordinates\fR\|(3) +functions. +.IP \(bu 4 +\&\fBEC_POINT_make_affine()\fR, \fBEC_POINTs_make_affine()\fR +.Sp +There is no replacement. These functions were not widely used, and OpenSSL +automatically performs this conversion when needed. +.IP \(bu 4 +\&\fBEC_POINT_set_compressed_coordinates_GF2m()\fR, \fBEC_POINT_set_compressed_coordinates_GFp()\fR +.Sp +Applications should use \fBEC_POINT_set_compressed_coordinates\fR\|(3) instead. +.IP \(bu 4 +\&\fBEC_POINTs_mul()\fR +.Sp +This function is not widely used. Applications should instead use the +\&\fBEC_POINT_mul\fR\|(3) function. +.IP \(bu 4 +\&\fBENGINE_*()\fR +.Sp +All engine functions are deprecated. An engine should be rewritten as a provider. +See "Providers are a replacement for engines and low-level method overrides". +.IP \(bu 4 +\&\fBERR_load_*()\fR, \fBERR_func_error_string()\fR, \fBERR_get_error_line()\fR, +\&\fBERR_get_error_line_data()\fR, \fBERR_get_state()\fR +.Sp +OpenSSL now loads error strings automatically so these functions are not needed. +.IP \(bu 4 +\&\fBERR_peek_error_line_data()\fR, \fBERR_peek_last_error_line_data()\fR +.Sp +The new functions are \fBERR_peek_error_func\fR\|(3), \fBERR_peek_last_error_func\fR\|(3), +\&\fBERR_peek_error_data\fR\|(3), \fBERR_peek_last_error_data\fR\|(3), \fBERR_get_error_all\fR\|(3), +\&\fBERR_peek_error_all\fR\|(3) and \fBERR_peek_last_error_all\fR\|(3). +Applications should use \fBERR_get_error_all\fR\|(3), or pick information +with ERR_peek functions and finish off with getting the error code by using +\&\fBERR_get_error\fR\|(3). +.IP \(bu 4 +\&\fBEVP_CIPHER_CTX_iv()\fR, \fBEVP_CIPHER_CTX_iv_noconst()\fR, \fBEVP_CIPHER_CTX_original_iv()\fR +.Sp +Applications should instead use \fBEVP_CIPHER_CTX_get_updated_iv\fR\|(3), +\&\fBEVP_CIPHER_CTX_get_updated_iv\fR\|(3) and \fBEVP_CIPHER_CTX_get_original_iv\fR\|(3) +respectively. +See \fBEVP_CIPHER_CTX_get_original_iv\fR\|(3) for further information. +.IP \(bu 4 +\&\fBEVP_CIPHER_meth_*()\fR, \fBEVP_MD_CTX_set_update_fn()\fR, \fBEVP_MD_CTX_update_fn()\fR, +\&\fBEVP_MD_meth_*()\fR +.Sp +See "Providers are a replacement for engines and low-level method overrides". +.IP \(bu 4 +\&\fBEVP_PKEY_CTRL_PKCS7_ENCRYPT()\fR, \fBEVP_PKEY_CTRL_PKCS7_DECRYPT()\fR, +\&\fBEVP_PKEY_CTRL_PKCS7_SIGN()\fR, \fBEVP_PKEY_CTRL_CMS_ENCRYPT()\fR, +\&\fBEVP_PKEY_CTRL_CMS_DECRYPT()\fR, and \fBEVP_PKEY_CTRL_CMS_SIGN()\fR +.Sp +These control operations are not invoked by the OpenSSL library anymore and +are replaced by direct checks of the key operation against the key type +when the operation is initialized. +.IP \(bu 4 +\&\fBEVP_PKEY_CTX_get0_dh_kdf_ukm()\fR, \fBEVP_PKEY_CTX_get0_ecdh_kdf_ukm()\fR +.Sp +See the "kdf-ukm" item in "DH key exchange parameters" in \fBEVP_KEYEXCH\-DH\fR\|(7) and +"ECDH Key Exchange parameters" in \fBEVP_KEYEXCH\-ECDH\fR\|(7). +These functions are obsolete and should not be required. +.IP \(bu 4 +\&\fBEVP_PKEY_CTX_set_rsa_keygen_pubexp()\fR +.Sp +Applications should use \fBEVP_PKEY_CTX_set1_rsa_keygen_pubexp\fR\|(3) instead. +.IP \(bu 4 +\&\fBEVP_PKEY_cmp()\fR, \fBEVP_PKEY_cmp_parameters()\fR +.Sp +Applications should use \fBEVP_PKEY_eq\fR\|(3) and \fBEVP_PKEY_parameters_eq\fR\|(3) instead. +See \fBEVP_PKEY_copy_parameters\fR\|(3) for further details. +.IP \(bu 4 +\&\fBEVP_PKEY_encrypt_old()\fR, \fBEVP_PKEY_decrypt_old()\fR, +.Sp +Applications should use \fBEVP_PKEY_encrypt_init\fR\|(3) and \fBEVP_PKEY_encrypt\fR\|(3) or +\&\fBEVP_PKEY_decrypt_init\fR\|(3) and \fBEVP_PKEY_decrypt\fR\|(3) instead. +.IP \(bu 4 +\&\fBEVP_PKEY_get0()\fR +.Sp +This function returns NULL if the key comes from a provider. +.IP \(bu 4 +\&\fBEVP_PKEY_get0_DH()\fR, \fBEVP_PKEY_get0_DSA()\fR, \fBEVP_PKEY_get0_EC_KEY()\fR, \fBEVP_PKEY_get0_RSA()\fR, +\&\fBEVP_PKEY_get1_DH()\fR, \fBEVP_PKEY_get1_DSA()\fR, EVP_PKEY_get1_EC_KEY and \fBEVP_PKEY_get1_RSA()\fR, +\&\fBEVP_PKEY_get0_hmac()\fR, \fBEVP_PKEY_get0_poly1305()\fR, \fBEVP_PKEY_get0_siphash()\fR +.Sp +See "Functions that return an internal key should be treated as read only". +.IP \(bu 4 +\&\fBEVP_PKEY_meth_*()\fR +.Sp +See "Providers are a replacement for engines and low-level method overrides". +.IP \(bu 4 +\&\fBEVP_PKEY_new_CMAC_key()\fR +.Sp +See "Deprecated low-level MAC functions". +.IP \(bu 4 +\&\fBEVP_PKEY_assign()\fR, \fBEVP_PKEY_set1_DH()\fR, \fBEVP_PKEY_set1_DSA()\fR, +\&\fBEVP_PKEY_set1_EC_KEY()\fR, \fBEVP_PKEY_set1_RSA()\fR +.Sp +See "Deprecated low-level key object getters and setters" +.IP \(bu 4 +\&\fBEVP_PKEY_set1_tls_encodedpoint()\fR \fBEVP_PKEY_get1_tls_encodedpoint()\fR +.Sp +These functions were previously used by libssl to set or get an encoded public +key into/from an EVP_PKEY object. With OpenSSL 3.0 these are replaced by the more +generic functions \fBEVP_PKEY_set1_encoded_public_key\fR\|(3) and +\&\fBEVP_PKEY_get1_encoded_public_key\fR\|(3). +The old versions have been converted to deprecated macros that just call the +new functions. +.IP \(bu 4 +\&\fBEVP_PKEY_set1_engine()\fR, \fBEVP_PKEY_get0_engine()\fR +.Sp +See "Providers are a replacement for engines and low-level method overrides". +.IP \(bu 4 +\&\fBEVP_PKEY_set_alias_type()\fR +.Sp +This function has been removed. There is no replacement. +See "\fBEVP_PKEY_set_alias_type()\fR method has been removed" +.IP \(bu 4 +\&\fBHMAC_Init_ex()\fR, \fBHMAC_Update()\fR, \fBHMAC_Final()\fR, \fBHMAC_size()\fR +.Sp +See "Deprecated low-level MAC functions". +.IP \(bu 4 +\&\fBHMAC_CTX_new()\fR, \fBHMAC_CTX_free()\fR, \fBHMAC_CTX_copy()\fR, \fBHMAC_CTX_reset()\fR, +\&\fBHMAC_CTX_set_flags()\fR, \fBHMAC_CTX_get_md()\fR +.Sp +See "Deprecated low-level MAC functions". +.IP \(bu 4 +\&\fBi2d_DHparams()\fR, \fBi2d_DHxparams()\fR +.Sp +See "Deprecated low-level key reading and writing functions" +and "Migration" in \fBd2i_RSAPrivateKey\fR\|(3) +.IP \(bu 4 +\&\fBi2d_DSAparams()\fR, \fBi2d_DSAPrivateKey()\fR, \fBi2d_DSAPrivateKey_bio()\fR, +\&\fBi2d_DSAPrivateKey_fp()\fR, \fBi2d_DSA_PUBKEY()\fR, \fBi2d_DSA_PUBKEY_bio()\fR, +\&\fBi2d_DSA_PUBKEY_fp()\fR, \fBi2d_DSAPublicKey()\fR +.Sp +See "Deprecated low-level key reading and writing functions" +and "Migration" in \fBd2i_RSAPrivateKey\fR\|(3) +.IP \(bu 4 +\&\fBi2d_ECParameters()\fR, \fBi2d_ECPrivateKey()\fR, \fBi2d_ECPrivateKey_bio()\fR, +\&\fBi2d_ECPrivateKey_fp()\fR, \fBi2d_EC_PUBKEY()\fR, \fBi2d_EC_PUBKEY_bio()\fR, +\&\fBi2d_EC_PUBKEY_fp()\fR +.Sp +See "Deprecated low-level key reading and writing functions" +and "Migration" in \fBd2i_RSAPrivateKey\fR\|(3) +.IP \(bu 4 +\&\fBi2o_ECPublicKey()\fR +.Sp +Use \fBEVP_PKEY_get1_encoded_public_key\fR\|(3). +See "Deprecated low-level key parameter getters" +.IP \(bu 4 +\&\fBi2d_RSAPrivateKey()\fR, \fBi2d_RSAPrivateKey_bio()\fR, \fBi2d_RSAPrivateKey_fp()\fR, +\&\fBi2d_RSA_PUBKEY()\fR, \fBi2d_RSA_PUBKEY_bio()\fR, \fBi2d_RSA_PUBKEY_fp()\fR, +\&\fBi2d_RSAPublicKey()\fR, \fBi2d_RSAPublicKey_bio()\fR, \fBi2d_RSAPublicKey_fp()\fR +.Sp +See "Deprecated low-level key reading and writing functions" +and "Migration" in \fBd2i_RSAPrivateKey\fR\|(3) +.IP \(bu 4 +\&\fBIDEA_encrypt()\fR, \fBIDEA_set_decrypt_key()\fR, \fBIDEA_set_encrypt_key()\fR, +\&\fBIDEA_cbc_encrypt()\fR, \fBIDEA_cfb64_encrypt()\fR, \fBIDEA_ecb_encrypt()\fR, +\&\fBIDEA_ofb64_encrypt()\fR +.Sp +See "Deprecated low-level encryption functions". +IDEA has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBIDEA_options()\fR +.Sp +There is no replacement. This function returned a constant string. +.IP \(bu 4 +\&\fBMD2()\fR, \fBMD2_Init()\fR, \fBMD2_Update()\fR, \fBMD2_Final()\fR +.Sp +See "Deprecated low-level encryption functions". +MD2 has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBMD2_options()\fR +.Sp +There is no replacement. This function returned a constant string. +.IP \(bu 4 +\&\fBMD4()\fR, \fBMD4_Init()\fR, \fBMD4_Update()\fR, \fBMD4_Final()\fR, \fBMD4_Transform()\fR +.Sp +See "Deprecated low-level encryption functions". +MD4 has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBMDC2()\fR, \fBMDC2_Init()\fR, \fBMDC2_Update()\fR, \fBMDC2_Final()\fR +.Sp +See "Deprecated low-level encryption functions". +MDC2 has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBMD5()\fR, \fBMD5_Init()\fR, \fBMD5_Update()\fR, \fBMD5_Final()\fR, \fBMD5_Transform()\fR +.Sp +See "Deprecated low-level encryption functions". +.IP \(bu 4 +\&\fBNCONF_WIN32()\fR +.Sp +This undocumented function has no replacement. +See "HISTORY" in \fBconfig\fR\|(5) for more details. +.IP \(bu 4 +\&\fBOCSP_parse_url()\fR +.Sp +Use \fBOSSL_HTTP_parse_url\fR\|(3) instead. +.IP \(bu 4 +\&\fBOCSP_REQ_CTX\fR type and \fBOCSP_REQ_CTX_*()\fR functions +.Sp +These methods were used to collect all necessary data to form a HTTP request, +and to perform the HTTP transfer with that request. With OpenSSL 3.0, the +type is \fBOSSL_HTTP_REQ_CTX\fR, and the deprecated functions are replaced +with \fBOSSL_HTTP_REQ_CTX_*()\fR. See \fBOSSL_HTTP_REQ_CTX\fR\|(3) for additional +details. +.IP \(bu 4 +\&\fBOPENSSL_fork_child()\fR, \fBOPENSSL_fork_parent()\fR, \fBOPENSSL_fork_prepare()\fR +.Sp +There is no replacement for these functions. These pthread fork support methods +were unused by OpenSSL. +.IP \(bu 4 +\&\fBOSSL_STORE_ctrl()\fR, \fBOSSL_STORE_do_all_loaders()\fR, \fBOSSL_STORE_LOADER_get0_engine()\fR, +\&\fBOSSL_STORE_LOADER_get0_scheme()\fR, \fBOSSL_STORE_LOADER_new()\fR, +\&\fBOSSL_STORE_LOADER_set_attach()\fR, \fBOSSL_STORE_LOADER_set_close()\fR, +\&\fBOSSL_STORE_LOADER_set_ctrl()\fR, \fBOSSL_STORE_LOADER_set_eof()\fR, +\&\fBOSSL_STORE_LOADER_set_error()\fR, \fBOSSL_STORE_LOADER_set_expect()\fR, +\&\fBOSSL_STORE_LOADER_set_find()\fR, \fBOSSL_STORE_LOADER_set_load()\fR, +\&\fBOSSL_STORE_LOADER_set_open()\fR, \fBOSSL_STORE_LOADER_set_open_ex()\fR, +\&\fBOSSL_STORE_register_loader()\fR, \fBOSSL_STORE_unregister_loader()\fR, +\&\fBOSSL_STORE_vctrl()\fR +.Sp +These functions helped applications and engines create loaders for +schemes they supported. These are all deprecated and discouraged in favour of +provider implementations, see \fBprovider\-storemgmt\fR\|(7). +.IP \(bu 4 +\&\fBPEM_read_DHparams()\fR, \fBPEM_read_bio_DHparams()\fR, +\&\fBPEM_read_DSAparams()\fR, \fBPEM_read_bio_DSAparams()\fR, +\&\fBPEM_read_DSAPrivateKey()\fR, \fBPEM_read_DSA_PUBKEY()\fR, +PEM_read_bio_DSAPrivateKey and \fBPEM_read_bio_DSA_PUBKEY()\fR, +\&\fBPEM_read_ECPKParameters()\fR, \fBPEM_read_ECPrivateKey()\fR, \fBPEM_read_EC_PUBKEY()\fR, +\&\fBPEM_read_bio_ECPKParameters()\fR, \fBPEM_read_bio_ECPrivateKey()\fR, \fBPEM_read_bio_EC_PUBKEY()\fR, +\&\fBPEM_read_RSAPrivateKey()\fR, \fBPEM_read_RSA_PUBKEY()\fR, \fBPEM_read_RSAPublicKey()\fR, +\&\fBPEM_read_bio_RSAPrivateKey()\fR, \fBPEM_read_bio_RSA_PUBKEY()\fR, \fBPEM_read_bio_RSAPublicKey()\fR, +\&\fBPEM_write_bio_DHparams()\fR, \fBPEM_write_bio_DHxparams()\fR, \fBPEM_write_DHparams()\fR, \fBPEM_write_DHxparams()\fR, +\&\fBPEM_write_DSAparams()\fR, \fBPEM_write_DSAPrivateKey()\fR, \fBPEM_write_DSA_PUBKEY()\fR, +\&\fBPEM_write_bio_DSAparams()\fR, \fBPEM_write_bio_DSAPrivateKey()\fR, \fBPEM_write_bio_DSA_PUBKEY()\fR, +\&\fBPEM_write_ECPKParameters()\fR, \fBPEM_write_ECPrivateKey()\fR, \fBPEM_write_EC_PUBKEY()\fR, +\&\fBPEM_write_bio_ECPKParameters()\fR, \fBPEM_write_bio_ECPrivateKey()\fR, \fBPEM_write_bio_EC_PUBKEY()\fR, +\&\fBPEM_write_RSAPrivateKey()\fR, \fBPEM_write_RSA_PUBKEY()\fR, \fBPEM_write_RSAPublicKey()\fR, +\&\fBPEM_write_bio_RSAPrivateKey()\fR, \fBPEM_write_bio_RSA_PUBKEY()\fR, +\&\fBPEM_write_bio_RSAPublicKey()\fR, +.Sp +See "Deprecated low-level key reading and writing functions" +.IP \(bu 4 +\&\fBPKCS1_MGF1()\fR +.Sp +See "Deprecated low-level encryption functions". +.IP \(bu 4 +\&\fBRAND_get_rand_method()\fR, \fBRAND_set_rand_method()\fR, \fBRAND_OpenSSL()\fR, +\&\fBRAND_set_rand_engine()\fR +.Sp +Applications should instead use \fBRAND_set_DRBG_type\fR\|(3), +\&\fBEVP_RAND\fR\|(3) and \fBEVP_RAND\fR\|(7). +See \fBRAND_set_rand_method\fR\|(3) for more details. +.IP \(bu 4 +\&\fBRC2_encrypt()\fR, \fBRC2_decrypt()\fR, \fBRC2_set_key()\fR, \fBRC2_cbc_encrypt()\fR, \fBRC2_cfb64_encrypt()\fR, +\&\fBRC2_ecb_encrypt()\fR, \fBRC2_ofb64_encrypt()\fR, +\&\fBRC4()\fR, \fBRC4_set_key()\fR, \fBRC4_options()\fR, +\&\fBRC5_32_encrypt()\fR, \fBRC5_32_set_key()\fR, \fBRC5_32_decrypt()\fR, \fBRC5_32_cbc_encrypt()\fR, +\&\fBRC5_32_cfb64_encrypt()\fR, \fBRC5_32_ecb_encrypt()\fR, \fBRC5_32_ofb64_encrypt()\fR +.Sp +See "Deprecated low-level encryption functions". +The Algorithms "RC2", "RC4" and "RC5" have been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBRIPEMD160()\fR, \fBRIPEMD160_Init()\fR, \fBRIPEMD160_Update()\fR, \fBRIPEMD160_Final()\fR, +\&\fBRIPEMD160_Transform()\fR +.Sp +See "Deprecated low-level digest functions". +The RIPE algorithm has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBRSA_bits()\fR, \fBRSA_security_bits()\fR, \fBRSA_size()\fR +.Sp +Use \fBEVP_PKEY_get_bits\fR\|(3), \fBEVP_PKEY_get_security_bits\fR\|(3) and +\&\fBEVP_PKEY_get_size\fR\|(3). +.IP \(bu 4 +\&\fBRSA_check_key()\fR, \fBRSA_check_key_ex()\fR +.Sp +See "Deprecated low-level validation functions" +.IP \(bu 4 +\&\fBRSA_clear_flags()\fR, \fBRSA_flags()\fR, \fBRSA_set_flags()\fR, \fBRSA_test_flags()\fR, +\&\fBRSA_setup_blinding()\fR, \fBRSA_blinding_off()\fR, \fBRSA_blinding_on()\fR +.Sp +All of these RSA flags have been deprecated without replacement: +.Sp +\&\fBRSA_FLAG_BLINDING\fR, \fBRSA_FLAG_CACHE_PRIVATE\fR, \fBRSA_FLAG_CACHE_PUBLIC\fR, +\&\fBRSA_FLAG_EXT_PKEY\fR, \fBRSA_FLAG_NO_BLINDING\fR, \fBRSA_FLAG_THREAD_SAFE\fR +\&\fBRSA_METHOD_FLAG_NO_CHECK\fR +.IP \(bu 4 +\&\fBRSA_generate_key_ex()\fR, \fBRSA_generate_multi_prime_key()\fR +.Sp +See "Deprecated low-level key generation functions". +.IP \(bu 4 +\&\fBRSA_get0_engine()\fR +.Sp +See "Providers are a replacement for engines and low-level method overrides" +.IP \(bu 4 +\&\fBRSA_get0_crt_params()\fR, \fBRSA_get0_d()\fR, \fBRSA_get0_dmp1()\fR, \fBRSA_get0_dmq1()\fR, +\&\fBRSA_get0_e()\fR, \fBRSA_get0_factors()\fR, \fBRSA_get0_iqmp()\fR, \fBRSA_get0_key()\fR, +\&\fBRSA_get0_multi_prime_crt_params()\fR, \fBRSA_get0_multi_prime_factors()\fR, \fBRSA_get0_n()\fR, +\&\fBRSA_get0_p()\fR, \fBRSA_get0_pss_params()\fR, \fBRSA_get0_q()\fR, +\&\fBRSA_get_multi_prime_extra_count()\fR +.Sp +See "Deprecated low-level key parameter getters" +.IP \(bu 4 +\&\fBRSA_new()\fR, \fBRSA_free()\fR, \fBRSA_up_ref()\fR +.Sp +See "Deprecated low-level object creation". +.IP \(bu 4 +\&\fBRSA_get_default_method()\fR, RSA_get_ex_data and \fBRSA_get_method()\fR +.Sp +See "Providers are a replacement for engines and low-level method overrides". +.IP \(bu 4 +\&\fBRSA_get_version()\fR +.Sp +There is no replacement. +.IP \(bu 4 +\&\fBRSA_meth_*()\fR, \fBRSA_new_method()\fR, RSA_null_method and \fBRSA_PKCS1_OpenSSL()\fR +.Sp +See "Providers are a replacement for engines and low-level method overrides". +.IP \(bu 4 +\&\fBRSA_padding_add_*()\fR, \fBRSA_padding_check_*()\fR +.Sp +See "Deprecated low-level signing functions" and +"Deprecated low-level encryption functions". +.IP \(bu 4 +\&\fBRSA_print()\fR, \fBRSA_print_fp()\fR +.Sp +See "Deprecated low-level key printing functions" +.IP \(bu 4 +\&\fBRSA_public_encrypt()\fR, \fBRSA_private_decrypt()\fR +.Sp +See "Deprecated low-level encryption functions" +.IP \(bu 4 +\&\fBRSA_private_encrypt()\fR, \fBRSA_public_decrypt()\fR +.Sp +This is equivalent to doing sign and verify recover operations (with a padding +mode of none). See "Deprecated low-level signing functions". +.IP \(bu 4 +\&\fBRSAPrivateKey_dup()\fR, \fBRSAPublicKey_dup()\fR +.Sp +There is no direct replacement. Applications may use \fBEVP_PKEY_dup\fR\|(3). +.IP \(bu 4 +\&\fBRSAPublicKey_it()\fR, \fBRSAPrivateKey_it()\fR +.Sp +See "Deprecated low-level key reading and writing functions" +.IP \(bu 4 +\&\fBRSA_set0_crt_params()\fR, \fBRSA_set0_factors()\fR, \fBRSA_set0_key()\fR, +\&\fBRSA_set0_multi_prime_params()\fR +.Sp +See "Deprecated low-level key parameter setters". +.IP \(bu 4 +\&\fBRSA_set_default_method()\fR, \fBRSA_set_method()\fR, \fBRSA_set_ex_data()\fR +.Sp +See "Providers are a replacement for engines and low-level method overrides" +.IP \(bu 4 +\&\fBRSA_sign()\fR, \fBRSA_sign_ASN1_OCTET_STRING()\fR, \fBRSA_verify()\fR, +\&\fBRSA_verify_ASN1_OCTET_STRING()\fR, \fBRSA_verify_PKCS1_PSS()\fR, +\&\fBRSA_verify_PKCS1_PSS_mgf1()\fR +.Sp +See "Deprecated low-level signing functions". +.IP \(bu 4 +\&\fBRSA_X931_derive_ex()\fR, \fBRSA_X931_generate_key_ex()\fR, \fBRSA_X931_hash_id()\fR +.Sp +There are no replacements for these functions. +X931 padding can be set using "Signature Parameters" in \fBEVP_SIGNATURE\-RSA\fR\|(7). +See \fBOSSL_SIGNATURE_PARAM_PAD_MODE\fR. +.IP \(bu 4 +\&\fBSEED_encrypt()\fR, \fBSEED_decrypt()\fR, \fBSEED_set_key()\fR, \fBSEED_cbc_encrypt()\fR, +\&\fBSEED_cfb128_encrypt()\fR, \fBSEED_ecb_encrypt()\fR, \fBSEED_ofb128_encrypt()\fR +.Sp +See "Deprecated low-level encryption functions". +The SEED algorithm has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBSHA1_Init()\fR, \fBSHA1_Update()\fR, \fBSHA1_Final()\fR, \fBSHA1_Transform()\fR, +\&\fBSHA224_Init()\fR, \fBSHA224_Update()\fR, \fBSHA224_Final()\fR, +\&\fBSHA256_Init()\fR, \fBSHA256_Update()\fR, \fBSHA256_Final()\fR, \fBSHA256_Transform()\fR, +\&\fBSHA384_Init()\fR, \fBSHA384_Update()\fR, \fBSHA384_Final()\fR, +\&\fBSHA512_Init()\fR, \fBSHA512_Update()\fR, \fBSHA512_Final()\fR, \fBSHA512_Transform()\fR +.Sp +See "Deprecated low-level digest functions". +.IP \(bu 4 +\&\fBSRP_Calc_A()\fR, \fBSRP_Calc_B()\fR, \fBSRP_Calc_client_key()\fR, \fBSRP_Calc_server_key()\fR, +\&\fBSRP_Calc_u()\fR, \fBSRP_Calc_x()\fR, \fBSRP_check_known_gN_param()\fR, \fBSRP_create_verifier()\fR, +\&\fBSRP_create_verifier_BN()\fR, \fBSRP_get_default_gN()\fR, \fBSRP_user_pwd_free()\fR, \fBSRP_user_pwd_new()\fR, +\&\fBSRP_user_pwd_set0_sv()\fR, \fBSRP_user_pwd_set1_ids()\fR, \fBSRP_user_pwd_set_gN()\fR, +\&\fBSRP_VBASE_add0_user()\fR, \fBSRP_VBASE_free()\fR, \fBSRP_VBASE_get1_by_user()\fR, \fBSRP_VBASE_init()\fR, +\&\fBSRP_VBASE_new()\fR, \fBSRP_Verify_A_mod_N()\fR, \fBSRP_Verify_B_mod_N()\fR +.Sp +There are no replacements for the SRP functions. +.IP \(bu 4 +\&\fBSSL_CTX_set_tmp_dh_callback()\fR, \fBSSL_set_tmp_dh_callback()\fR, +\&\fBSSL_CTX_set_tmp_dh()\fR, \fBSSL_set_tmp_dh()\fR +.Sp +These are used to set the Diffie-Hellman (DH) parameters that are to be used by +servers requiring ephemeral DH keys. Instead applications should consider using +the built-in DH parameters that are available by calling \fBSSL_CTX_set_dh_auto\fR\|(3) +or \fBSSL_set_dh_auto\fR\|(3). If custom parameters are necessary then applications can +use the alternative functions \fBSSL_CTX_set0_tmp_dh_pkey\fR\|(3) and +\&\fBSSL_set0_tmp_dh_pkey\fR\|(3). There is no direct replacement for the "callback" +functions. The callback was originally useful in order to have different +parameters for export and non-export ciphersuites. Export ciphersuites are no +longer supported by OpenSSL. Use of the callback functions should be replaced +by one of the other methods described above. +.IP \(bu 4 +\&\fBSSL_CTX_set_tlsext_ticket_key_cb()\fR +.Sp +Use the new \fBSSL_CTX_set_tlsext_ticket_key_evp_cb\fR\|(3) function instead. +.IP \(bu 4 +\&\fBWHIRLPOOL()\fR, \fBWHIRLPOOL_Init()\fR, \fBWHIRLPOOL_Update()\fR, \fBWHIRLPOOL_Final()\fR, +\&\fBWHIRLPOOL_BitUpdate()\fR +.Sp +See "Deprecated low-level digest functions". +The Whirlpool algorithm has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBX509_certificate_type()\fR +.Sp +This was an undocumented function. Applications can use \fBX509_get0_pubkey\fR\|(3) +and \fBX509_get0_signature\fR\|(3) instead. +.IP \(bu 4 +\&\fBX509_http_nbio()\fR, \fBX509_CRL_http_nbio()\fR +.Sp +Use \fBX509_load_http\fR\|(3) and \fBX509_CRL_load_http\fR\|(3) instead. +.PP +\fINID handling for provided keys and algorithms\fR +.IX Subsection "NID handling for provided keys and algorithms" +.PP +The following functions for NID (numeric id) handling have changed semantics. +.IP \(bu 4 +\&\fBEVP_PKEY_id()\fR, \fBEVP_PKEY_get_id()\fR +.Sp +This function was previously used to reliably return the NID of +an EVP_PKEY object, e.g., to look up the name of the algorithm of +such EVP_PKEY by calling \fBOBJ_nid2sn\fR\|(3). With the introduction +of \fBprovider\fR\|(7)s \fBEVP_PKEY_id()\fR or its new equivalent +\&\fBEVP_PKEY_get_id\fR\|(3) might now also return the value \-1 +(\fBEVP_PKEY_KEYMGMT\fR) indicating the use of a provider to +implement the EVP_PKEY object. Therefore, the use of +\&\fBEVP_PKEY_get0_type_name\fR\|(3) is recommended for retrieving +the name of the EVP_PKEY algorithm. +.SS "Using the FIPS Module in applications" +.IX Subsection "Using the FIPS Module in applications" +See \fBfips_module\fR\|(7) and \fBOSSL_PROVIDER\-FIPS\fR\|(7) for details. +.SS "OpenSSL command line application changes" +.IX Subsection "OpenSSL command line application changes" +\fINew applications\fR +.IX Subsection "New applications" +.PP +\&\fBopenssl kdf\fR uses the new \fBEVP_KDF\fR\|(3) API. +\&\fBopenssl kdf\fR uses the new \fBEVP_MAC\fR\|(3) API. +.PP +\fIAdded options\fR +.IX Subsection "Added options" +.PP +\&\fB\-provider_path\fR and \fB\-provider\fR are available to all apps and can be used +multiple times to load any providers, such as the 'legacy' provider or third +party providers. If used then the 'default' provider would also need to be +specified if required. The \fB\-provider_path\fR must be specified before the +\&\fB\-provider\fR option. +.PP +The \fBlist\fR app has many new options. See \fBopenssl\-list\fR\|(1) for more +information. +.PP +\&\fB\-crl_lastupdate\fR and \fB\-crl_nextupdate\fR used by \fBopenssl ca\fR allows +explicit setting of fields in the generated CRL. +.PP +\fIRemoved options\fR +.IX Subsection "Removed options" +.PP +Interactive mode is not longer available. +.PP +The \fB\-crypt\fR option used by \fBopenssl passwd\fR. +The \fB\-c\fR option used by \fBopenssl x509\fR, \fBopenssl dhparam\fR, +\&\fBopenssl dsaparam\fR, and \fBopenssl ecparam\fR. +.PP +\fIOther Changes\fR +.IX Subsection "Other Changes" +.PP +The output of Command line applications may have minor changes. +These are primarily changes in capitalisation and white space. However, in some +cases, there are additional differences. +For example, the DH parameters output from \fBopenssl dhparam\fR now lists 'P', +\&'Q', 'G' and 'pcounter' instead of 'prime', 'generator', 'subgroup order' and +\&'counter' respectively. +.PP +The \fBopenssl\fR commands that read keys, certificates, and CRLs now +automatically detect the PEM or DER format of the input files so it is not +necessary to explicitly specify the input format anymore. However if the +input format option is used the specified format will be required. +.PP +\&\fBopenssl speed\fR no longer uses low-level API calls. +This implies some of the performance numbers might not be comparable with the +previous releases due to higher overhead. This applies particularly to +measuring performance on smaller data chunks. +.PP +b, \fBopenssl dsa\fR, \fBopenssl gendsa\fR, \fBopenssl dsaparam\fR, +\&\fBopenssl genrsa\fR and \fBopenssl rsa\fR have been modified to use PKEY APIs. +\&\fBopenssl genrsa\fR and \fBopenssl rsa\fR now write PKCS #8 keys by default. +.PP +\fIDefault settings\fR +.IX Subsection "Default settings" +.PP +"SHA256" is now the default digest for TS query used by \fBopenssl ts\fR. +.PP +\fIDeprecated apps\fR +.IX Subsection "Deprecated apps" +.PP +\&\fBopenssl rsautl\fR is deprecated, use \fBopenssl pkeyutl\fR instead. +\&\fBopenssl dhparam\fR, \fBopenssl dsa\fR, \fBopenssl gendsa\fR, \fBopenssl dsaparam\fR, +\&\fBopenssl genrsa\fR, \fBopenssl rsa\fR, \fBopenssl genrsa\fR and \fBopenssl rsa\fR are +now in maintenance mode and no new features will be added to them. +.SS "TLS Changes" +.IX Subsection "TLS Changes" +.IP \(bu 4 +TLS 1.3 FFDHE key exchange support added +.Sp +This uses DH safe prime named groups. +.IP \(bu 4 +Support for fully "pluggable" TLSv1.3 groups. +.Sp +This means that providers may supply their own group implementations (using +either the "key exchange" or the "key encapsulation" methods) which will +automatically be detected and used by libssl. +.IP \(bu 4 +SSL and SSL_CTX options are now 64 bit instead of 32 bit. +.Sp +The signatures of the functions to get and set options on SSL and +SSL_CTX objects changed from "unsigned long" to "uint64_t" type. +.Sp +This may require source code changes. For example it is no longer possible +to use the \fBSSL_OP_\fR macro values in preprocessor \f(CW\*(C`#if\*(C'\fR conditions. +However it is still possible to test whether these macros are defined or not. +.Sp +See \fBSSL_CTX_get_options\fR\|(3), \fBSSL_CTX_set_options\fR\|(3), +\&\fBSSL_get_options\fR\|(3) and \fBSSL_set_options\fR\|(3). +.IP \(bu 4 +\&\fBSSL_set1_host()\fR and \fBSSL_add1_host()\fR Changes +.Sp +These functions now take IP literal addresses as well as actual hostnames. +.IP \(bu 4 +Added SSL option SSL_OP_CLEANSE_PLAINTEXT +.Sp +If the option is set, openssl cleanses (zeroizes) plaintext bytes from +internal buffers after delivering them to the application. Note, +the application is still responsible for cleansing other copies +(e.g.: data received by \fBSSL_read\fR\|(3)). +.IP \(bu 4 +Client-initiated renegotiation is disabled by default. +.Sp +To allow it, use the \fB\-client_renegotiation\fR option, +the \fBSSL_OP_ALLOW_CLIENT_RENEGOTIATION\fR flag, or the \f(CW\*(C`ClientRenegotiation\*(C'\fR +config parameter as appropriate. +.IP \(bu 4 +Secure renegotiation is now required by default for TLS connections +.Sp +Support for RFC 5746 secure renegotiation is now required by default for +SSL or TLS connections to succeed. Applications that require the ability +to connect to legacy peers will need to explicitly set +SSL_OP_LEGACY_SERVER_CONNECT. Accordingly, SSL_OP_LEGACY_SERVER_CONNECT +is no longer set as part of SSL_OP_ALL. +.IP \(bu 4 +Combining the Configure options no-ec and no-dh no longer disables TLSv1.3 +.Sp +Typically if OpenSSL has no EC or DH algorithms then it cannot support +connections with TLSv1.3. However OpenSSL now supports "pluggable" groups +through providers. Therefore third party providers may supply group +implementations even where there are no built-in ones. Attempting to create +TLS connections in such a build without also disabling TLSv1.3 at run time or +using third party provider groups may result in handshake failures. TLSv1.3 +can be disabled at compile time using the "no\-tls1_3" Configure option. +.IP \(bu 4 +\&\fBSSL_CTX_set_ciphersuites()\fR and \fBSSL_set_ciphersuites()\fR changes. +.Sp +The methods now ignore unknown ciphers. +.IP \(bu 4 +Security callback change. +.Sp +The security callback, which can be customised by application code, supports +the security operation SSL_SECOP_TMP_DH. This is defined to take an EVP_PKEY +in the "other" parameter. In most places this is what is passed. All these +places occur server side. However there was one client side call of this +security operation and it passed a DH object instead. This is incorrect +according to the definition of SSL_SECOP_TMP_DH, and is inconsistent with all +of the other locations. Therefore this client side call has been changed to +pass an EVP_PKEY instead. +.IP \(bu 4 +New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF +.Sp +The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced. If that option +is set, an unexpected EOF is ignored, it pretends a close notify was received +instead and so the returned error becomes SSL_ERROR_ZERO_RETURN. +.IP \(bu 4 +The security strength of SHA1 and MD5 based signatures in TLS has been reduced. +.Sp +This results in SSL 3, TLS 1.0, TLS 1.1 and DTLS 1.0 no longer +working at the default security level of 1 and instead requires security +level 0. The security level can be changed either using the cipher string +with \f(CW@SECLEVEL\fR, or calling \fBSSL_CTX_set_security_level\fR\|(3). This also means +that where the signature algorithms extension is missing from a ClientHello +then the handshake will fail in TLS 1.2 at security level 1. This is because, +although this extension is optional, failing to provide one means that +OpenSSL will fallback to a default set of signature algorithms. This default +set requires the availability of SHA1. +.IP \(bu 4 +X509 certificates signed using SHA1 are no longer allowed at security level 1 and above. +.Sp +In TLS/SSL the default security level is 1. It can be set either using the cipher +string with \f(CW@SECLEVEL\fR, or calling \fBSSL_CTX_set_security_level\fR\|(3). If the +leaf certificate is signed with SHA\-1, a call to \fBSSL_CTX_use_certificate\fR\|(3) +will fail if the security level is not lowered first. +Outside TLS/SSL, the default security level is \-1 (effectively 0). It can +be set using \fBX509_VERIFY_PARAM_set_auth_level\fR\|(3) or using the \fB\-auth_level\fR +options of the commands. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBfips_module\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The migration guide was created for OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/npf-params.7 b/static/netbsd/man7/npf-params.7 new file mode 100644 index 00000000..6b80d4c0 --- /dev/null +++ b/static/netbsd/man7/npf-params.7 @@ -0,0 +1,178 @@ +.\" $NetBSD: npf-params.7,v 1.9 2023/02/12 13:21:28 kardel Exp $ +.\" +.\" Copyright (c) 2019 Mindaugas Rasiukevicius +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 31, 2020 +.Dt NPF-PARAMS 7 +.Os +.Sh NAME +.Nm npf-params +.Nd tunable NPF parameters +.Sh DESCRIPTION +NPF supports a set of dynamically tunable parameters. +.Pp +All parameter values are integers and should generally be between +zero and +.Dv INT_MAX , +unless specified otherwise. +Some parameters values can be negative; such values would typically +have a special meaning. +Enable/disable switches should be represented as boolean values 0 ("off") +or 1 ("on"). +.Sh PARAMETERS +.Bl -tag -width "123456" +.\" --- +.Bl -tag -width "123456" +.It Li bpf.jit +BPF just-in-time compilation: enables or disables +.Xr bpfjit 4 +support. +Some machine architectures are not presently supported by +.Xr bpfjit 4 . +Setting this parameter to off stops NPF from trying to enable this +functionality, and generating a warning if it is unable to do so. +Default: 1. +.El +.\" --- +.Bl -tag -width "123456" +.It Li ip4.reassembly +Perform IPv4 reassembly before inspecting the packet. +Fragmentation is considered very harmful, so most networks are expected +to prevent it; reassembly is enabled by default. +However, while the packet should generally be reassembled at the receiver, +reassembly by the packet filter may be necessary in order to perform state +tracking. +Default: 1. +.It Li ip6.reassembly +Perform IPv6 reassembly before inspecting the packet. +Discouraged in general but not prohibited by RFC 8200. +Default: 0. +.El +.\" --- +.Bl -tag -width "123456" +.It Li gc.step +Number of connection state items to process in one garbage collection +(G/C) cycle. +Must be positive number. +Default: 256. +.It Li gc.interval_min +The lower bound for the sleep time of the G/C worker. +The worker is self-tuning and will wake up more frequently if there are +connections to expire; it will wake up less frequently, diverging towards +the upper bound, if it does not encounter expired connections. +Default: 50 (in milliseconds). +.It Li gc.interval_max +The upper bound for the sleep time of the G/C worker. +Default: 5000 (in milliseconds). +.El +.\" --- +.It Li state.key +The connection state is uniquely identified by an n-tuple. +The state behavior can be controlled by including (excluding) +some of the information in (from) the keys. +.Bl -tag -width "123456" +.It Li interface +Include interface identifier into the keys, making the connection +state strictly per-interface. +Default: 1. +.It Li direction +Include packet direction into the keys. +Default: 1. +.El +.\" --- +.It Li state.generic +Generic state tracking parameters for non-TCP flows. +All timeouts are in seconds and must be zero or positive. +.Bl -tag -width "123456" +.It Li timeout.new +Timeout for new ("unsynchronized") state. +Default: 30. +.It Li timeout.established +Timeout for established ("synchronized") state. +Default: 60. +.It Li timeout.closed +Timeout for closed state. +Default: 0. +.El +.\" --- +.It Li state.tcp +State tracking parameters for TCP connections. +All timeout values are in seconds. +.Bl -tag -width "123456" +.It Li max_ack_win +Maximum allowed ACK window. +Default: 66000. +.It Li strict_order_rst +Enforce strict order RST. +Default: 1. +.\" - +.It Li timeout.new +Timeout for a new connection in "unsynchronized" state. +Default: 30. +.It Li timeout.established +Timeout for an established connection ("synchronized" state). +Default: 86400. +.It Li timeout.half_close +Timeout for the half-close TCP states. +Default: 3600. +.It Li timeout.close +Timeout for the full close TCP states. +Default: 10. +.It Li timeout.time_wait +Timeout for the TCP time-wait state. +Default: 240. +.El +.\" --- +.It Li portmap.min_port +Lower bound of the port range used when selecting the port +for dynamic NAT with port translation enabled. +Default: 1024 (inclusive; also the lowest allowed value). +.It Li portmap.max_port +Upper bound of the port range as described above. +Default: 49151 (inclusive; 65535 is the highest allowed value). +.\" --- +.El +.\" ----- +.Sh EXAMPLES +An example line in the +.Xr npf.conf 5 +configuration file: +.Bd -literal -offset indent +set state.tcp.strict_order_rst on # "on" can be used instead of 1 +set state.tcp.timeout.time_wait 0 # destroy the state immediately +.Ed +.\" ----- +.Sh SEE ALSO +.Xr libnpf 3 , +.Xr npfkern 3 , +.Xr bpfjit 4 , +.Xr npf.conf 5 , +.Xr pcap-filter 7 , +.Xr npfctl 8 +.\" ----- +.Sh AUTHORS +NPF +was designed and implemented by +.An Mindaugas Rasiukevicius . diff --git a/static/netbsd/man7/npf.7 b/static/netbsd/man7/npf.7 new file mode 100644 index 00000000..1425cd7e --- /dev/null +++ b/static/netbsd/man7/npf.7 @@ -0,0 +1,99 @@ +.\" $NetBSD: npf.7,v 1.7 2019/08/11 22:27:15 gutteridge Exp $ +.\" +.\" Copyright (c) 2009-2014 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This material is based upon work partially supported by The +.\" NetBSD Foundation under a contract with Mindaugas Rasiukevicius. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 11, 2019 +.Dt NPF 7 +.Os +.Sh NAME +.Nm NPF +.Nd NetBSD packet filter +.\" ----- +.Sh DESCRIPTION +.Nm +is a layer 3 packet filter, supporting IPv4 and IPv6 as well as +layer 4 protocols such as TCP, UDP, and ICMP. +It was designed with a focus on high performance, scalability, and +modularity. +.\" ----- +.Sh FEATURES +.Nm +offers the traditional set of features provided by packet filters. +Some key features are: +.Bl -bullet -offset indent +.It +Stateful inspection (connection tracking). +.It +Network address translation (NAT). +This includes static (stateless) and dynamic (stateful) translation, +port translation, bi-directional NAT, etc. +.It +IPv6-to-IPv6 network prefix translation (NPTv6). +.It +Tables for efficient IP sets. +.It +Application Level Gateways (e.g., to support traceroute). +.It +Use of BPF with just-in-time (JIT) compilation. +.It +Rule procedures and a framework for +.Nm +extensions. +.It +Traffic normalisation (extension). +.It +Packet logging (extension). +.El +.Pp +For a full set of features and their description, see the +.Nm +documentation website and other manual pages. +.\" ----- +.Sh SEE ALSO +.Xr libnpf 3 , +.Xr bpf 4 , +.Xr bpfjit 4 , +.Xr npf.conf 5 , +.Xr npf-params 7 , +.Xr pcap-filter 7 , +.Xr npfctl 8 , +.Xr npfd 8 +.Pp +.Lk https://github.com/rmind/npf/ "NPF project page" +.Pp +.Lk http://rmind.github.io/npf/ "NPF documentation website" +.Sh HISTORY +.Nm +was written from scratch in 2009 and is distributed under the +2-clause BSD license. +It first appeared in +.Nx 6.0 . +.Sh AUTHORS +.Nm +was designed and implemented by +.An Mindaugas Rasiukevicius . diff --git a/static/netbsd/man7/openssl-core.h.7 b/static/netbsd/man7/openssl-core.h.7 new file mode 100644 index 00000000..59e4bd51 --- /dev/null +++ b/static/netbsd/man7/openssl-core.h.7 @@ -0,0 +1,111 @@ +.\" $NetBSD: openssl-core.h.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL-CORE.H 7" +.TH OPENSSL-CORE.H 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +openssl/core.h \- OpenSSL Core types +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fI\fR header defines a number of public types that +are used to communicate between the OpenSSL libraries and +implementation providers. +These types are designed to minimise the need for intimate knowledge +of internal structures between the OpenSSL libraries and the providers. +.PP +The types are: +.IP \fBOSSL_DISPATCH\fR\|(3) 4 +.IX Item "OSSL_DISPATCH" +.PD 0 +.IP \fBOSSL_ITEM\fR\|(3) 4 +.IX Item "OSSL_ITEM" +.IP \fBOSSL_ALGORITHM\fR\|(3) 4 +.IX Item "OSSL_ALGORITHM" +.IP \fBOSSL_PARAM\fR\|(3) 4 +.IX Item "OSSL_PARAM" +.IP \fBOSSL_CALLBACK\fR\|(3) 4 +.IX Item "OSSL_CALLBACK" +.IP \fBOSSL_PASSPHRASE_CALLBACK\fR\|(3) 4 +.IX Item "OSSL_PASSPHRASE_CALLBACK" +.PD +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-core_dispatch.h\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The types described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/openssl-core_dispatch.h.7 b/static/netbsd/man7/openssl-core_dispatch.h.7 new file mode 100644 index 00000000..e4945eb5 --- /dev/null +++ b/static/netbsd/man7/openssl-core_dispatch.h.7 @@ -0,0 +1,109 @@ +.\" $NetBSD: openssl-core_dispatch.h.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL-CORE_DISPATCH.H 7" +.TH OPENSSL-CORE_DISPATCH.H 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +openssl/core_dispatch.h +\&\- OpenSSL provider dispatch numbers and function types +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fI\fR header defines all the operation +numbers, dispatch numbers and provider interface function types +currently available. +.PP +The operation and dispatch numbers are represented with macros, which +are named as follows: +.IP "operation numbers" 4 +.IX Item "operation numbers" +These macros have the form \f(CW\*(C`OSSL_OP_\fR\f(CIopname\fR\f(CW\*(C'\fR. +.IP "dipatch numbers" 4 +.IX Item "dipatch numbers" +These macros have the form \f(CW\*(C`OSSL_FUNC_\fR\f(CIopname\fR\f(CW_\fR\f(CIfuncname\fR\f(CW\*(C'\fR, where +\&\f(CW\*(C`\fR\f(CIopname\fR\f(CW\*(C'\fR is the same as in the macro for the operation this +function belongs to. +.PP +With every dispatch number, there is an associated function type. +.PP +For further information, please see the \fBprovider\fR\|(7) +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The types and macros described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/openssl-core_names.h.7 b/static/netbsd/man7/openssl-core_names.h.7 new file mode 100644 index 00000000..b3d0c20e --- /dev/null +++ b/static/netbsd/man7/openssl-core_names.h.7 @@ -0,0 +1,107 @@ +.\" $NetBSD: openssl-core_names.h.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL-CORE_NAMES.H 7" +.TH OPENSSL-CORE_NAMES.H 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +openssl/core_names.h \- OpenSSL provider parameter names +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fI\fR header defines a multitude of macros +for \fBOSSL_PARAM\fR\|(3) names, algorithm names and other known names used +with OpenSSL\*(Aqs providers, made available for practical purposes only. +.PP +Existing names are further described in the manuals for OpenSSL\*(Aqs +providers (see "SEE ALSO") and the manuals for each algorithm they +provide (listed in those provider manuals). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-FIPS\fR\|(7), +\&\fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The macros described here were added in OpenSSL 3.0. +.SH CAVEATS +.IX Header "CAVEATS" +\&\fIThis header file does not constitute a general registry of names\fR. +Providers that implement new algorithms are to be responsible for +their own parameter names. +.PP +However, authors of provider that implement their own variants of +algorithms that OpenSSL providers support will want to pay attention +to the names provided in this header to work in a compatible manner. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/openssl-env.7 b/static/netbsd/man7/openssl-env.7 new file mode 100644 index 00000000..aa90ccf5 --- /dev/null +++ b/static/netbsd/man7/openssl-env.7 @@ -0,0 +1,242 @@ +.\" $NetBSD: openssl-env.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL-ENV 7" +.TH OPENSSL-ENV 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +openssl\-env \- OpenSSL environment variables +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The OpenSSL libraries use environment variables to override the +compiled\-in default paths for various data. +To avoid security risks, the environment is usually not consulted when +the executable is set\-user\-ID or set\-group\-ID. +.IP \fBCTLOG_FILE\fR 4 +.IX Item "CTLOG_FILE" +Specifies the path to a certificate transparency log list. +See \fBCTLOG_STORE_new\fR\|(3). +.IP \fBOPENSSL\fR 4 +.IX Item "OPENSSL" +Specifies the path to the \fBopenssl\fR executable. Used by +the \fBrehash\fR script (see "Script Configuration" in \fBopenssl\-rehash\fR\|(1)) +and by the \fBCA.pl\fR script (see "NOTES" in \fBCA.pl\fR\|(1) +.IP "\fBOPENSSL_CONF\fR, \fBOPENSSL_CONF_INCLUDE\fR" 4 +.IX Item "OPENSSL_CONF, OPENSSL_CONF_INCLUDE" +Specifies the path to a configuration file and the directory for +included files. +See \fBconfig\fR\|(5). +.IP \fBOPENSSL_CONFIG\fR 4 +.IX Item "OPENSSL_CONFIG" +Specifies a configuration option and filename for the \fBreq\fR and \fBca\fR +commands invoked by the \fBCA.pl\fR script. +See \fBCA.pl\fR\|(1). +.IP \fBOPENSSL_ENGINES\fR 4 +.IX Item "OPENSSL_ENGINES" +Specifies the directory from which dynamic engines are loaded. +See \fBopenssl\-engine\fR\|(1). +.IP "\fBOPENSSL_MALLOC_FD\fR, \fBOPENSSL_MALLOC_FAILURES\fR" 4 +.IX Item "OPENSSL_MALLOC_FD, OPENSSL_MALLOC_FAILURES" +If built with debugging, this allows memory allocation to fail. +See \fBOPENSSL_malloc\fR\|(3). +.IP \fBOPENSSL_MODULES\fR 4 +.IX Item "OPENSSL_MODULES" +Specifies the directory from which cryptographic providers are loaded. +Equivalently, the generic \fB\-provider\-path\fR command\-line option may be used. +.IP \fBOPENSSL_TRACE\fR 4 +.IX Item "OPENSSL_TRACE" +By default the OpenSSL trace feature is disabled statically. +To enable it, OpenSSL must be built with tracing support, +which may be configured like this: \f(CW\*(C`./config enable\-trace\*(C'\fR +.Sp +Unless OpenSSL tracing support is generally disabled, +enable trace output of specific parts of OpenSSL libraries, by name. +This output usually makes sense only if you know OpenSSL internals well. +.Sp +The value of this environment variable is a comma\-separated list of names, +with the following available: +.IP \fBOPENSSL_RUNNING_UNIT_TESTS\fR 4 +.IX Item "OPENSSL_RUNNING_UNIT_TESTS" +This environment variable is used to flag the fact that unit tests are being run +(i.e. \`make test\`). It is used to detect when the OpenSSL should behave in a special +manner during unit tests (i.e. when unit tests are being run on fuzzing builds). It should +generally not be set by users. +.RS 4 +.IP \fBTRACE\fR 4 +.IX Item "TRACE" +Traces the OpenSSL trace API itself. +.IP \fBINIT\fR 4 +.IX Item "INIT" +Traces OpenSSL library initialization and cleanup. +.IP \fBTLS\fR 4 +.IX Item "TLS" +Traces the TLS/SSL protocol. +.IP \fBTLS_CIPHER\fR 4 +.IX Item "TLS_CIPHER" +Traces the ciphers used by the TLS/SSL protocol. +.IP \fBCONF\fR 4 +.IX Item "CONF" +Show details about provider and engine configuration. +.IP \fBENGINE_TABLE\fR 4 +.IX Item "ENGINE_TABLE" +The function that is used by RSA, DSA (etc) code to select registered +ENGINEs, cache defaults and functional references (etc), will generate +debugging summaries. +.IP \fBENGINE_REF_COUNT\fR 4 +.IX Item "ENGINE_REF_COUNT" +Reference counts in the ENGINE structure will be monitored with a line +of generated for each change. +.IP \fBPKCS5V2\fR 4 +.IX Item "PKCS5V2" +Traces PKCS#5 v2 key generation. +.IP \fBPKCS12_KEYGEN\fR 4 +.IX Item "PKCS12_KEYGEN" +Traces PKCS#12 key generation. +.IP \fBPKCS12_DECRYPT\fR 4 +.IX Item "PKCS12_DECRYPT" +Traces PKCS#12 decryption. +.IP \fBX509V3_POLICY\fR 4 +.IX Item "X509V3_POLICY" +Generates the complete policy tree at various points during X.509 v3 +policy evaluation. +.IP \fBBN_CTX\fR 4 +.IX Item "BN_CTX" +Traces BIGNUM context operations. +.IP \fBCMP\fR 4 +.IX Item "CMP" +Traces CMP client and server activity. +.IP \fBSTORE\fR 4 +.IX Item "STORE" +Traces STORE operations. +.IP \fBDECODER\fR 4 +.IX Item "DECODER" +Traces decoder operations. +.IP \fBENCODER\fR 4 +.IX Item "ENCODER" +Traces encoder operations. +.IP \fBREF_COUNT\fR 4 +.IX Item "REF_COUNT" +Traces decrementing certain ASN.1 structure references. +.IP \fBHTTP\fR 4 +.IX Item "HTTP" +Traces the HTTP client and server, such as messages being sent and received. +.RE +.RS 4 +.RE +.IP \fBOPENSSL_WIN32_UTF8\fR 4 +.IX Item "OPENSSL_WIN32_UTF8" +If set, then \fBUI_OpenSSL\fR\|(3) returns UTF\-8 encoded strings, rather than +ones encoded in the current code page, and +the \fBopenssl\fR\|(1) program also transcodes the command\-line parameters +from the current code page to UTF\-8. +This environment variable is only checked on Microsoft Windows platforms. +.IP \fBRANDFILE\fR 4 +.IX Item "RANDFILE" +The state file for the random number generator. +This should not be needed in normal use. +See \fBRAND_load_file\fR\|(3). +.IP "\fBSSL_CERT_DIR\fR, \fBSSL_CERT_FILE\fR" 4 +.IX Item "SSL_CERT_DIR, SSL_CERT_FILE" +Specify the default directory or file containing CA certificates. +See \fBSSL_CTX_load_verify_locations\fR\|(3). +.IP \fBTSGET\fR 4 +.IX Item "TSGET" +Additional arguments for the \fBtsget\fR\|(1) command. +.IP "\fBOPENSSL_ia32cap\fR, \fBOPENSSL_sparcv9cap\fR, \fBOPENSSL_ppccap\fR, \fBOPENSSL_armcap\fR, \fBOPENSSL_s390xcap\fR, \fBOPENSSL_riscvcap\fR" 4 +.IX Item "OPENSSL_ia32cap, OPENSSL_sparcv9cap, OPENSSL_ppccap, OPENSSL_armcap, OPENSSL_s390xcap, OPENSSL_riscvcap" +OpenSSL supports a number of different algorithm implementations for +various machines and, by default, it determines which to use based on the +processor capabilities and run time feature enquiry. These environment +variables can be used to exert more control over this selection process. +See \fBOPENSSL_ia32cap\fR\|(3), \fBOPENSSL_ppccap\fR\|(3), \fBOPENSSL_riscvcap\fR\|(3), +and \fBOPENSSL_s390xcap\fR\|(3). +.IP "\fBNO_PROXY\fR, \fBHTTPS_PROXY\fR, \fBHTTP_PROXY\fR" 4 +.IX Item "NO_PROXY, HTTPS_PROXY, HTTP_PROXY" +Specify a proxy hostname. +See \fBOSSL_HTTP_parse_url\fR\|(3). +.IP \fBQLOGDIR\fR 4 +.IX Item "QLOGDIR" +Specifies a QUIC qlog output directory. See \fBopenssl\-qlog\fR\|(7). +.IP \fBOSSL_QFILTER\fR 4 +.IX Item "OSSL_QFILTER" +Used to set a QUIC qlog filter specification. See \fBopenssl\-qlog\fR\|(7). +.IP \fBSSLKEYLOGFILE\fR 4 +.IX Item "SSLKEYLOGFILE" +Used to produce the standard format output file for SSL key logging. Optionally +set this variable to a filename to log all secrets produced by SSL connections. +Note, use of the environment variable is predicated on configuring OpenSSL at +build time with the enable\-sslkeylog feature. The file format standard can be +found at . +Note: the use of \fBSSLKEYLOGFILE\fR poses an explicit security risk. By recording +the exchanged keys during an SSL session, it allows any available party with +read access to the file to decrypt application traffic sent over that session. +Use of this feature should be restricted to test and debug environments only. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/openssl-glossary.7 b/static/netbsd/man7/openssl-glossary.7 new file mode 100644 index 00000000..e59076b6 --- /dev/null +++ b/static/netbsd/man7/openssl-glossary.7 @@ -0,0 +1,264 @@ +.\" $NetBSD: openssl-glossary.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL-GLOSSARY 7" +.TH OPENSSL-GLOSSARY 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +openssl\-glossary \- An OpenSSL Glossary +.SH DESCRIPTION +.IX Header "DESCRIPTION" +.IP Algorithm 4 +.IX Item "Algorithm" +Cryptographic primitives such as the SHA256 digest, or AES encryption are +referred to in OpenSSL as "algorithms". There can be more than one +implementation for any given algorithm available for use. +.Sp +\&\fBcrypto\fR\|(7) +.IP "ASN.1, ASN1" 4 +.IX Item "ASN.1, ASN1" +ASN.1 ("Abstract Syntax Notation One") is a notation for describing abstract +types and values. It is defined in the ITU\-T documents X.680 to X.683: +.Sp +, +, +, + +.IP "Base Provider" 4 +.IX Item "Base Provider" +An OpenSSL Provider that contains encoders and decoders for OpenSSL keys. All +the algorithm implementations in the Base Provider are also available in the +Default Provider. +.Sp +\&\fBOSSL_PROVIDER\-base\fR\|(7) +.IP Decoder 4 +.IX Item "Decoder" +A decoder is a type of algorithm used for decoding keys and parameters from some +external format such as PEM or DER. +.Sp +\&\fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3) +.IP "Default Provider" 4 +.IX Item "Default Provider" +An OpenSSL Provider that contains the most common OpenSSL algorithm +implementations. It is loaded by default if no other provider is available. All +the algorithm implementations in the Base Provider are also available in the +Default Provider. +.Sp +\&\fBOSSL_PROVIDER\-default\fR\|(7) +.IP "DER (""Distinguished Encoding Rules"")" 4 +.IX Item "DER (""Distinguished Encoding Rules"")" +DER is a binary encoding of data, structured according to an ASN.1 +specification. This is a common encoding used for cryptographic objects +such as private and public keys, certificates, CRLs, ... +.Sp +It is defined in ITU\-T document X.690: +.Sp + +.IP Encoder 4 +.IX Item "Encoder" +An encoder is a type of algorithm used for encoding keys and parameters to some +external format such as PEM or DER. +.Sp +\&\fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3) +.IP "Explicit Fetching" 4 +.IX Item "Explicit Fetching" +Explicit Fetching is a type of Fetching (see Fetching). Explicit Fetching is +where a function call is made to obtain an algorithm object representing an +implementation such as \fBEVP_MD_fetch\fR\|(3) or \fBEVP_CIPHER_fetch\fR\|(3) +.IP Fetching 4 +.IX Item "Fetching" +Fetching is the process of looking through the available algorithm +implementations, applying selection criteria (via a property query string), and +finally choosing the implementation that will be used. +.Sp +Also see Explicit Fetching and Implicit Fetching. +.Sp +\&\fBcrypto\fR\|(7) +.IP "FIPS Provider" 4 +.IX Item "FIPS Provider" +An OpenSSL Provider that contains OpenSSL algorithm implementations that have +been validated according to the FIPS 140\-2 standard. +.Sp +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7) +.IP "Implicit Fetching" 4 +.IX Item "Implicit Fetching" +Implicit Fetching is a type of Fetching (see Fetching). Implicit Fetching is +where an algorithm object with no associated implementation is used such as the +return value from \fBEVP_sha256\fR\|(3) or \fBEVP_aes_128_cbc\fR\|(3). With implicit +fetching an implementation is fetched automatically using default selection +criteria the first time the algorithm is used. +.IP "Legacy Provider" 4 +.IX Item "Legacy Provider" +An OpenSSL Provider that contains algorithm implementations that are considered +insecure or are no longer in common use. +.Sp +\&\fBOSSL_PROVIDER\-legacy\fR\|(7) +.IP "Library Context" 4 +.IX Item "Library Context" +A Library Context in OpenSSL is represented by the type \fBOSSL_LIB_CTX\fR. It can +be thought of as a scope within which configuration options apply. If an +application does not explicitly create a library context then the "default" +one is used. Many OpenSSL functions can take a library context as an argument. +A NULL value can always be passed to indicate the default library context. +.Sp +\&\fBOSSL_LIB_CTX\fR\|(3) +.IP MSBLOB 4 +.IX Item "MSBLOB" +MSBLOB is a Microsoft specific binary format for RSA and DSA keys, both +private and public. This form is never passphrase protected. +.IP "Null Provider" 4 +.IX Item "Null Provider" +An OpenSSL Provider that contains no algorithm implementations. This can be +useful to prevent the default provider from being automatically loaded in a +library context. +.Sp +\&\fBOSSL_PROVIDER\-null\fR\|(7) +.IP Operation 4 +.IX Item "Operation" +An operation is a group of OpenSSL functions with a common purpose such as +encryption, or digesting. +.Sp +\&\fBcrypto\fR\|(7) +.IP "PEM (""Privacy Enhanced Message"")" 4 +.IX Item "PEM (""Privacy Enhanced Message"")" +PEM is a format used for encoding of binary content into a mail and ASCII +friendly form. The content is a series of base64\-encoded lines, surrounded +by begin/end markers each on their own line. For example: +.Sp +.Vb 4 +\& \-\-\-\-\-BEGIN PRIVATE KEY\-\-\-\-\- +\& MIICdg.... +\& ... bhTQ== +\& \-\-\-\-\-END PRIVATE KEY\-\-\-\-\- +.Ve +.Sp +Optional header line(s) may appear after the begin line, and their existence +depends on the type of object being written or read. +.Sp +For all OpenSSL uses, the binary content is expected to be a DER encoded +structure. +.Sp +This is defined in IETF RFC 1421: +.Sp + +.IP PKCS#8 4 +.IX Item "PKCS#8" +PKCS#8 is a specification of ASN.1 structures that OpenSSL uses for storing +or transmitting any private key in a key type agnostic manner. +There are two structures worth noting for OpenSSL use, one that contains the +key data in unencrypted form (known as "PrivateKeyInfo") and an encrypted +wrapper structure (known as "EncryptedPrivateKeyInfo"). +.Sp +This is specified in RFC 5208: +.Sp + +.IP Property 4 +.IX Item "Property" +A property is a way of classifying and selecting algorithm implementations. +A property is a key/value pair expressed as a string. For example all algorithm +implementations in the default provider have the property "provider=default". +An algorithm implementation can have multiple properties defined against it. +.Sp +Also see Property Query String. +.Sp +\&\fBproperty\fR\|(7) +.IP "Property Query String" 4 +.IX Item "Property Query String" +A property query string is a string containing a sequence of properties that +can be used to select an algorithm implementation. For example the query string +"provider=example,foo=bar" will select algorithms from the "example" provider +that have a "foo" property defined for them with a value of "bar". +.Sp +Property Query Strings are used during fetching. See Fetching. +.Sp +\&\fBproperty\fR\|(7) +.IP Provider 4 +.IX Item "Provider" +A provider in OpenSSL is a component that groups together algorithm +implementations. Providers can come from OpenSSL itself or from third parties. +.Sp +\&\fBprovider\fR\|(7) +.IP PVK 4 +.IX Item "PVK" +PVK is a Microsoft specific binary format for RSA and DSA private keys. +This form may be passphrase protected. +.IP SubjectPublicKeyInfo 4 +.IX Item "SubjectPublicKeyInfo" +SubjectPublicKeyInfo is an ASN.1 structure that OpenSSL uses for storing and +transmitting any public key in a key type agnostic manner. +.Sp +This is specified as part of the specification for certificates, RFC 5280: +.Sp + +.SH HISTORY +.IX Header "HISTORY" +This glossary was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/openssl-qlog.7 b/static/netbsd/man7/openssl-qlog.7 new file mode 100644 index 00000000..c229dc68 --- /dev/null +++ b/static/netbsd/man7/openssl-qlog.7 @@ -0,0 +1,279 @@ +.\" $NetBSD: openssl-qlog.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL-QLOG 7" +.TH OPENSSL-QLOG 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +openssl\-qlog \- OpenSSL qlog tracing functionality +.SH DESCRIPTION +.IX Header "DESCRIPTION" +OpenSSL has unstable support for generating logs in the qlog logging format, +which can be used to obtain diagnostic data for QUIC connections. The data +generated includes information on packets sent and received and the frames +contained within them, as well as loss detection and other events. +.PP +The qlog output generated by OpenSSL can be used to obtain diagnostic +visualisations of a given QUIC connection using tools such as \fBqvis\fR. +.PP +\&\fBWARNING:\fR The output of OpenSSL\*(Aqs qlog functionality uses an unstable format +based on a draft specification. qlog output is not subject to any format +stability or compatibility guarantees at this time, and \fBwill\fR change in +incompatible ways in future versions of OpenSSL. See \fBFORMAT STABILITY\fR below +for details. +.SH USAGE +.IX Header "USAGE" +When OpenSSL is built with qlog support, qlog is enabled at run time by setting +the standard \fBQLOGDIR\fR environment variable to point to a directory where qlog +files should be written. Once set, any QUIC connection established by OpenSSL +will have a qlog file written automatically to the specified directory. +.PP +Log files are generated in the \fI.sqlog\fR format based on JSON\-SEQ (RFC 7464). +.PP +The filenames of generated log files under the specified \fBQLOGDIR\fR use the +following structure: +.PP +.Vb 1 +\& {connection_odcid}_{vantage_point_type}.sqlog +.Ve +.PP +where \fB{connection_odcid}\fR is the lowercase hexadecimal encoding of a QUIC +connection\*(Aqs Original Destination Connection ID, which is the Destination +Connection ID used in the header of the first Initial packet sent as part of the +connection process, and \fB{vantage_point_type}\fR is either \f(CW\*(C`client\*(C'\fR or +\&\f(CW\*(C`server\*(C'\fR, reflecting the perspective of the endpoint producing the qlog output. +.PP +The qlog functionality can be disabled at OpenSSL build time using the +\&\fIno\-unstable\-qlog\fR configure flag. +.SH "SUPPORTED EVENT TYPES" +.IX Header "SUPPORTED EVENT TYPES" +The following event types are currently supported: +.IP \fBconnectivity:connection_started\fR 4 +.IX Item "connectivity:connection_started" +.PD 0 +.IP \fBconnectivity:connection_state_updated\fR 4 +.IX Item "connectivity:connection_state_updated" +.IP \fBconnectivity:connection_closed\fR 4 +.IX Item "connectivity:connection_closed" +.IP \fBtransport:parameters_set\fR 4 +.IX Item "transport:parameters_set" +.IP \fBtransport:packet_sent\fR 4 +.IX Item "transport:packet_sent" +.IP \fBtransport:packet_received\fR 4 +.IX Item "transport:packet_received" +.IP \fBrecovery:packet_lost\fR 4 +.IX Item "recovery:packet_lost" +.PD +.SH FILTERS +.IX Header "FILTERS" +By default, all supported event types are logged. The \fBOSSL_QFILTER\fR +environment variable can be used to configure a filter specification which +determines which event types are to be logged. Each event type can be turned on +and off individually. The filter specification is a space\-separated list of +terms listing event types to enable or disable. The terms are applied in order, +thus the effects of later terms override the effects of earlier terms. +.SS Examples +.IX Subsection "Examples" +Here are some example filter specifications: +.ie n .IP """*"" (or ""+*"")" 4 +.el .IP "\f(CW*\fR (or \f(CW+*\fR)" 4 +.IX Item "* (or +*)" +Enable all supported qlog event types. +.ie n .IP """\-*""" 4 +.el .IP \f(CW\-*\fR 4 +.IX Item "-*" +Disable all qlog event types. +.ie n .IP """* \-transport:packet_received""" 4 +.el .IP "\f(CW* \-transport:packet_received\fR" 4 +.IX Item "* -transport:packet_received" +Enable all qlog event types, but disable the \fBtransport:packet_received\fR event +type. +.ie n .IP """\-* transport:packet_sent""" 4 +.el .IP "\f(CW\-* transport:packet_sent\fR" 4 +.IX Item "-* transport:packet_sent" +Disable all qlog event types, except for the \fBtransport:packet_sent\fR event type. +.ie n .IP """\-* connectivity:* transport:parameters_set""" 4 +.el .IP "\f(CW\-* connectivity:* transport:parameters_set\fR" 4 +.IX Item "-* connectivity:* transport:parameters_set" +Disable all qlog event types, except for \fBtransport:parameters_set\fR and all +supported event types in the \fBconnectivity\fR category. +.SS "Filter Syntax Specification" +.IX Subsection "Filter Syntax Specification" +Formally, the format of the filter specification in ABNF is as follows: +.PP +.Vb 1 +\& filter = *filter\-term +\& +\& filter\-term = add\-sub\-term +\& +\& add\-sub\-term = ["\-" / "+"] specifier +\& +\& specifier = global\-specifier / qualified\-specifier +\& +\& global\-specifier = wildcard +\& +\& qualified\-specifier = component\-specifier ":" component\-specifier +\& +\& component\-specifier = name / wildcard +\& +\& wildcard = "*" +\& +\& name = 1*(ALPHA / DIGIT / "_" / "\-") +.Ve +.PP +Filter terms are interpreted as follows: +.ie n .IP """+*"" (or ""*"")" 4 +.el .IP "\f(CW+*\fR (or \f(CW*\fR)" 4 +.IX Item "+* (or *)" +Enables all event types. +.ie n .IP """\-*""" 4 +.el .IP \f(CW\-*\fR 4 +.IX Item "-*" +Disables all event types. +.ie n .IP """+foo:*"" (or ""foo:*"")" 4 +.el .IP "\f(CW+foo:*\fR (or \f(CWfoo:*\fR)" 4 +.IX Item "+foo:* (or foo:*)" +Enables all event types in the \fBfoo\fR category. +.ie n .IP """\-foo:*""" 4 +.el .IP \f(CW\-foo:*\fR 4 +.IX Item "-foo:*" +Disables all event types in the \fBfoo\fR category. +.ie n .IP """+foo:bar"" (or ""foo:bar"")" 4 +.el .IP "\f(CW+foo:bar\fR (or \f(CWfoo:bar\fR)" 4 +.IX Item "+foo:bar (or foo:bar)" +Enables a specific event type \fBfoo:bar\fR. +.ie n .IP """\-foo:bar""" 4 +.el .IP \f(CW\-foo:bar\fR 4 +.IX Item "-foo:bar" +Disables a specific event type \fBfoo:bar\fR. +.PP +Partial wildcard matches are not supported at this time. +.SS "Default Configuration" +.IX Subsection "Default Configuration" +If the \fBOSSL_QFILTER\fR environment variable is not set or set to the empty +string, this is equivalent to enabling all event types (i.e., it is equivalent +to a filter of \f(CW\*(C`*\*(C'\fR). Note that the \fBQLOGDIR\fR environment variable must also be +set to enable qlog. +.SH "FORMAT STABILITY" +.IX Header "FORMAT STABILITY" +The OpenSSL qlog functionality currently implements a draft version of the qlog +specification. Future revisions to the qlog specification in advance of formal +standardisation are expected to introduce incompatible and breaking changes to +the qlog format. The OpenSSL qlog functionality will transition to producing +output in this format in the future once standardisation is complete. +.PP +Because of this, the qlog output of OpenSSL \fBwill\fR change in incompatible and +breaking ways in the future, including in non\-major releases of OpenSSL. The +qlog output of OpenSSL is considered unstable and not subject to any format +stability or compatibility guarantees at this time. +.PP +Users of the OpenSSL qlog functionality must be aware that the output may change +arbitrarily between releases and that the preservation of compatibility with any +given tool between releases is not guaranteed. +.SS Aims +.IX Subsection "Aims" +The OpenSSL draft qlog functionality is primarily intended for use in +conjunction with the qvis tool . In terms of +format compatibility, the output format of the OpenSSL qlog functionality is +expected to track what is supported by qvis. As such, future changes to the +output of the OpenSSL qlog functionality are expected to track changes in qvis +as they occur, and reflect the versions of qlog currently supported by qvis. +.PP +This means that prior to the finalisation of the qlog standard, in the event of +a disparity between the current draft and what qvis supports, the OpenSSL qlog +functionality will generally aim for qvis compatibility over compliance with the +latest draft. +.PP +As such, OpenSSL\*(Aqs qlog functionality currently implements qlog version 0.3 as +defined in \fBdraft\-ietf\-quic\-qlog\-main\-schema\-05\fR and +\&\fBdraft\-ietf\-quic\-qlog\-quic\-events\-04\fR. These revisions are intentionally used +instead of more recent revisions due to their qvis compatibility. +.SH LIMITATIONS +.IX Header "LIMITATIONS" +The OpenSSL implementation of qlog currently has the following limitations: +.IP \(bu 4 +Not all event types defined by the draft specification are implemented. +.IP \(bu 4 +Only the JSON\-SEQ (\fB.sqlog\fR) output format is supported. +.IP \(bu 4 +Only the \fBQLOGDIR\fR environment variable is supported for configuring the qlog +output directory. The standard \fBQLOGFILE\fR environment variable is not +supported. +.IP \(bu 4 +There is no API for programmatically enabling or controlling the qlog +functionality. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-quic\fR\|(7), \fBopenssl\-env\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/openssl-quic-concurrency.7 b/static/netbsd/man7/openssl-quic-concurrency.7 new file mode 100644 index 00000000..080efca6 --- /dev/null +++ b/static/netbsd/man7/openssl-quic-concurrency.7 @@ -0,0 +1,321 @@ +.\" $NetBSD: openssl-quic-concurrency.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL-QUIC-CONCURRENCY 7" +.TH OPENSSL-QUIC-CONCURRENCY 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +openssl\-quic\-concurrency \- OpenSSL QUIC Concurrency Model +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A QUIC domain is a group of QUIC resources such as listeners (see +\&\fBSSL_new_listener\fR\|(3)) and connections which share common event processing +resources, such as internal pollers, timers and locks. All usage of OpenSSL QUIC +happens inside a QUIC domain. +.PP +These resources can be accessed and used concurrently depending on the +circumstances. This man page discusses the available concurrency models and how +they can be used. +.SH "EXPLICIT AND IMPLICIT QUIC DOMAINS" +.IX Header "EXPLICIT AND IMPLICIT QUIC DOMAINS" +A QUIC domain is instantiated either explicitly (\fBSSL_new_domain\fR\|(3)) or +implicitly by calling \fBSSL_new\fR\|(3) or \fBSSL_new_listener\fR\|(3): +.IP \(bu 4 +An explicit QUIC domain is created by and visible to the application as a QUIC +domain SSL object and has other QUIC SSL objects created underneath it, such as +listeners or connections. +.IP \(bu 4 +An implicit QUIC domain is one which is created internally due to the direct +creation of a QUIC connection or listener SSL object; the application does not +explicitly create a QUIC domain SSL object and never directly references the +domain. +.PP +Explicit creation of a QUIC domain provides the greatest level of control for an +application. Applications can use an implicit QUIC domain for ease of use and to +avoid needing to create a separate QUIC domain SSL object. +.PP +Regardless of whether a QUIC domain is explicitly created, the internal +processing model is the same and the application must choose an appropriate +concurrency model as discussed below. +.SH "CONCURRENCY MODELS" +.IX Header "CONCURRENCY MODELS" +The OpenSSL QUIC implementation supports multiple concurrency models to support +a wide variety of usage scenarios. +.PP +The available concurrency models are as follows: +.IP \(bu 4 +The \fBSingle\-Threaded Concurrency Model (SCM)\fR, which supports only +application\-synchronised single\-threaded usage. +.IP \(bu 4 +The \fBContentive Concurrency Model (CCM)\fR, which supports multi\-threaded usage. +.IP \(bu 4 +The \fBThread\-Assisted Concurrency Model (TACM)\fR, which also supports +multi\-threaded usage and provides assistance to an application for handling QUIC +timer events. +.PP +The merits of these models are as follows: +.IP \(bu 4 +The \fBSingle\-Threaded Concurrency Model (SCM)\fR performs no locking or +synchronisation. It is entirely up to the application to synchronise access to +the QUIC domain and its subsidiary SSL objects. +.Sp +This concurrency model is also useful for an application which wants to use the +OpenSSL QUIC implementation as a pure state machine. +.IP \(bu 4 +The \fBContentive Concurrency Model (CCM)\fR performs automatic locking when making +API calls to SSL objects in a QUIC domain. This provides automatic +synchronisation for multi\-threaded usage of QUIC objects. For example, different +QUIC stream SSL objects in the same QUIC connection can be safely accessed from +different threads. +.Sp +This concurrency model adds the overhead of locking over the Single\-Threaded +Concurrency Model in order to support multi\-threaded usage, but provides limited +performance in highly contended multi\-threaded usage due to its simple approach. +However, it may still prove a good solution for a broad class of applications +which spend the majority of their time in application logic and not in QUIC I/O +processing. +.Sp +An advantage of this model relative to the more sophisticated concurrency models +below is that it does not create any OS threads. +.IP \(bu 4 +The \fBThread\-Assisted Concurrency Model (TACM)\fR is identical to the Contentive +Concurrency Model except that a thread is spun up in the background to ensure +that QUIC timer events are handled in a timely fashion. This ensures that QUIC +timeout events are handled even if an application does not periodically call +into the QUIC domain to ensure that any outstanding QUIC\-related timer or +network I/O events are handled. The assist thread contends for the same +resources like any other thread. However, handshake layer events (TLS) are never +processed by the assist thread. +.PP +The default concurrency model is CCM or TACM, depending on the \fBSSL_METHOD\fR +used with a \fBSSL_CTX\fR. Using \fBOSSL_QUIC_client_method\fR\|(3) results in a default +concurrency model of CCM, whereas using \fBOSSL_QUIC_client_thread_method\fR\|(3) +results in a default concurrency model of TACM. +.PP +Additional concurrency models may be offered in future releases of OpenSSL. +.SH "BLOCKING I/O CAPABILITIES" +.IX Header "BLOCKING I/O CAPABILITIES" +All of the supported concurrency models are capable of supporting blocking I/O +calls, where application\-level I/O calls (for example, to \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_write_ex\fR\|(3) on a QUIC stream SSL object) block until the request can be +serviced. This includes the use of \fBSSL_poll\fR\|(3) in a blocking fashion. +.PP +Supporting blocking API calls reliably with multi\-threaded usage requires the +creation of additional OS resources such as internal file descriptors to allow +threads to be woken when necessary. This creation of internal OS resources is +optional and may need to be explicitly requested by an application depending on +the chosen concurrency model. If this functionality is disabled, depending on +the chosen concurrency model, blocking API calls may not be available and calls +to \fBSSL_set_blocking_mode\fR\|(3) attempting to enable blocking mode may fail, +notwithstanding the following section. +.SS "Legacy Blocking Support Compatibility" +.IX Subsection "Legacy Blocking Support Compatibility" +OpenSSL 3.2 and 3.3 contained a buggy implementation of blocking QUIC I/O calls +which is only reliable under single\-threaded usage. This functionality is always +available in the Single\-Threaded Concurrency Model (SCM), where it works +reliably. +.PP +For compatibility reasons, this functionality is also available under the +default concurrency model if the application does not explicitly specify a +concurrency model or disable it. This is known as Legacy Blocking Compatibility +Mode, and its usage is not recommended for multi\-threaded applications. +.SH "RECOMMENDED USAGE" +.IX Header "RECOMMENDED USAGE" +New applications are advised to choose a concurrency model as follows: +.IP \(bu 4 +A purely single\-threaded application, or an application which wishes to use +OpenSSL QUIC as a state machine and manage synchronisation itself, should +explicitly select the SCM concurrency model. +.IP \(bu 4 +An application which wants to engage in multi\-threaded usage of different QUIC +connections or streams in the same QUIC domain should a) select the CCM or TACM +concurrency model and b) explicitly opt in or out of blocking I/O support +(depending on whether the application wishes to make blocking I/O calls), +disabling Legacy Blocking Compatibility Mode. +.Sp +An application should select the CCM concurrency model if the application can +guarantee that a QUIC domain will be serviced regularly (for example, because +the application can guarantee that the timeout returned by +\&\fBSSL_get_event_timeout\fR\|(3) will be handled). If an application is unable to do +this, it should select the TACM concurrency model. +.IP \(bu 4 +Applications should explicitly configure a concurrency model during +initialisation. +.SH "CONFIGURING A CONCURRENCY MODEL" +.IX Header "CONFIGURING A CONCURRENCY MODEL" +If using an explicit QUIC domain, a concurrency model is chosen when calling +\&\fBSSL_new_domain\fR\|(3) by specifying zero or more of the following flags: +.IP \fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR 4 +.IX Item "SSL_DOMAIN_FLAG_SINGLE_THREAD" +Specifying this flag configures the Single\-Threaded Concurrency Model (SCM). +.IP \fBSSL_DOMAIN_FLAG_MULTI_THREAD\fR 4 +.IX Item "SSL_DOMAIN_FLAG_MULTI_THREAD" +Specifying this flag configures the Contentive Concurrency Model (CCM) (unless +\&\fBSSL_DOMAIN_FLAG_THREAD_ASSISTED\fR is also specified). +.IP \fBSSL_DOMAIN_FLAG_THREAD_ASSISTED\fR 4 +.IX Item "SSL_DOMAIN_FLAG_THREAD_ASSISTED" +Specifying this flag configures the Thread\-Assisted Concurrency Model (TACM). +It implies \fBSSL_DOMAIN_FLAG_MULTI_THREAD\fR. +.IP \fBSSL_DOMAIN_FLAG_BLOCKING\fR 4 +.IX Item "SSL_DOMAIN_FLAG_BLOCKING" +Enable reliable support for blocking I/O calls, allocating whatever OS resources +are necessary to realise this. If this flag is specified, +\&\fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR is ignored. +.Sp +Details on the allocated OS resources can be found under "CONSUMPTION OF OS +RESOURCES" below. +.IP \fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR 4 +.IX Item "SSL_DOMAIN_FLAG_LEGACY_BLOCKING" +Enables legacy blocking compatibility mode. See "Legacy Blocking Support +Compatibility". +.PP +Mutually exclusive flag combinations result in an error (for example, combining +\&\fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR and \fBSSL_DOMAIN_FLAG_MULTI_THREADED\fR). +.PP +The concurrency model for a domain cannot be changed after the domain is +created. +.SS "Default Behaviour" +.IX Subsection "Default Behaviour" +If none of \fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR, \fBSSL_DOMAIN_FLAG_MULTI_THREAD\fR or +\&\fBSSL_DOMAIN_FLAG_THREAD_ASSISTED\fR are provided to \fBSSL_new_domain\fR\|(3) or +another constructor function which can accept the above flags, the default +concurrency model set on the \fBSSL_CTX\fR is used. This default can be set and get +using \fBSSL_CTX_set_domain_flags\fR\|(3) and \fBSSL_CTX_get_domain_flags\fR\|(3). Any +additional flags provided (for example, \fBSSL_DOMAIN_FLAG_BLOCCKING\fR) are added +to the set of inherited flags. +.PP +The default concurrency model set on a newly created \fBSSL_CTX\fR is determined as +follows: +.IP \(bu 4 +If an \fBSSL_METHOD\fR of \fBOSSL_QUIC_client_thread_method\fR\|(3) is used, the +Thread\-Assisted Concurrency Model (TACM) is used with the +\&\fBSSL_DOMAIN_FLAG_BLOCKING\fR flag. This provides reliable blocking functionality. +.IP \(bu 4 +Otherwise, if OpenSSL was built without threading support, the Single\-Threaded +Concurrency Model (SCM) is used, with the \fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR +flag. +.IP \(bu 4 +Otherwise, if an \fBSSL_METHOD\fR of \fBOSSL_QUIC_client_method\fR\|(3) is used, the +Contentive Concurrency Model (CCM) is used with the +\&\fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR flag. +.IP \(bu 4 +Otherwise, the Contentive Concurrency Model (CCM) is used. +.PP +The default concurrency model may vary between releases of OpenSSL. An +application may specify one or more of the domain flags above to ensure +consistent usage of a specific concurrency model between releases. +.SS "Configuration of Concurrency Models with Implicit QUIC Domains" +.IX Subsection "Configuration of Concurrency Models with Implicit QUIC Domains" +If an explicit QUIC domain is not explicitly created using \fBSSL_new_domain\fR\|(3), +an implicit QUIC domain is created when calling \fBSSL_new_listener\fR\|(3) or +\&\fBSSL_new\fR\|(3). Such a domain will use the default domain flags configured on the +\&\fBSSL_CTX\fR as described above. +.SH "CONSUMPTION OF OS RESOURCES" +.IX Header "CONSUMPTION OF OS RESOURCES" +If full blocking I/O support is selected using \fBSSL_DOMAIN_FLAG_BLOCKING\fR, at +least one socket, socket\-like OS handle or file descriptor must be allocated to +allow one thread to wake other threads which may be blocking in calls to OS +socket polling interfaces such as \fBselect\fR\|(2) or \fBpoll\fR\|(2). This is allocated +automatically internally by OpenSSL. +.PP +If the Thread\-Assisted Concurrency Model (TACM) is selected, a background thread +is spawned. This also implies \fBSSL_DOMAIN_FLAG_BLOCKING\fR and the above. +.PP +The internal consumption by OpenSSL of mutexes, condition variables, spin locks +or other similar thread synchronisation primitives is unspecified under all +concurrency models. +.PP +The internal consumption by OpenSSL of threads is unspecified under the +Thread\-Assisted Concurrency Model. +.PP +The internal consumption by OpenSSL of sockets, socket\-like OS handles or file +descriptors, or other resources as needed to support inter\-thread notification, +is unspecified under the Thread\-Assisted Concurrency Model or when using +\&\fBSSL_DOMAIN_FLAG_BLOCKING\fR. +.SH "BEHAVIOUR OF SSL OBJECTS" +.IX Header "BEHAVIOUR OF SSL OBJECTS" +A QUIC SSL object has blocking mode enabled by default where \fBall\fR of the +following criteria are met: +.IP \(bu 4 +\&\fBSSL_DOMAIN_FLAG_BLOCKING\fR or \fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR is enabled; +and +.IP \(bu 4 +The QUIC connection is being used with network read and write BIOs which expose +supported poll descriptors. See \fBopenssl\-quic\fR\|(7) for details. +.PP +In all other cases, a QUIC SSL object has blocking mode disabled by default. The +blocking mode can be changed explicitly using \fBSSL_set_blocking_mode\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-quic\fR\|(7), \fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3), +\&\fBOSSL_QUIC_client_thread_method\fR\|(3), \fBSSL_CTX_set_domain_flags\fR\|(3), +\&\fBSSL_new_domain\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/openssl-quic.7 b/static/netbsd/man7/openssl-quic.7 new file mode 100644 index 00000000..569b16b6 --- /dev/null +++ b/static/netbsd/man7/openssl-quic.7 @@ -0,0 +1,795 @@ +.\" $NetBSD: openssl-quic.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL-QUIC 7" +.TH OPENSSL-QUIC 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +openssl\-quic \- OpenSSL QUIC +.SH DESCRIPTION +.IX Header "DESCRIPTION" +OpenSSL 3.2 and later features support for the QUIC transport protocol. +You can use OpenSSL\*(Aqs QUIC capabilities for both client and server applications. +This man page describes how to let applications use the QUIC protocol using the +libssl API. +.PP +The QUIC protocol maps to the standard SSL API. A QUIC connection is represented +by an SSL object in the same way that a TLS connection is. Only minimal changes +are needed to existing applications which use libssl API to bring QUIC protocol +support in. QUIC clients can use \fBOSSL_QUIC_client_method\fR\|(3) or +\&\fBOSSL_QUIC_client_thread_method\fR\|(3) with \fBSSL_CTX_new\fR\|(3). See below for more +details about the difference between the two. For servers, there is only one +option: SSL method \fBOSSL_QUIC_server_method\fR\|(3) with \fBSSL_CTX_new\fR\|(3). +.PP +The remainder of this man page discusses, in order: +.IP \(bu 4 +Default stream mode versus multi\-stream mode for clients; +.IP \(bu 4 +The changes to existing libssl APIs which are driven by QUIC\-related +implementation requirements, which existing applications should bear in mind; +.IP \(bu 4 +Aspects which must be considered by existing applications when adopting QUIC, +including potential changes which may be needed. +.IP \(bu 4 +Recommended usage approaches for new applications. +.IP \(bu 4 +New, QUIC\-specific APIs. +.SH "CLIENT MODES OF OPERATION" +.IX Header "CLIENT MODES OF OPERATION" +When a client creates a QUIC connection, by default, it operates in default +stream mode, which is intended to provide compatibility with existing non\-QUIC +application usage patterns. In this mode, the connection has a single stream +associated with it. Calls to \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) on the QUIC +connection SSL object read and write from that stream. Whether the stream is +client\-initiated or server\-initiated from a QUIC perspective depends on whether +\&\fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called first. +.PP +Default stream mode is primarily for compatibility with existing applications. +For new applications utilizing QUIC, it\*(Aqs recommended to disable this mode and +instead adopt the multi\-stream API. See the RECOMMENDATIONS FOR NEW APPLICATIONS +section for more details. +.SS "Default Stream Mode" +.IX Subsection "Default Stream Mode" +A QUIC client connection can be used in either default stream mode or +multi\-stream mode. By default, a newly created QUIC connection SSL object uses +default stream mode. +.PP +In default stream mode, a stream is implicitly created and bound to the QUIC +connection SSL object; \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) calls to the QUIC +connection SSL object work by default and are mapped to that stream. +.PP +When default stream mode is used, any API function which can be called on a QUIC +stream SSL object can also be called on a QUIC connection SSL object, in which +case it affects the default stream bound to the connection. +.PP +The identity of a QUIC stream, including its stream ID, varies depending on +whether a stream is client\-initiated or server\-initiated. In default stream +mode, if a client application calls \fBSSL_read\fR\|(3) first before any call to +\&\fBSSL_write\fR\|(3) on the connection, it is assumed that the application protocol +is using a server\-initiated stream, and the \fBSSL_read\fR\|(3) call will not +complete (either blocking, or failing appropriately if nonblocking mode is +configured) until the server initiates a stream. Conversely, if the client +application calls \fBSSL_write\fR\|(3) before any call to \fBSSL_read\fR\|(3) on the +connection, it is assumed that a client\-initiated stream is to be used +and such a stream is created automatically. +.PP +Default stream mode is intended to aid compatibility with legacy applications. +New applications adopting QUIC should use multi\-stream mode, described below, +and avoid use of the default stream functionality. +.PP +It is possible to use additional streams in default stream mode using +\&\fBSSL_new_stream\fR\|(3) and \fBSSL_accept_stream\fR\|(3); note that the default incoming +stream policy will need to be changed using \fBSSL_set_incoming_stream_policy\fR\|(3) +in order to use \fBSSL_accept_stream\fR\|(3) in this case. However, applications +using additional streams are strongly recommended to use multi\-stream mode +instead. +.PP +Calling \fBSSL_new_stream\fR\|(3) or \fBSSL_accept_stream\fR\|(3) before a default stream +has been associated with the QUIC connection SSL object will inhibit future +creation of a default stream. +.SS "Multi\-Stream Mode" +.IX Subsection "Multi-Stream Mode" +The recommended usage mode for new applications adopting QUIC is multi\-stream +mode, in which no default stream is attached to the QUIC connection SSL object +and attempts to call \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) on the QUIC connection +SSL object fail. Instead, an application calls \fBSSL_new_stream\fR\|(3) or +\&\fBSSL_accept_stream\fR\|(3) to create individual stream SSL objects for sending and +receiving application data using \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3). +.PP +To use multi\-stream mode, call \fBSSL_set_default_stream_mode\fR\|(3) with an +argument of \fBSSL_DEFAULT_STREAM_MODE_NONE\fR; this function must be called prior +to initiating the connection. The default stream mode cannot be changed after +initiating a connection. +.PP +When multi\-stream mode is used, meaning that no default stream is associated +with the connection, calls to API functions which are defined as operating on a +QUIC stream fail if called on the QUIC connection SSL object. For example, calls +such as \fBSSL_write\fR\|(3) or \fBSSL_get_stream_id\fR\|(3) will fail. +.SH "CHANGES TO EXISTING APIS" +.IX Header "CHANGES TO EXISTING APIS" +Most SSL APIs, such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3), function as they do +for TLS connections and do not have changed semantics, with some exceptions. The +changes to the semantics of existing APIs are as follows: +.IP \(bu 4 +Since QUIC uses UDP, \fBSSL_set_bio\fR\|(3), \fBSSL_set0_rbio\fR\|(3) and +\&\fBSSL_set0_wbio\fR\|(3) function as before, but must now receive a BIO with datagram +semantics. There are broadly four options for applications to use as a network +BIO: +.RS 4 +.IP \(bu 4 +\&\fBBIO_s_datagram\fR\|(3), recommended for most applications, replaces +\&\fBBIO_s_socket\fR\|(3) and provides a UDP socket. +.IP \(bu 4 +\&\fBBIO_s_dgram_pair\fR\|(3) provides BIO pair\-like functionality but with datagram +semantics, and is recommended for existing applications which use a BIO pair or +memory BIO to manage libssl\*(Aqs communication with the network. +.IP \(bu 4 +\&\fBBIO_s_dgram_mem\fR\|(3) provides a simple memory BIO\-like interface but with +datagram semantics. Unlike \fBBIO_s_dgram_pair\fR\|(3), it is unidirectional. +.IP \(bu 4 +An application may also choose to implement a custom BIO. The new +\&\fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) APIs must be supported. +.RE +.RS 4 +.RE +.IP \(bu 4 +\&\fBSSL_set_fd\fR\|(3), \fBSSL_set_rfd\fR\|(3) and \fBSSL_set_wfd\fR\|(3) traditionally +instantiate a \fBBIO_s_socket\fR\|(3). For QUIC, these functions instead instantiate +a \fBBIO_s_datagram\fR\|(3). This is equivalent to instantiating a +\&\fBBIO_s_datagram\fR\|(3) and using \fBSSL_set0_rbio\fR\|(3) and \fBSSL_set0_wbio\fR\|(3). +.IP \(bu 4 +Traditionally, whether the application\-level I/O APIs (such as \fBSSL_read\fR\|(3) +and \fBSSL_write\fR\|(3) operated in a blocking fashion was directly correlated with +whether the underlying network socket was configured in a blocking fashion. This +is no longer the case; applications must explicitly configure the desired +application\-level blocking mode using \fBSSL_set_blocking_mode\fR\|(3). See +\&\fBSSL_set_blocking_mode\fR\|(3) for details. +.IP \(bu 4 +Network\-level I/O must always be performed in a nonblocking manner. The +application can still enjoy blocking semantics for calls to application\-level +I/O functions such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3), but the underlying +network BIO provided to QUIC (such as a \fBBIO_s_datagram\fR\|(3)) must be configured +in nonblocking mode. For application\-level blocking functionality, see +\&\fBSSL_set_blocking_mode\fR\|(3). +.IP \(bu 4 +\&\fBBIO_new_ssl_connect\fR\|(3) has been changed to automatically use a +\&\fBBIO_s_datagram\fR\|(3) when used with QUIC, therefore applications which use this +do not need to change the BIO they use. +.IP \(bu 4 +\&\fBBIO_new_buffer_ssl_connect\fR\|(3) cannot be used with QUIC and applications must +change to use \fBBIO_new_ssl_connect\fR\|(3) instead. +.IP \(bu 4 +\&\fBSSL_shutdown\fR\|(3) has significant changes in relation to how QUIC connections +must be shut down. In particular, applications should be advised that the full +RFC\-conformant QUIC shutdown process may take an extended amount of time. This +may not be suitable for short\-lived processes which should exit immediately +after their usage of a QUIC connection is completed. A rapid shutdown mode +is available for such applications. For details, see \fBSSL_shutdown\fR\|(3). +.IP \(bu 4 +\&\fBSSL_want\fR\|(3), \fBSSL_want_read\fR\|(3) and \fBSSL_want_write\fR\|(3) no longer reflect +the I/O state of the network BIO passed to the QUIC SSL object, but instead +reflect the flow control state of the QUIC stream associated with the SSL +object. +.Sp +When used in nonblocking mode, \fBSSL_ERROR_WANT_READ\fR indicates that the +receive part of a QUIC stream does not currently have any more data available to +be read, and \fBSSL_ERROR_WANT_WRITE\fR indicates that the stream\*(Aqs internal buffer +is full. +.Sp +To determine if the QUIC implementation currently wishes to be informed of +incoming network datagrams, use the new function \fBSSL_net_read_desired\fR\|(3); +likewise, to determine if the QUIC implementation currently wishes to be +informed when it is possible to transmit network datagrams, use the new function +\&\fBSSL_net_write_desired\fR\|(3). Only applications which wish to manage their own event +loops need to use these functions; see \fBAPPLICATION\-DRIVEN EVENT LOOPS\fR for +further discussion. +.IP \(bu 4 +The use of ALPN is mandatory when using QUIC. Attempts to connect without +configuring ALPN will fail. For information on how to configure ALPN, see +\&\fBSSL_set_alpn_protos\fR\|(3). +.IP \(bu 4 +Whether QUIC operates in a client or server mode is determined by the +\&\fBSSL_METHOD\fR used, rather than by calls to \fBSSL_set_connect_state\fR\|(3) or +\&\fBSSL_set_accept_state\fR\|(3). It is not necessary to call either of +\&\fBSSL_set_connect_state\fR\|(3) or \fBSSL_set_accept_state\fR\|(3) before connecting, but +if either of these are called, the function called must be congruent with the +\&\fBSSL_METHOD\fR being used. +.IP \(bu 4 +The \fBSSL_set_min_proto_version\fR\|(3) and \fBSSL_set_max_proto_version\fR\|(3) APIs are +not used and the values passed to them are ignored, as OpenSSL QUIC currently +always uses TLS 1.3. +.IP \(bu 4 +The following libssl functionality is not available when used with QUIC. +.RS 4 +.IP \(bu 4 +Async functionality +.IP \(bu 4 +\&\fBSSL_MODE_AUTO_RETRY\fR +.IP \(bu 4 +Record Padding and Fragmentation (\fBSSL_set_block_padding\fR\|(3), etc.) +.IP \(bu 4 +\&\fBSSL_stateless\fR\|(3) support +.IP \(bu 4 +SRTP functionality +.IP \(bu 4 +TLSv1.3 Early Data +.IP \(bu 4 +TLS Next Protocol Negotiation cannot be used and is superseded by ALPN, which +must be used instead. The use of ALPN is mandatory with QUIC. +.IP \(bu 4 +Post\-Handshake Client Authentication is not available as QUIC prohibits its use. +.IP \(bu 4 +QUIC requires the use of TLSv1.3 or later, therefore functionality only relevant +to older TLS versions is not available. +.IP \(bu 4 +Some cipher suites which are generally available for TLSv1.3 are not available +for QUIC, such as \fBTLS_AES_128_CCM_8_SHA256\fR. Your application may need to +adjust the list of acceptable cipher suites it passes to libssl. +.IP \(bu 4 +CCM mode is not currently supported. +.RE +.RS 4 +.Sp +The following libssl functionality is also not available when used with QUIC, +but calls to the relevant functions are treated as no\-ops: +.IP \(bu 4 +Readahead (\fBSSL_set_read_ahead\fR\|(3), etc.) +.RE +.RS 4 +.RE +.SH "CONSIDERATIONS FOR EXISTING APPLICATIONS" +.IX Header "CONSIDERATIONS FOR EXISTING APPLICATIONS" +Existing applications seeking to adopt QUIC should apply the following list to +determine what changes they will need to make: +.IP \(bu 4 +A client application wishing to use QUIC must use \fBOSSL_QUIC_client_method\fR\|(3) +or \fBOSSL_QUIC_client_thread_method\fR\|(3) as its SSL method. For more information +on the differences between these two methods, see +\&\fBTHREAD ASSISTED MODE\fR. +.IP \(bu 4 +A server application wishing to use QUIC must use \fBOSSL_QUIC_server_method\fR\|(3). +The server can then accept new connections with \fBSSL_accept_connection\fR\|(3). +.IP \(bu 4 +Determine how to provide QUIC with network access. Determine which of the below +apply for your application: +.RS 4 +.IP \(bu 4 +Your application uses \fBBIO_s_socket\fR\|(3) to construct a BIO which is passed to +the SSL object to provide it with network access. +.Sp +Changes needed: Change your application to use \fBBIO_s_datagram\fR\|(3) instead when +using QUIC. The socket must be configured in nonblocking mode. You may or may +not need to use \fBSSL_set1_initial_peer_addr\fR\|(3) to set the initial peer +address; see the \fBQUIC\-SPECIFIC APIS\fR section for details. +.IP \(bu 4 +Your application uses \fBBIO_new_ssl_connect\fR\|(3) to +construct a BIO which is passed to the SSL object to provide it with network +access. +.Sp +Changes needed: No changes needed. Use of QUIC is detected automatically and a +datagram socket is created instead of a normal TCP socket. +.IP \(bu 4 +Your application uses any other I/O strategy in this list but combines it with a +\&\fBBIO_f_buffer\fR\|(3), for example using \fBBIO_push\fR\|(3). +.Sp +Changes needed: Disable the usage of \fBBIO_f_buffer\fR\|(3) when using QUIC. Usage +of such a buffer is incompatible with QUIC as QUIC requires datagram semantics +in its interaction with the network. +.IP \(bu 4 +Your application uses a BIO pair to cause the SSL object to read and write +network traffic to a memory buffer. Your application manages the transmission +and reception of buffered data itself in a way unknown to libssl. +.Sp +Changes needed: Switch from using a conventional BIO pair to using +\&\fBBIO_s_dgram_pair\fR\|(3) instead, which has the necessary datagram semantics. You +will need to modify your application to transmit and receive using a UDP socket +and to use datagram semantics when interacting with the \fBBIO_s_dgram_pair\fR\|(3) +instance. +.IP \(bu 4 +Your application uses a custom BIO method to provide the SSL object with network +access. +.Sp +Changes needed: The custom BIO must be re\-architected to have datagram +semantics. \fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) must be implemented. These +calls must operate in a nonblocking fashion. Optionally, implement the +\&\fBBIO_get_rpoll_descriptor\fR\|(3) and \fBBIO_get_wpoll_descriptor\fR\|(3) methods if +desired. Implementing these methods is required if blocking semantics at the SSL +API level are desired. +.RE +.RS 4 +.RE +.IP \(bu 4 +An application must explicitly configure whether it wishes to use the SSL APIs +in blocking mode or not. Traditionally, an SSL object has automatically operated +in blocking or nonblocking mode based on whether the underlying network BIO +operates in blocking or nonblocking mode. QUIC requires the use of a +nonblocking network BIO, therefore the blocking mode at the application level +can be explicitly configured by the application using the new +\&\fBSSL_set_blocking_mode\fR\|(3) API. The default mode is blocking. If an application +wishes to use the SSL object APIs at application level in a nonblocking manner, +it must add a call to \fBSSL_set_blocking_mode\fR\|(3) to disable blocking mode. +.IP \(bu 4 +If your client application does not choose to use thread assisted mode, it must +ensure that it calls an I/O function on the SSL object (for example, +\&\fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3)), or the new function \fBSSL_handle_events\fR\|(3), +regularly. If the SSL object is used in blocking mode, an ongoing blocking call +to an I/O function satisfies this requirement. This is required to ensure that +timer events required by QUIC are handled in a timely fashion. +.Sp +Most applications will service the SSL object by calling \fBSSL_read\fR\|(3) or +\&\fBSSL_write\fR\|(3) regularly. If an application does not do this, it should ensure +that \fBSSL_handle_events\fR\|(3) is called regularly. +.Sp +\&\fBSSL_get_event_timeout\fR\|(3) can be used to determine when +\&\fBSSL_handle_events\fR\|(3) must next be called. +.Sp +If the SSL object is being used with an underlying network BIO which is pollable +(such as \fBBIO_s_datagram\fR\|(3)), the application can use +\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3) to obtain +resources which can be used to determine when \fBSSL_handle_events\fR\|(3) should be +called due to network I/O. +.Sp +Client applications which use thread assisted mode do not need to be concerned +with this requirement, as the QUIC implementation ensures timeout events +are handled in a timely manner. See \fBTHREAD ASSISTED MODE\fR for details. +.IP \(bu 4 +Ensure that your usage of \fBSSL_want\fR\|(3), \fBSSL_want_read\fR\|(3) and +\&\fBSSL_want_write\fR\|(3) reflects the API changes described in \fBCHANGES TO EXISTING +APIS\fR. In particular, you should use these APIs to determine the ability of a +QUIC stream to receive or provide application data, not to to determine if +network I/O is required. +.IP \(bu 4 +Evaluate your application\*(Aqs use of \fBSSL_shutdown\fR\|(3) in light of the changes +discussed in \fBCHANGES TO EXISTING APIS\fR. Depending on whether your application +wishes to prioritise RFC conformance or rapid shutdown, consider using the new +\&\fBSSL_shutdown_ex\fR\|(3) API instead. See \fBQUIC\-SPECIFIC APIS\fR for details. +.SH "RECOMMENDED USAGE IN NEW APPLICATIONS" +.IX Header "RECOMMENDED USAGE IN NEW APPLICATIONS" +The recommended usage in new applications varies depending on three independent +design decisions: +.IP \(bu 4 +Whether the application will use blocking or nonblocking I/O at the application +level (configured using \fBSSL_set_blocking_mode\fR\|(3)). +.Sp +If the application does nonblocking I/O at the application level it can choose +to manage its own polling and event loop; see \fBAPPLICATION\-DRIVEN EVENT LOOPS\fR. +.IP \(bu 4 +Whether the application intends to give the QUIC implementation direct access to +a network socket (e.g. via \fBBIO_s_datagram\fR\|(3)) or whether it intends to buffer +transmitted and received datagrams via a \fBBIO_s_dgram_pair\fR\|(3) or custom BIO. +.Sp +The former is preferred where possible as it reduces latency to the network, +which enables QUIC to achieve higher performance and more accurate connection +round trip time (RTT) estimation. +.IP \(bu 4 +Whether thread assisted mode will be used (see \fBTHREAD ASSISTED MODE\fR). +.PP +Simple demos for QUIC usage under these various scenarios can be found at +. +.PP +Applications which wish to implement QUIC\-specific protocols should be aware of +the APIs listed under \fBQUIC\-SPECIFIC APIS\fR which provide access to +QUIC\-specific functionality. For example, \fBSSL_stream_conclude\fR\|(3) can be used +to indicate the end of the sending part of a stream, and \fBSSL_shutdown_ex\fR\|(3) +can be used to provide a QUIC application error code when closing a connection. +.PP +Regardless of the design decisions chosen above, it is recommended that new +applications avoid use of the default stream mode and use the multi\-stream API +by calling \fBSSL_set_default_stream_mode\fR\|(3); see the MODES OF OPERATION section +for details. +.SH "QUIC\-SPECIFIC APIS" +.IX Header "QUIC-SPECIFIC APIS" +This section details new APIs which are directly or indirectly related to QUIC. +For details on the operation of each API, see the referenced man pages. +.PP +The following SSL APIs are new but relevant to both QUIC and DTLS: +.IP \fBSSL_get_event_timeout\fR\|(3) 4 +.IX Item "SSL_get_event_timeout" +Determines when the QUIC implementation should next be woken up via a call to +\&\fBSSL_handle_events\fR\|(3) (or another I/O function such as \fBSSL_read\fR\|(3) or +\&\fBSSL_write\fR\|(3)), if ever. +.Sp +This can also be used with DTLS and supersedes \fBDTLSv1_get_timeout\fR\|(3) for new +usage. +.IP \fBSSL_handle_events\fR\|(3) 4 +.IX Item "SSL_handle_events" +This is a non\-specific I/O operation which makes a best effort attempt to +perform any pending I/O or timeout processing. It can be used to advance the +QUIC state machine by processing incoming network traffic, generating outgoing +network traffic and handling any expired timeout events. Most other I/O +functions on an SSL object, such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3), +implicitly perform event handling on the SSL object, so calling this function is +only needed if no other I/O function is to be called. +.Sp +This can also be used with DTLS and supersedes \fBDTLSv1_handle_timeout\fR\|(3) for +new usage. +.PP +The following SSL APIs are specific to QUIC: +.IP \fBSSL_new_listener\fR\|(3) 4 +.IX Item "SSL_new_listener" +Creates a listener SSL object, which differs from an ordinary SSL object in that +it is used to provide an abstraction for the acceptance of network connections +in a protocol\-agnostic manner. +.Sp +Currently, listener SSL objects are only supported for QUIC server usage or +client\-only usage. The listener interface may expand to support additional +protocols in the future. +.IP \fBSSL_new_listener_from\fR\|(3) 4 +.IX Item "SSL_new_listener_from" +Creates a listener SSL object which is subordinate to a QUIC domain SSL object +\&\fIssl\fR. See \fBSSL_new_domain\fR\|(3) and \fBopenssl\-quic\-concurrency\fR\|(7) for details +on QUIC domain SSL objects. +.IP \fBSSL_is_listener\fR\|(3) 4 +.IX Item "SSL_is_listener" +Returns 1 if and only if an SSL object is a listener SSL object. +.IP \fBSSL_get0_listener\fR\|(3) 4 +.IX Item "SSL_get0_listener" +Returns an SSL object pointer (potentially to the same object on which it is +called) or NULL. +.IP \fBSSL_listen\fR\|(3) 4 +.IX Item "SSL_listen" +Begin listening after a listener has been created. It is ordinarily not needed +to call this because it will be called automatically on the first call to +\&\fBSSL_accept_connection\fR\|(3). +.IP \fBSSL_accept_connection\fR\|(3) 4 +.IX Item "SSL_accept_connection" +Accepts a new incoming connection for a listener SSL object. A new SSL object +representing the accepted connection is created and returned on success. If no +incoming connection is available and the listener SSL object is configured in +nonblocking mode, NULL is returned. +.IP \fBSSL_get_accept_connection_queue_len\fR\|(3) 4 +.IX Item "SSL_get_accept_connection_queue_len" +Returns an informational value listing the number of connections waiting to be +popped from the queue via calls to \fBSSL_accept_connection()\fR. +.IP \fBSSL_new_from_listener\fR\|(3) 4 +.IX Item "SSL_new_from_listener" +Creates a client connection under a given listener SSL object. For QUIC, it is +also possible to use \fBSSL_new_from_listener()\fR in conjunction with a listener +which does accept incoming connections (i.e., which was not created using +\&\fBSSL_LISTENER_FLAG_NO_ACCEPT\fR), leading to a UDP network endpoint which has +both incoming and outgoing connections. +.IP \fBSSL_new_domain\fR\|(3) 4 +.IX Item "SSL_new_domain" +Creates a new QUIC event domain, represented as an SSL object. This is known as +a QUIC domain SSL object. The concept of a QUIC event domain is discussed in +detail in \fBopenssl\-quic\-concurrency\fR\|(7). +.IP \fBSSL_is_domain\fR\|(3) 4 +.IX Item "SSL_is_domain" +Returns 1 if an SSL object is a QUIC domain SSL object. +.IP \fBSSL_get0_domain\fR\|(3) 4 +.IX Item "SSL_get0_domain" +\&\fBSSL_get0_domain()\fR obtains a pointer to the QUIC domain SSL object in an SSL +object hierarchy (if any). +.IP "\fBSSL_set_blocking_mode\fR\|(3), \fBSSL_get_blocking_mode\fR\|(3)" 4 +.IX Item "SSL_set_blocking_mode, SSL_get_blocking_mode" +Configures whether blocking semantics are used at the application level. This +determines whether calls to functions such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) +will block. +.IP "\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3)" 4 +.IX Item "SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor" +These functions facilitate operation in nonblocking mode. +.Sp +When an SSL object is being used with an underlying network read BIO which +supports polling, \fBSSL_get_rpoll_descriptor\fR\|(3) outputs an OS resource which +can be used to synchronise on network readability events which should result in +a call to \fBSSL_handle_events\fR\|(3). \fBSSL_get_wpoll_descriptor\fR\|(3) works in an +analogous fashion for the underlying network write BIO. +.Sp +The poll descriptors provided by these functions should be used only when +\&\fBSSL_net_read_desired\fR\|(3) and \fBSSL_net_write_desired\fR\|(3) return 1, +respectively. +.IP "\fBSSL_net_read_desired\fR\|(3), \fBSSL_net_write_desired\fR\|(3)" 4 +.IX Item "SSL_net_read_desired, SSL_net_write_desired" +These functions facilitate operation in nonblocking mode and are used in +conjunction with \fBSSL_get_rpoll_descriptor\fR\|(3) and +\&\fBSSL_get_wpoll_descriptor\fR\|(3) respectively. They determine whether the +respective poll descriptor is currently relevant for the purposes of polling. +.IP \fBSSL_set1_initial_peer_addr\fR\|(3) 4 +.IX Item "SSL_set1_initial_peer_addr" +This function can be used to set the initial peer address for an outgoing QUIC +connection. This function must be used in the general case when creating an +outgoing QUIC connection; however, the correct initial peer address can be +autodetected in some cases. See \fBSSL_set1_initial_peer_addr\fR\|(3) for details. +.IP \fBSSL_shutdown_ex\fR\|(3) 4 +.IX Item "SSL_shutdown_ex" +This augments \fBSSL_shutdown\fR\|(3) by allowing an application error code to be +specified. It also allows an application to decide how quickly it wants a +shutdown to be performed, potentially by trading off strict RFC compliance. +.IP \fBSSL_stream_conclude\fR\|(3) 4 +.IX Item "SSL_stream_conclude" +This allows an application to indicate the normal end of the sending part of a +QUIC stream. This corresponds to the FIN flag in the QUIC RFC. The receiving +part of a stream remains usable. +.IP \fBSSL_stream_reset\fR\|(3) 4 +.IX Item "SSL_stream_reset" +This allows an application to indicate the non\-normal termination of the sending +part of a stream. This corresponds to the RESET_STREAM frame in the QUIC RFC. +.IP "\fBSSL_get_stream_write_state\fR\|(3) and \fBSSL_get_stream_read_state\fR\|(3)" 4 +.IX Item "SSL_get_stream_write_state and SSL_get_stream_read_state" +This allows an application to determine the current stream states for the +sending and receiving parts of a stream respectively. +.IP "\fBSSL_get_stream_write_error_code\fR\|(3) and \fBSSL_get_stream_read_error_code\fR\|(3)" 4 +.IX Item "SSL_get_stream_write_error_code and SSL_get_stream_read_error_code" +This allows an application to determine the application error code which was +signalled by a peer which has performed a non\-normal stream termination of the +respective sending or receiving part of a stream, if any. +.IP \fBSSL_get_conn_close_info\fR\|(3) 4 +.IX Item "SSL_get_conn_close_info" +This allows an application to determine the error code which was signalled when +the local or remote endpoint terminated the QUIC connection. +.IP \fBSSL_get0_connection\fR\|(3) 4 +.IX Item "SSL_get0_connection" +Gets the QUIC connection SSL object from a QUIC stream SSL object. +.IP \fBSSL_is_connection\fR\|(3) 4 +.IX Item "SSL_is_connection" +Returns 1 if an SSL object is not a QUIC stream SSL object. +.IP \fBSSL_get_stream_type\fR\|(3) 4 +.IX Item "SSL_get_stream_type" +Provides information on the kind of QUIC stream which is attached +to the SSL object. +.IP \fBSSL_get_stream_id\fR\|(3) 4 +.IX Item "SSL_get_stream_id" +Returns the QUIC stream ID which the QUIC protocol has associated with a QUIC +stream. +.IP \fBSSL_new_stream\fR\|(3) 4 +.IX Item "SSL_new_stream" +Creates a new QUIC stream SSL object representing a new, locally\-initiated QUIC +stream. +.IP \fBSSL_accept_stream\fR\|(3) 4 +.IX Item "SSL_accept_stream" +Potentially yields a new QUIC stream SSL object representing a new +remotely\-initiated QUIC stream, blocking until one is available if the +connection is configured to do so. +.IP \fBSSL_get_accept_stream_queue_len\fR\|(3) 4 +.IX Item "SSL_get_accept_stream_queue_len" +Provides information on the number of pending remotely\-initiated streams. +.IP \fBSSL_set_incoming_stream_policy\fR\|(3) 4 +.IX Item "SSL_set_incoming_stream_policy" +Configures how incoming, remotely\-initiated streams are handled. The incoming +stream policy can be used to automatically reject streams created by the peer, +or allow them to be handled using \fBSSL_accept_stream\fR\|(3). +.IP \fBSSL_set_default_stream_mode\fR\|(3) 4 +.IX Item "SSL_set_default_stream_mode" +Used to configure or disable default stream mode; see the MODES OF OPERATION +section for details. +.PP +The following BIO APIs are not specific to QUIC but have been added to +facilitate QUIC\-specific requirements and are closely associated with its use: +.IP \fBBIO_s_dgram_pair\fR\|(3) 4 +.IX Item "BIO_s_dgram_pair" +This is a new BIO method which is similar to a conventional BIO pair but +provides datagram semantics. +.IP "\fBBIO_get_rpoll_descriptor\fR\|(3), \fBBIO_get_wpoll_descriptor\fR\|(3)" 4 +.IX Item "BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor" +This is a new BIO API which allows a BIO to expose a poll descriptor. This API +is used to implement the corresponding SSL APIs \fBSSL_get_rpoll_descriptor\fR\|(3) +and \fBSSL_get_wpoll_descriptor\fR\|(3). +.IP "\fBBIO_sendmmsg\fR\|(3), \fBBIO_recvmmsg\fR\|(3)" 4 +.IX Item "BIO_sendmmsg, BIO_recvmmsg" +This is a new BIO API which can be implemented by BIOs which implement datagram +semantics. It is implemented by \fBBIO_s_datagram\fR\|(3) and \fBBIO_s_dgram_pair\fR\|(3). +It is used by the QUIC implementation to send and receive UDP datagrams. +.IP "\fBBIO_dgram_set_no_trunc\fR\|(3), \fBBIO_dgram_get_no_trunc\fR\|(3)" 4 +.IX Item "BIO_dgram_set_no_trunc, BIO_dgram_get_no_trunc" +By default, \fBBIO_s_dgram_pair\fR\|(3) has semantics comparable to those of Berkeley +sockets being used with datagram semantics. This allows an alternative mode +to be enabled in which datagrams will not be silently truncated if they are +too large. +.IP "\fBBIO_dgram_set_caps\fR\|(3), \fBBIO_dgram_get_caps\fR\|(3)" 4 +.IX Item "BIO_dgram_set_caps, BIO_dgram_get_caps" +These functions are used to allow the user of one end of a +\&\fBBIO_s_dgram_pair\fR\|(3) to indicate its capabilities to the other end of a +\&\fBBIO_s_dgram_pair\fR\|(3). In particular, this allows an application to inform the +QUIC implementation of whether it is prepared to handle local and/or peer +addresses in transmitted datagrams and to provide the applicable information in +received datagrams. +.IP "\fBBIO_dgram_get_local_addr_cap\fR\|(3), \fBBIO_dgram_set_local_addr_enable\fR\|(3), \fBBIO_dgram_get_local_addr_enable\fR\|(3)" 4 +.IX Item "BIO_dgram_get_local_addr_cap, BIO_dgram_set_local_addr_enable, BIO_dgram_get_local_addr_enable" +Local addressing support refers to the ability of a BIO with datagram semantics +to allow a source address to be specified on transmission and to report the +destination address on reception. These functions can be used to determine if a +BIO can support local addressing and to enable local addressing support if it +can. +.IP \fBBIO_err_is_non_fatal\fR\|(3) 4 +.IX Item "BIO_err_is_non_fatal" +This is used to determine if an error while calling \fBBIO_sendmmsg\fR\|(3) or +\&\fBBIO_recvmmsg\fR\|(3) is ephemeral in nature, such as "would block" errors. +.SH "THREAD ASSISTED MODE" +.IX Header "THREAD ASSISTED MODE" +The optional thread assisted mode for clients can be used with +\&\fBOSSL_QUIC_client_thread_method\fR\|(3). In this mode, a background thread is +created automatically. The OpenSSL QUIC implementation then takes responsibility +for ensuring that timeout events are handled on a timely basis even if no SSL +I/O function such as \fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called by the +application for a long time. +.PP +All necessary locking is handled automatically internally, but the thread safety +guarantees for the public SSL API are unchanged. Therefore, an application must +still do its own locking if it wishes to make concurrent use of the public SSL +APIs. +.PP +Because this method relies on threads, it is not available on platforms where +threading support is not available or not supported by OpenSSL. However, it +does provide the simplest mode of usage for an application. +.PP +The implementation may or may not use a common thread or thread pool to service +multiple SSL objects in the same \fBSSL_CTX\fR. +.SH "APPLICATION\-DRIVEN EVENT LOOPS" +.IX Header "APPLICATION-DRIVEN EVENT LOOPS" +OpenSSL\*(Aqs QUIC implementation is designed to facilitate applications which wish +to use the SSL APIs in a blocking fashion, but is also designed to facilitate +applications which wish to use the SSL APIs in a nonblocking fashion and manage +their own event loops and polling directly. This is useful when it is desirable +to host OpenSSL\*(Aqs QUIC implementation on top of an application\*(Aqs existing +nonblocking I/O infrastructure. +.PP +This is supported via the concept of poll descriptors; see +\&\fBBIO_get_rpoll_descriptor\fR\|(3) for details. Broadly, a \fBBIO_POLL_DESCRIPTOR\fR is +a structure which expresses some kind of OS resource which can be used to +synchronise on I/O events. The QUIC implementation provides a +\&\fBBIO_POLL_DESCRIPTOR\fR based on the poll descriptor provided by the underlying +network BIO. This is typically an OS socket handle, though custom BIOs could +choose to implement their own custom poll descriptor format. +.PP +Broadly, an application which wishes to manage its own event loop should +interact with the SSL object as follows: +.IP \(bu 4 +It should provide read and write BIOs with nonblocking datagram semantics to +the SSL object using \fBSSL_set0_rbio\fR\|(3) and \fBSSL_set0_wbio\fR\|(3). This could be +a BIO abstracting a network socket such as \fBBIO_s_datagram\fR\|(3), or a BIO +abstracting some kind of memory buffer such as \fBBIO_s_dgram_pair\fR\|(3). Use of a +custom BIO is also possible. +.IP \(bu 4 +It should configure the SSL object into nonblocking mode by calling +\&\fBSSL_set_blocking_mode\fR\|(3). +.IP \(bu 4 +It should configure the SSL object as desired, set an initial peer as needed +using \fBSSL_set1_initial_peer_addr\fR\|(3), and trigger the connection process by +calling \fBSSL_connect\fR\|(3). +.IP \(bu 4 +If the network read and write BIOs provided were pollable (for example, +a \fBBIO_s_datagram\fR\|(3), or a custom BIO which implements +\&\fBBIO_get_rpoll_descriptor\fR\|(3) and \fBBIO_get_wpoll_descriptor\fR\|(3)), it should +perform the following steps repeatedly: +.RS 4 +.IP \(bu 4 +The application should call \fBSSL_get_rpoll_descriptor\fR\|(3) and +\&\fBSSL_get_wpoll_descriptor\fR\|(3) to identify OS resources which can be used for +synchronisation. +.IP \(bu 4 +It should call \fBSSL_net_read_desired\fR\|(3) and \fBSSL_net_write_desired\fR\|(3) to determine +whether the QUIC implementation is currently interested in readability and +writability events on the underlying network BIO which was provided, and call +\&\fBSSL_get_event_timeout\fR\|(3) to determine if any timeout event will become +applicable in the future. +.IP \(bu 4 +It should wait until one of the following events occurs: +.RS 4 +.IP \(bu 4 +The poll descriptor returned by \fBSSL_get_rpoll_descriptor\fR\|(3) becomes readable +(if \fBSSL_net_read_desired\fR\|(3) returned 1); +.IP \(bu 4 +The poll descriptor returned by \fBSSL_get_wpoll_descriptor\fR\|(3) becomes writable +(if \fBSSL_net_write_desired\fR\|(3) returned 1); +.IP \(bu 4 +The timeout returned by \fBSSL_get_event_timeout\fR\|(3) (if any) expires. +.RE +.RS 4 +.Sp +Once any of these events occurs, \fBSSL_handle_events\fR\|(3) should be called. +.RE +.RE +.RS 4 +.RE +.IP \(bu 4 +If the network read and write BIOs provided were not pollable (for example, in +the case of \fBBIO_s_dgram_pair\fR\|(3)), the application is responsible for managing +and synchronising network I/O. It should call \fBSSL_handle_events\fR\|(3) after it +writes data to a \fBBIO_s_dgram_pair\fR\|(3) or otherwise takes action so that the +QUIC implementation can read new datagrams via a call to \fBBIO_recvmmsg\fR\|(3) on +the underlying network BIO. The QUIC implementation may output datagrams via a +call to \fBBIO_sendmmsg\fR\|(3) and the application is responsible for ensuring these +are transmitted. +.Sp +The application must call \fBSSL_get_event_timeout\fR\|(3) after every call to +\&\fBSSL_handle_events\fR\|(3) (or another I/O function on the SSL object), and ensure +that a call to \fBSSL_handle_events\fR\|(3) is performed after the specified timeout +(if any). +.SH "WINDOWS APPLICATION NOTES" +.IX Header "WINDOWS APPLICATION NOTES" +QUIC protocol uses UDP sockets. The \fBrecvfrom()\fR function on Windows may fail +with \f(CW\*(C`WSAECONNRESET\*(C'\fR error causing OpenSSL QUIC stack to enter permanent +error, which prevents further communication over QUIC protocol. Applications +should disable SIO_UDP_CONNRESET and SIO_UDP_NETRESET error notification +on UDP sockets they pass to OpenSSL QUIC stack. More details can be found here: +https://learn.microsoft.com/en\-us/windows/win32/winsock/winsock\-ioctls#sio_udp_connreset\-opcode\-setting\-i\-t3 +.PP +OpenSSL attempts to always disable SIO_UDP_CONNRESET and SIO_UDP_NETRESET +on UDP sockets it receives from application, but no error is reported back +if the respective \f(CWWSAIoctl()\fR calls fail. Robust application should set those +options itself so it can handle error notifications from \f(CWWSAIoctl()\fR properly. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3), +\&\fBSSL_net_read_desired\fR\|(3), \fBSSL_net_write_desired\fR\|(3), +\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3), +\&\fBSSL_set_blocking_mode\fR\|(3), \fBSSL_shutdown_ex\fR\|(3), +\&\fBSSL_set1_initial_peer_addr\fR\|(3), \fBSSL_stream_conclude\fR\|(3), +\&\fBSSL_stream_reset\fR\|(3), \fBSSL_get_stream_read_state\fR\|(3), +\&\fBSSL_get_stream_read_error_code\fR\|(3), \fBSSL_get_conn_close_info\fR\|(3), +\&\fBSSL_get0_connection\fR\|(3), \fBSSL_get_stream_type\fR\|(3), \fBSSL_get_stream_id\fR\|(3), +\&\fBSSL_new_stream\fR\|(3), \fBSSL_accept_stream\fR\|(3), +\&\fBSSL_set_incoming_stream_policy\fR\|(3), \fBSSL_set_default_stream_mode\fR\|(3), +\&\fBSSL_new_listener\fR\|(3), \fBSSL_new_listener_from\fR\|(3), \fBSSL_is_listener\fR\|(3), +\&\fBSSL_get0_listener\fR\|(3), \fBSSL_listen\fR\|(3), \fBSSL_accept_connection\fR\|(3), +\&\fBSSL_get_accept_connection_queue_len\fR\|(3), \fBSSL_new_domain\fR\|(3), +\&\fBSSL_is_domain\fR\|(3), \fBSSL_get0_domain\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/openssl-threads.7 b/static/netbsd/man7/openssl-threads.7 new file mode 100644 index 00000000..5cd9e012 --- /dev/null +++ b/static/netbsd/man7/openssl-threads.7 @@ -0,0 +1,163 @@ +.\" $NetBSD: openssl-threads.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL-THREADS 7" +.TH OPENSSL-THREADS 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +openssl\-threads \- Overview of thread safety in OpenSSL +.SH DESCRIPTION +.IX Header "DESCRIPTION" +In this man page, we use the term \fBthread\-safe\fR to indicate that an +object or function can be used by multiple threads at the same time. +.PP +OpenSSL can be built with or without threads support. The most important +use of this support is so that OpenSSL itself can use a single consistent +API, as shown in "EXAMPLES" in \fBCRYPTO_THREAD_run_once\fR\|(3). +Multi\-platform applications can also use this API. +.PP +In particular, being configured for threads support does not imply that +all OpenSSL objects are thread\-safe. +To emphasize: \fImost objects are not safe for simultaneous use\fR. +Exceptions to this should be documented on the specific manual pages, and +some general high\-level guidance is given here. +.PP +One major use of the OpenSSL thread API is to implement reference counting. +Many objects within OpenSSL are reference\-counted, so resources are not +released, until the last reference is removed. +References are often increased automatically (such as when an \fBX509\fR +certificate object is added into an \fBX509_STORE\fR trust store). +There is often an \fR\f(BIobject\fR\fB_up_ref\fR() function that can be used to increase +the reference count. +Failure to match \fB\fR\f(BIobject\fR\fB_up_ref\fR() calls with the right number of +\&\fB\fR\f(BIobject\fR\fB_free\fR() calls is a common source of memory leaks when a program +exits. +.PP +Many objects have set and get API\*(Aqs to set attributes in the object. +A \f(CW\*(C`set0\*(C'\fR passes ownership from the caller to the object and a +\&\f(CW\*(C`get0\*(C'\fR returns a pointer but the attribute ownership +remains with the object and a reference to it is returned. +A \f(CW\*(C`set1\*(C'\fR or \f(CW\*(C`get1\*(C'\fR function does not change the ownership, but instead +updates the attribute\*(Aqs reference count so that the object is shared +between the caller and the object; the caller must free the returned +attribute when finished. +Functions that involve attributes that have reference counts themselves, +but are named with just \f(CW\*(C`set\*(C'\fR or \f(CW\*(C`get\*(C'\fR are historical; and the documentation +must state how the references are handled. +Get methods are often thread\-safe as long as the ownership requirements are +met and shared objects are not modified. +Set methods, or modifying shared objects, are generally not thread\-safe +as discussed below. +.PP +Objects are thread\-safe +as long as the API\*(Aqs being invoked don\*(Aqt modify the object; in this +case the parameter is usually marked in the API as \f(CW\*(C`const\*(C'\fR. +Not all parameters are marked this way. +Note that a \f(CW\*(C`const\*(C'\fR declaration does not mean immutable; for example +\&\fBX509_cmp\fR\|(3) takes pointers to \f(CW\*(C`const\*(C'\fR objects, but the implementation +uses a C cast to remove that so it can lock objects, generate and cache +a DER encoding, and so on. +.PP +Another instance of thread\-safety is when updates to an object\*(Aqs +internal state, such as cached values, are done with locks. +One example of this is the reference counting API\*(Aqs described above. +.PP +In all cases, however, it is generally not safe for one thread to +mutate an object, such as setting elements of a private or public key, +while another thread is using that object, such as verifying a signature. +.PP +The same API\*(Aqs can usually be used simultaneously on different objects +without interference. +For example, two threads can calculate a signature using two different +\&\fBEVP_PKEY_CTX\fR objects. +.PP +For implicit global state or singletons, thread\-safety depends on the facility. +The \fBCRYPTO_secure_malloc\fR\|(3) and related API\*(Aqs have their own lock, +while \fBCRYPTO_malloc\fR\|(3) assumes the underlying platform allocation +will do any necessary locking. +Some API\*(Aqs, such as \fBNCONF_load\fR\|(3) and related do no locking at all; +this can be considered a bug. +.PP +A separate, although related, issue is modifying "factory" objects +when other objects have been created from that. +For example, an \fBSSL_CTX\fR object created by \fBSSL_CTX_new\fR\|(3) is used +to create per\-connection \fBSSL\fR objects by calling \fBSSL_new\fR\|(3). +In this specific case, and probably for factory methods in general, it is +not safe to modify the factory object after it has been used to create +other objects. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBCRYPTO_THREAD_run_once\fR\|(3), +local system threads documentation. +.SH BUGS +.IX Header "BUGS" +This page is admittedly very incomplete. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/openssl_user_macros.7 b/static/netbsd/man7/openssl_user_macros.7 new file mode 100644 index 00000000..6d7cf58d --- /dev/null +++ b/static/netbsd/man7/openssl_user_macros.7 @@ -0,0 +1,160 @@ +.\" $NetBSD: openssl_user_macros.7,v 1.1 2025/07/18 16:41:20 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_USER_MACROS 7" +.TH OPENSSL_USER_MACROS 7 2025-07-18 3.5.1 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +openssl_user_macros, OPENSSL_API_COMPAT, OPENSSL_NO_DEPRECATED +\&\- User defined macros +.SH DESCRIPTION +.IX Header "DESCRIPTION" +User defined macros allow the programmer to control certain aspects of +what is exposed by the OpenSSL headers. +.PP +\&\fBNOTE:\fR to be effective, a user defined macro \fImust be defined +before including any header file that depends on it\fR, either in the +compilation command (\f(CW\*(C`cc \-DMACRO=value\*(C'\fR) or by defining the macro in +source before including any headers. +.PP +Other manual pages may refer to this page when declarations depend on +user defined macros. +.SS "The macros" +.IX Subsection "The macros" +.IP \fBOPENSSL_API_COMPAT\fR 4 +.IX Item "OPENSSL_API_COMPAT" +The value is a version number, given in one of the following two forms: +.RS 4 +.ie n .IP """0xMNNFF000L""" 4 +.el .IP \f(CW0xMNNFF000L\fR 4 +.IX Item "0xMNNFF000L" +This is the form supported for all versions up to 1.1.x, where \f(CW\*(C`M\*(C'\fR +represents the major number, \f(CW\*(C`NN\*(C'\fR represents the minor number, and +\&\f(CW\*(C`FF\*(C'\fR represents the fix number, as a hexadecimal number. For version +1.1.0, that\*(Aqs \f(CW\*(C`0x10100000L\*(C'\fR. +.Sp +Any version number may be given, but these numbers are +the current known major deprecation points, making them the most +meaningful: +.RS 4 +.ie n .IP """0x00908000L"" (version 0.9.8)" 4 +.el .IP "\f(CW0x00908000L\fR (version 0.9.8)" 4 +.IX Item "0x00908000L (version 0.9.8)" +.PD 0 +.ie n .IP """0x10000000L"" (version 1.0.0)" 4 +.el .IP "\f(CW0x10000000L\fR (version 1.0.0)" 4 +.IX Item "0x10000000L (version 1.0.0)" +.ie n .IP """0x10100000L"" (version 1.1.0)" 4 +.el .IP "\f(CW0x10100000L\fR (version 1.1.0)" 4 +.IX Item "0x10100000L (version 1.1.0)" +.PD +.RE +.RS 4 +.Sp +For convenience, higher numbers are accepted as well, as long as +feasible. For example, \f(CW\*(C`0x60000000L\*(C'\fR will work as expected. +However, it is recommended to start using the second form instead: +.RE +.ie n .IP """mmnnpp""" 4 +.el .IP \f(CWmmnnpp\fR 4 +.IX Item "mmnnpp" +This form is a simple decimal number calculated with this formula: +.Sp +\&\fImajor\fR * 10000 + \fIminor\fR * 100 + \fIpatch\fR +.Sp +where \fImajor\fR, \fIminor\fR and \fIpatch\fR are the desired major, +minor and patch components of the version number. For example: +.RS 4 +.IP "30000 corresponds to version 3.0.0" 4 +.IX Item "30000 corresponds to version 3.0.0" +.PD 0 +.IP "10002 corresponds to version 1.0.2" 4 +.IX Item "10002 corresponds to version 1.0.2" +.IP "420101 corresponds to version 42.1.1" 4 +.IX Item "420101 corresponds to version 42.1.1" +.PD +.RE +.RS 4 +.RE +.RE +.RS 4 +.Sp +If \fBOPENSSL_API_COMPAT\fR is undefined, this default value is used in its +place: +\&\f(CW30500\fR +.RE +.IP \fBOPENSSL_NO_DEPRECATED\fR 4 +.IX Item "OPENSSL_NO_DEPRECATED" +If this macro is defined, all deprecated public symbols in all OpenSSL +versions up to and including the version given by \fBOPENSSL_API_COMPAT\fR +(or the default value given above, when \fBOPENSSL_API_COMPAT\fR isn\*(Aqt defined) +will be hidden. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-introduction.7 b/static/netbsd/man7/ossl-guide-introduction.7 new file mode 100644 index 00000000..fa01d409 --- /dev/null +++ b/static/netbsd/man7/ossl-guide-introduction.7 @@ -0,0 +1,165 @@ +.\" $NetBSD: ossl-guide-introduction.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-INTRODUCTION 7" +.TH OSSL-GUIDE-INTRODUCTION 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-introduction +\&\- OpenSSL Guide: An introduction to OpenSSL +.SH "WHAT IS OPENSSL?" +.IX Header "WHAT IS OPENSSL?" +OpenSSL is a robust, commercial\-grade, full\-featured toolkit for general\-purpose +cryptography and secure communication. Its features are made available via a +command line application that enables users to perform various cryptography +related functions such as generating keys and certificates. Additionally it +supplies two libraries that application developers can use to implement +cryptography based capabilities and to securely communicate across a network. +Finally, it also has a set of providers that supply implementations of a broad +set of cryptographic algorithms. +.PP +OpenSSL is fully open source. Version 3.0 and above are distributed under the +Apache v2 license. +.SH "GETTING AND INSTALLING OPENSSL" +.IX Header "GETTING AND INSTALLING OPENSSL" +The OpenSSL Project develops and distributes the source code for OpenSSL. You +can obtain that source code via the OpenSSL website +(). +.PP +Many Operating Systems (notably Linux distributions) supply pre\-built OpenSSL +binaries either pre\-installed or available via the package management system in +use for that OS. It is worth checking whether this applies to you before +attempting to build OpenSSL from the source code. +.PP +Some third parties also supply OpenSSL binaries (e.g. for Windows and some other +platforms). The OpenSSL project maintains a list of these third parties at +. +.PP +If you build and install OpenSSL from the source code then you should download +the appropriate files for the version that you want to use from the link given +above. Extract the contents of the \fBtar.gz\fR archive file that you downloaded +into an appropriate directory. Inside that archive you will find a file named +\&\fBINSTALL.md\fR which will supply detailed instructions on how to build and +install OpenSSL from source. Make sure you read the contents of that file +carefully in order to achieve a successful build. In the directory you will also +find a set of \fBNOTES\fR files that provide further platform specific information. +Make sure you carefully read the file appropriate to your platform. As well as +the platform specific \fBNOTES\fR files there is also a \fBNOTES\-PERL.md\fR file that +provides information about setting up Perl for use by the OpenSSL build system +across multiple platforms. +.PP +Sometimes you may want to build and install OpenSSL from source on a system +which already has a pre\-built version of OpenSSL installed on it via the +Operating System package management system (for example if you want to use a +newer version of OpenSSL than the one supplied by your Operating System). In +this case it is strongly recommended to install OpenSSL to a different location +than where the pre\-built version is installed. You should \fBnever\fR replace the +pre\-built version with a different version as this may break your system. +.SH "CONTENTS OF THE OPENSSL GUIDE" +.IX Header "CONTENTS OF THE OPENSSL GUIDE" +The OpenSSL Guide is a series of documentation pages (starting with this one) +that introduce some of the main concepts in OpenSSL. The guide can either be +read end\-to\-end in order, or alternatively you can simply skip to the parts most +applicable to your use case. Note however that later pages may depend on and +assume knowledge from earlier pages. +.PP +The pages in the guide are as follows: +.IP "\fBossl\-guide\-libraries\-introduction\fR\|(7): An introduction to the OpenSSL libraries" 4 +.IX Item "ossl-guide-libraries-introduction: An introduction to the OpenSSL libraries" +.PD 0 +.IP "\fBossl\-guide\-libcrypto\-introduction\fR\|(7): An introduction to libcrypto" 4 +.IX Item "ossl-guide-libcrypto-introduction: An introduction to libcrypto" +.IP "\fBossl\-guide\-libssl\-introduction\fR\|(7): An introduction to libssl" 4 +.IX Item "ossl-guide-libssl-introduction: An introduction to libssl" +.IP "\fBossl\-guide\-tls\-introduction\fR\|(7): An introduction to SSL/TLS in OpenSSL" 4 +.IX Item "ossl-guide-tls-introduction: An introduction to SSL/TLS in OpenSSL" +.IP "\fBossl\-guide\-tls\-client\-block\fR\|(7): Writing a simple blocking TLS client" 4 +.IX Item "ossl-guide-tls-client-block: Writing a simple blocking TLS client" +.IP "\fBossl\-guide\-tls\-client\-non\-block\fR\|(7): Writing a simple nonblocking TLS client" 4 +.IX Item "ossl-guide-tls-client-non-block: Writing a simple nonblocking TLS client" +.IP "\fBossl\-guide\-tls\-server\-block\fR\|(7): Writing a simple blocking TLS server" 4 +.IX Item "ossl-guide-tls-server-block: Writing a simple blocking TLS server" +.IP "\fBossl\-guide\-quic\-introduction\fR\|(7): An introduction to QUIC in OpenSSL" 4 +.IX Item "ossl-guide-quic-introduction: An introduction to QUIC in OpenSSL" +.IP "\fBossl\-guide\-quic\-client\-block\fR\|(7): Writing a simple blocking QUIC client" 4 +.IX Item "ossl-guide-quic-client-block: Writing a simple blocking QUIC client" +.IP "\fBossl\-guide\-quic\-server\-block\fR\|(7): Writing a simple blocking QUIC server" 4 +.IX Item "ossl-guide-quic-server-block: Writing a simple blocking QUIC server" +.IP "\fBossl\-guide\-quic\-multi\-stream\fR\|(7): Writing a simple multi\-stream QUIC client" 4 +.IX Item "ossl-guide-quic-multi-stream: Writing a simple multi-stream QUIC client" +.IP "\fBossl\-guide\-quic\-server\-non\-block\fR\|(7): Writing a simple nonblocking QUIC server" 4 +.IX Item "ossl-guide-quic-server-non-block: Writing a simple nonblocking QUIC server" +.IP "\fBossl\-guide\-quic\-client\-non\-block\fR\|(7): Writing a simple nonblocking QUIC client" 4 +.IX Item "ossl-guide-quic-client-non-block: Writing a simple nonblocking QUIC client" +.IP "\fBossl\-guide\-migration\fR\|(7): Migrating from older OpenSSL versions" 4 +.IX Item "ossl-guide-migration: Migrating from older OpenSSL versions" +.PD +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-libcrypto-introduction.7 b/static/netbsd/man7/ossl-guide-libcrypto-introduction.7 new file mode 100644 index 00000000..47acc073 --- /dev/null +++ b/static/netbsd/man7/ossl-guide-libcrypto-introduction.7 @@ -0,0 +1,448 @@ +.\" $NetBSD: ossl-guide-libcrypto-introduction.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-LIBCRYPTO-INTRODUCTION 7" +.TH OSSL-GUIDE-LIBCRYPTO-INTRODUCTION 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-libcrypto\-introduction, crypto +\&\- OpenSSL Guide: An introduction to libcrypto +.SH INTRODUCTION +.IX Header "INTRODUCTION" +The OpenSSL cryptography library (\f(CW\*(C`libcrypto\*(C'\fR) enables access to a wide range +of cryptographic algorithms used in various Internet standards. The services +provided by this library are used by the OpenSSL implementations of TLS and +CMS, and they have also been used to implement many other third party products +and protocols. +.PP +The functionality includes symmetric encryption, public key cryptography, key +agreement, certificate handling, cryptographic hash functions, cryptographic +pseudo\-random number generators, message authentication codes (MACs), key +derivation functions (KDFs), and various utilities. +.SS Algorithms +.IX Subsection "Algorithms" +Cryptographic primitives such as the SHA256 digest, or AES encryption are +referred to in OpenSSL as "algorithms". Each algorithm may have multiple +implementations available for use. For example the RSA algorithm is available as +a "default" implementation suitable for general use, and a "fips" implementation +which has been validated to FIPS 140 standards for situations where that is +important. It is also possible that a third party could add additional +implementations such as in a hardware security module (HSM). +.PP +Algorithms are implemented in providers. See +\&\fBossl\-guide\-libraries\-introduction\fR\|(7) for information about providers. +.SS Operations +.IX Subsection "Operations" +Different algorithms can be grouped together by their purpose. For example there +are algorithms for encryption, and different algorithms for digesting data. +These different groups are known as "operations" in OpenSSL. Each operation +has a different set of functions associated with it. For example to perform an +encryption operation using AES (or any other encryption algorithm) you would use +the encryption functions detailed on the \fBEVP_EncryptInit\fR\|(3) page. Or to +perform a digest operation using SHA256 then you would use the digesting +functions on the \fBEVP_DigestInit\fR\|(3) page. +.SH "ALGORITHM FETCHING" +.IX Header "ALGORITHM FETCHING" +In order to use an algorithm an implementation for it must first be "fetched". +Fetching is the process of looking through the available implementations, +applying selection criteria (via a property query string), and finally choosing +the implementation that will be used. +.PP +Two types of fetching are supported by OpenSSL \- "Explicit fetching" and +"Implicit fetching". +.SS "Explicit fetching" +.IX Subsection "Explicit fetching" +Explicit fetching involves directly calling a specific API to fetch an algorithm +implementation from a provider. This fetched object can then be passed to other +APIs. These explicit fetching functions usually have the name \f(CW\*(C`APINAME_fetch\*(C'\fR, +where \f(CW\*(C`APINAME\*(C'\fR is the name of the operation. For example \fBEVP_MD_fetch\fR\|(3) +can be used to explicitly fetch a digest algorithm implementation. The user is +responsible for freeing the object returned from the \f(CW\*(C`APINAME_fetch\*(C'\fR function +using \f(CW\*(C`APINAME_free\*(C'\fR when it is no longer needed. +.PP +These fetching functions follow a fairly common pattern, where three +arguments are passed: +.IP "The library context" 4 +.IX Item "The library context" +See \fBOSSL_LIB_CTX\fR\|(3) for a more detailed description. +This may be NULL to signify the default (global) library context, or a +context created by the user. Only providers loaded in this library context (see +\&\fBOSSL_PROVIDER_load\fR\|(3)) will be considered by the fetching function. In case +no provider has been loaded in this library context then the default provider +will be loaded as a fallback (see \fBOSSL_PROVIDER\-default\fR\|(7)). +.IP "An identifier" 4 +.IX Item "An identifier" +For all currently implemented fetching functions this is the algorithm name. +Each provider supports a list of algorithm implementations. See the provider +specific documentation for information on the algorithm implementations +available in each provider: +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-default\fR\|(7), +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-FIPS\fR\|(7), +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-legacy\fR\|(7) and +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-base\fR\|(7). +.Sp +Note, while providers may register algorithms against a list of names using a +string with a colon separated list of names, fetching algorithms using that +format is currently unsupported. +.IP "A property query string" 4 +.IX Item "A property query string" +The property query string used to guide selection of the algorithm +implementation. See +"PROPERTY QUERY STRINGS" in \fBossl\-guide\-libraries\-introduction\fR\|(7). +.PP +The algorithm implementation that is fetched can then be used with other diverse +functions that use them. For example the \fBEVP_DigestInit_ex\fR\|(3) function takes +as a parameter an \fBEVP_MD\fR object which may have been returned from an earlier +call to \fBEVP_MD_fetch\fR\|(3). +.SS "Implicit fetching" +.IX Subsection "Implicit fetching" +OpenSSL has a number of functions that return an algorithm object with no +associated implementation, such as \fBEVP_sha256\fR\|(3), \fBEVP_aes_128_cbc\fR\|(3), +\&\fBEVP_get_cipherbyname\fR\|(3) or \fBEVP_get_digestbyname\fR\|(3). These are present for +compatibility with OpenSSL before version 3.0 where explicit fetching was not +available. +.PP +When they are used with functions like \fBEVP_DigestInit_ex\fR\|(3) or +\&\fBEVP_CipherInit_ex\fR\|(3), the actual implementation to be used is +fetched implicitly using default search criteria (which uses NULL for the +library context and property query string). +.PP +In some cases implicit fetching can also occur when a NULL algorithm parameter +is supplied. In this case an algorithm implementation is implicitly fetched +using default search criteria and an algorithm name that is consistent with +the context in which it is being used. +.PP +Functions that use an \fBEVP_PKEY_CTX\fR or an \fBEVP_PKEY\fR\|(3), such as +\&\fBEVP_DigestSignInit\fR\|(3), all fetch the implementations implicitly. Usually the +algorithm to fetch is determined based on the type of key that is being used and +the function that has been called. +.SS Performance +.IX Subsection "Performance" +If you perform the same operation many times with the same algorithm then it is +recommended to use a single explicit fetch of the algorithm and then reuse the +explicitly fetched algorithm each subsequent time. This will typically be +faster than implicitly fetching the algorithm every time you use it. See an +example of Explicit fetching in "USING ALGORITHMS IN APPLICATIONS". +.PP +Prior to OpenSSL 3.0, functions such as \fBEVP_sha256()\fR which return a "const" +object were used directly to indicate the algorithm to use in various function +calls. If you pass the return value of one of these convenience functions to an +operation then you are using implicit fetching. If you are converting an +application that worked with an OpenSSL version prior to OpenSSL 3.0 then +consider changing instances of implicit fetching to explicit fetching instead. +.PP +If an explicitly fetched object is not passed to an operation, then any implicit +fetch will use an internally cached prefetched object, but it will +still be slower than passing the explicitly fetched object directly. +.PP +The following functions can be used for explicit fetching: +.IP \fBEVP_MD_fetch\fR\|(3) 4 +.IX Item "EVP_MD_fetch" +Fetch a message digest/hashing algorithm implementation. +.IP \fBEVP_CIPHER_fetch\fR\|(3) 4 +.IX Item "EVP_CIPHER_fetch" +Fetch a symmetric cipher algorithm implementation. +.IP \fBEVP_KDF_fetch\fR\|(3) 4 +.IX Item "EVP_KDF_fetch" +Fetch a Key Derivation Function (KDF) algorithm implementation. +.IP \fBEVP_MAC_fetch\fR\|(3) 4 +.IX Item "EVP_MAC_fetch" +Fetch a Message Authentication Code (MAC) algorithm implementation. +.IP \fBEVP_KEM_fetch\fR\|(3) 4 +.IX Item "EVP_KEM_fetch" +Fetch a Key Encapsulation Mechanism (KEM) algorithm implementation +.IP \fBOSSL_ENCODER_fetch\fR\|(3) 4 +.IX Item "OSSL_ENCODER_fetch" +Fetch an encoder algorithm implementation (e.g. to encode keys to a specified +format). +.IP \fBOSSL_DECODER_fetch\fR\|(3) 4 +.IX Item "OSSL_DECODER_fetch" +Fetch a decoder algorithm implementation (e.g. to decode keys from a specified +format). +.IP \fBEVP_RAND_fetch\fR\|(3) 4 +.IX Item "EVP_RAND_fetch" +Fetch a Pseudo Random Number Generator (PRNG) algorithm implementation. +.PP +See "OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-default\fR\|(7), +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-FIPS\fR\|(7), +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-legacy\fR\|(7) and +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-base\fR\|(7) for a list of algorithm names +that can be fetched. +.SH "FETCHING EXAMPLES" +.IX Header "FETCHING EXAMPLES" +The following section provides a series of examples of fetching algorithm +implementations. +.PP +Fetch any available implementation of SHA2\-256 in the default context. Note +that some algorithms have aliases. So "SHA256" and "SHA2\-256" are synonymous: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", NULL); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch any available implementation of AES\-128\-CBC in the default context: +.PP +.Vb 3 +\& EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES\-128\-CBC", NULL); +\& ... +\& EVP_CIPHER_free(cipher); +.Ve +.PP +Fetch an implementation of SHA2\-256 from the default provider in the default +context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch an implementation of SHA2\-256 that is not from the default provider in the +default context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider!=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch an implementation of SHA2\-256 that is preferably from the FIPS provider in +the default context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=?fips"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch an implementation of SHA2\-256 from the default provider in the specified +library context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(libctx, "SHA2\-256", "provider=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Load the legacy provider into the default context and then fetch an +implementation of WHIRLPOOL from it: +.PP +.Vb 2 +\& /* This only needs to be done once \- usually at application start up */ +\& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); +\& +\& EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Note that in the above example the property string "provider=legacy" is optional +since, assuming no other providers have been loaded, the only implementation of +the "whirlpool" algorithm is in the "legacy" provider. Also note that the +default provider should be explicitly loaded if it is required in addition to +other providers: +.PP +.Vb 3 +\& /* This only needs to be done once \- usually at application start up */ +\& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); +\& OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default"); +\& +\& EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL); +\& EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2\-256", NULL); +\& ... +\& EVP_MD_free(md_whirlpool); +\& EVP_MD_free(md_sha256); +.Ve +.SH "USING ALGORITHMS IN APPLICATIONS" +.IX Header "USING ALGORITHMS IN APPLICATIONS" +Cryptographic algorithms are made available to applications through use of the +"EVP" APIs. Each of the various operations such as encryption, digesting, +message authentication codes, etc., have a set of EVP function calls that can +be invoked to use them. See the \fBevp\fR\|(7) page for further details. +.PP +Most of these follow a common pattern. A "context" object is first created. For +example for a digest operation you would use an \fBEVP_MD_CTX\fR, and for an +encryption/decryption operation you would use an \fBEVP_CIPHER_CTX\fR. The +operation is then initialised ready for use via an "init" function \- optionally +passing in a set of parameters (using the \fBOSSL_PARAM\fR\|(3) type) to configure how +the operation should behave. Next data is fed into the operation in a series of +"update" calls. The operation is finalised using a "final" call which will +typically provide some kind of output. Finally the context is cleaned up and +freed. +.PP +The following shows a complete example for doing this process for digesting +data using SHA256. The process is similar for other operations such as +encryption/decryption, signatures, message authentication codes, etc. Additional +examples can be found in the OpenSSL demos (see +"DEMO APPLICATIONS" in \fBossl\-guide\-libraries\-introduction\fR\|(7)). +.PP +.Vb 4 +\& #include +\& #include +\& #include +\& #include +\& +\& int main(void) +\& { +\& EVP_MD_CTX *ctx = NULL; +\& EVP_MD *sha256 = NULL; +\& const unsigned char msg[] = { +\& 0x00, 0x01, 0x02, 0x03 +\& }; +\& unsigned int len = 0; +\& unsigned char *outdigest = NULL; +\& int ret = 1; +\& +\& /* Create a context for the digest operation */ +\& ctx = EVP_MD_CTX_new(); +\& if (ctx == NULL) +\& goto err; +\& +\& /* +\& * Fetch the SHA256 algorithm implementation for doing the digest. We\*(Aqre +\& * using the "default" library context here (first NULL parameter), and +\& * we\*(Aqre not supplying any particular search criteria for our SHA256 +\& * implementation (second NULL parameter). Any SHA256 implementation will +\& * do. +\& * In a larger application this fetch would just be done once, and could +\& * be used for multiple calls to other operations such as EVP_DigestInit_ex(). +\& */ +\& sha256 = EVP_MD_fetch(NULL, "SHA256", NULL); +\& if (sha256 == NULL) +\& goto err; +\& +\& /* Initialise the digest operation */ +\& if (!EVP_DigestInit_ex(ctx, sha256, NULL)) +\& goto err; +\& +\& /* +\& * Pass the message to be digested. This can be passed in over multiple +\& * EVP_DigestUpdate calls if necessary +\& */ +\& if (!EVP_DigestUpdate(ctx, msg, sizeof(msg))) +\& goto err; +\& +\& /* Allocate the output buffer */ +\& outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256)); +\& if (outdigest == NULL) +\& goto err; +\& +\& /* Now calculate the digest itself */ +\& if (!EVP_DigestFinal_ex(ctx, outdigest, &len)) +\& goto err; +\& +\& /* Print out the digest result */ +\& BIO_dump_fp(stdout, outdigest, len); +\& +\& ret = 0; +\& +\& err: +\& /* Clean up all the resources we allocated */ +\& OPENSSL_free(outdigest); +\& EVP_MD_free(sha256); +\& EVP_MD_CTX_free(ctx); +\& if (ret != 0) +\& ERR_print_errors_fp(stderr); +\& return ret; +\& } +.Ve +.SH "ENCODING AND DECODING KEYS" +.IX Header "ENCODING AND DECODING KEYS" +Many algorithms require the use of a key. Keys can be generated dynamically +using the EVP APIs (for example see \fBEVP_PKEY_Q_keygen\fR\|(3)). However it is often +necessary to save or load keys (or their associated parameters) to or from some +external format such as PEM or DER (see \fBopenssl\-glossary\fR\|(7)). OpenSSL uses +encoders and decoders to perform this task. +.PP +Encoders and decoders are just algorithm implementations in the same way as +any other algorithm implementation in OpenSSL. They are implemented by +providers. The OpenSSL encoders and decoders are available in the default +provider. They are also duplicated in the base provider. +.PP +For information about encoders see \fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3). For +information about decoders see \fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3). +.PP +As well as using encoders/decoders directly there are also some helper functions +that can be used for certain well known and commonly used formats. For example +see \fBPEM_read_PrivateKey\fR\|(3) and \fBPEM_write_PrivateKey\fR\|(3) for information +about reading and writing key data from PEM encoded files. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-libssl\-introduction\fR\|(7) for an introduction to using \f(CW\*(C`libssl\*(C'\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\fR\|(1), \fBssl\fR\|(7), \fBevp\fR\|(7), \fBOSSL_LIB_CTX\fR\|(3), \fBopenssl\-threads\fR\|(7), +\&\fBproperty\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-base\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7), \fBOSSL_PROVIDER\-null\fR\|(7), +\&\fBopenssl\-glossary\fR\|(7), \fBprovider\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-libraries-introduction.7 b/static/netbsd/man7/ossl-guide-libraries-introduction.7 new file mode 100644 index 00000000..2960ae6e --- /dev/null +++ b/static/netbsd/man7/ossl-guide-libraries-introduction.7 @@ -0,0 +1,377 @@ +.\" $NetBSD: ossl-guide-libraries-introduction.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-LIBRARIES-INTRODUCTION 7" +.TH OSSL-GUIDE-LIBRARIES-INTRODUCTION 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-libraries\-introduction +\&\- OpenSSL Guide: An introduction to the OpenSSL libraries +.SH INTRODUCTION +.IX Header "INTRODUCTION" +OpenSSL supplies two libraries that can be used by applications known as +\&\f(CW\*(C`libcrypto\*(C'\fR and \f(CW\*(C`libssl\*(C'\fR. +.PP +The \f(CW\*(C`libcrypto\*(C'\fR library provides APIs for general purpose cryptography such as +encryption, digital signatures, hash functions, etc. It additionally supplies +supporting APIs for cryptography related standards, e.g. for reading and writing +digital certificates (also known as X.509 certificates). Finally it also +supplies various additional supporting APIs that are not directly cryptography +related but are nonetheless useful and depended upon by other APIs. For +example the "BIO" functions provide capabilities for abstracting I/O, e.g. via a +file or over a network. +.PP +The \f(CW\*(C`libssl\*(C'\fR library provides functions to perform secure communication between +two peers across a network. Most significantly it implements support for the +SSL/TLS, DTLS and QUIC standards. +.PP +The \f(CW\*(C`libssl\*(C'\fR library depends on and uses many of the capabilities supplied by +\&\f(CW\*(C`libcrypto\*(C'\fR. Any application linked against \f(CW\*(C`libssl\*(C'\fR will also link against +\&\f(CW\*(C`libcrypto\*(C'\fR, and most applications that do this will directly use API functions +supplied by both libraries. +.PP +Applications may be written that only use \f(CW\*(C`libcrypto\*(C'\fR capabilities and do not +link against \f(CW\*(C`libssl\*(C'\fR at all. +.SH PROVIDERS +.IX Header "PROVIDERS" +As well as the two main libraries, OpenSSL also comes with a set of providers. +.PP +A provider in OpenSSL is a component that collects together algorithm +implementations (for example an implementation of the symmetric encryption +algorithm AES). In order to use an algorithm you must have at least one +provider loaded that contains an implementation of it. OpenSSL comes with a +number of providers and they may also be obtained from third parties. +.PP +Providers may either be "built\-in" or in the form of a separate loadable module +file (typically one ending in ".so" or ".dll" dependent on the platform). A +built\-in provider is one that is either already present in \f(CW\*(C`libcrypto\*(C'\fR or one +that the application has supplied itself directly. Third parties can also supply +providers in the form of loadable modules. +.PP +If you don\*(Aqt load a provider explicitly (either in program code or via config) +then the OpenSSL built\-in "default" provider will be automatically loaded. +.PP +See "OPENSSL PROVIDERS" below for a description of the providers that OpenSSL +itself supplies. +.PP +Loading and unloading providers is quite an expensive operation. It is normally +done once, early on in the application lifecycle and those providers are kept +loaded for the duration of the application execution. +.SH "LIBRARY CONTEXTS" +.IX Header "LIBRARY CONTEXTS" +Many OpenSSL API functions make use of a library context. A library context can +be thought of as a "scope" within which configuration options take effect. When +a provider is loaded, it is only loaded within the scope of a given library +context. In this way it is possible for different components of a complex +application to each use a different library context and have different providers +loaded with different configuration settings. +.PP +If an application does not explicitly create a library context then the +"default" library context will be used. +.PP +Library contexts are represented by the \fBOSSL_LIB_CTX\fR type. Many OpenSSL API +functions take a library context as a parameter. Applications can always pass +\&\fBNULL\fR for this parameter to just use the default library context. +.PP +The default library context is automatically created the first time it is +needed. This will automatically load any available configuration file and will +initialise OpenSSL for use. Unlike in earlier versions of OpenSSL (prior to +1.1.0) no explicit initialisation steps need to be taken. +.PP +Similarly when the application exits, the default library context is +automatically destroyed. No explicit de\-initialisation steps need to be taken. +.PP +See \fBOSSL_LIB_CTX\fR\|(3) for more information about library contexts. +See also "ALGORITHM FETCHING" in \fBossl\-guide\-libcrypto\-introduction\fR\|(7). +.SH "PROPERTY QUERY STRINGS" +.IX Header "PROPERTY QUERY STRINGS" +In some cases the available providers may mean that more than one implementation +of any given algorithm might be available. For example the OpenSSL FIPS provider +supplies alternative implementations of many of the same algorithms that are +available in the OpenSSL default provider. +.PP +The process of selecting an algorithm implementation is known as "fetching". +When OpenSSL fetches an algorithm to use it is possible to specify a "property +query string" to guide the selection process. For example a property query +string of "provider=default" could be used to force the selection to only +consider algorithm implementations in the default provider. +.PP +Property query strings can be specified explicitly as an argument to a function. +It is also possible to specify a default property query string for the whole +library context using the \fBEVP_set_default_properties\fR\|(3) or +\&\fBEVP_default_properties_enable_fips\fR\|(3) functions. Where both +default properties and function specific properties are specified then they are +combined. Function specific properties will override default properties where +there is a conflict. +.PP +See "ALGORITHM FETCHING" in \fBossl\-guide\-libcrypto\-introduction\fR\|(7) for more +information about fetching. See \fBproperty\fR\|(7) for more information about +properties. +.SH "MULTI\-THREADED APPLICATIONS" +.IX Header "MULTI-THREADED APPLICATIONS" +As long as OpenSSL has been built with support for threads (the default case +on most platforms) then most OpenSSL \fIfunctions\fR are thread\-safe in the sense +that it is safe to call the same function from multiple threads at the same +time. However most OpenSSL \fIdata structures\fR are not thread\-safe. For example +the \fBBIO_write\fR\|(3) and \fBBIO_read\fR\|(3) functions are thread safe. However it +would not be thread safe to call \fBBIO_write()\fR from one thread while calling +\&\fBBIO_read()\fR in another where both functions are passed the same \fBBIO\fR object +since both of them may attempt to make changes to the same \fBBIO\fR object. +.PP +There are exceptions to these rules. A small number of functions are not thread +safe at all. Where this is the case this restriction should be noted in the +documentation for the function. Similarly some data structures may be partially +or fully thread safe. For example it is always safe to use an \fBOSSL_LIB_CTX\fR in +multiple threads. +.PP +See \fBopenssl\-threads\fR\|(7) for a more detailed discussion on OpenSSL threading +support. +.SH "ERROR HANDLING" +.IX Header "ERROR HANDLING" +Most OpenSSL functions will provide a return value indicating whether the +function has been successful or not. It is considered best practice to always +check the return value from OpenSSL functions (where one is available). +.PP +Most functions that return a pointer value will return NULL in the event of a +failure. +.PP +Most functions that return an integer value will return a positive integer for +success. Some of these functions will return 0 to indicate failure. Others may +return 0 or a negative value for failure. +.PP +Some functions cannot fail and have a \fBvoid\fR return type. There are also a +small number of functions that do not conform to the above conventions (e.g. +they may return 0 to indicate success). +.PP +Due to the above variations in behaviour it is important to check the +documentation for each function for information about how to interpret the +return value for it. +.PP +It is sometimes necessary to get further information about the cause of a +failure (e.g. for debugging or logging purposes). Many (but not all) functions +will add further information about a failure to the OpenSSL error stack. By +using the error stack you can find out information such as a reason code/string +for the error as well as the exact file and source line within OpenSSL that +emitted the error. +.PP +OpenSSL supplies a set of error handling functions to query the error stack. See +\&\fBERR_get_error\fR\|(3) for information about the functions available for querying +error data. Also see \fBERR_print_errors\fR\|(3) for information on some simple +helper functions for printing error data. Finally look at \fBERR_clear_error\fR\|(3) +for how to clear old errors from the error stack. +.SH "OPENSSL PROVIDERS" +.IX Header "OPENSSL PROVIDERS" +OpenSSL comes with a set of providers. +.PP +The algorithms available in each of these providers may vary due to build time +configuration options. The \fBopenssl\-list\fR\|(1) command can be used to list the +currently available algorithms. +.PP +The names of the algorithms shown from \fBopenssl\-list\fR\|(1) can be used as an +algorithm identifier to the appropriate fetching function. Also see the provider +specific manual pages linked below for further details about using the +algorithms available in each of the providers. +.PP +As well as the OpenSSL providers third parties can also implement providers. +For information on writing a provider see \fBprovider\fR\|(7). +.SS "Default provider" +.IX Subsection "Default provider" +The default provider is built\-in as part of the \fIlibcrypto\fR library and +contains all of the most commonly used algorithm implementations. Should it be +needed (if other providers are loaded and offer implementations of the same +algorithms), the property query string "provider=default" can be used as a +search criterion for these implementations. The default provider includes all +of the functionality in the base provider below. +.PP +If you don\*(Aqt load any providers at all then the "default" provider will be +automatically loaded. If you explicitly load any provider then the "default" +provider would also need to be explicitly loaded if it is required. +.PP +See \fBOSSL_PROVIDER\-default\fR\|(7). +.SS "Base provider" +.IX Subsection "Base provider" +The base provider is built in as part of the \fIlibcrypto\fR library and contains +algorithm implementations for encoding and decoding of OpenSSL keys. +Should it be needed (if other providers are loaded and offer +implementations of the same algorithms), the property query string +"provider=base" can be used as a search criterion for these implementations. +Some encoding and decoding algorithm implementations are not FIPS algorithm +implementations in themselves but support algorithms from the FIPS provider and +are allowed for use in "FIPS mode". The property query string "fips=yes" can be +used to select such algorithms. +.PP +See \fBOSSL_PROVIDER\-base\fR\|(7). +.SS "FIPS provider" +.IX Subsection "FIPS provider" +The FIPS provider is a dynamically loadable module, and must therefore +be loaded explicitly, either in code or through OpenSSL configuration +(see \fBconfig\fR\|(5)). It contains algorithm implementations that have been +validated according to FIPS standards. Should it be needed (if other +providers are loaded and offer implementations of the same algorithms), the +property query string "provider=fips" can be used as a search criterion for +these implementations. All approved algorithm implementations in the FIPS +provider can also be selected with the property "fips=yes". The FIPS provider +may also contain non\-approved algorithm implementations and these can be +selected with the property "fips=no". +.PP +Typically the "Base provider" will also need to be loaded because the FIPS +provider does not support the encoding or decoding of keys. +.PP +See \fBOSSL_PROVIDER\-FIPS\fR\|(7) and \fBfips_module\fR\|(7). +.SS "Legacy provider" +.IX Subsection "Legacy provider" +The legacy provider is a dynamically loadable module, and must therefore +be loaded explicitly, either in code or through OpenSSL configuration +(see \fBconfig\fR\|(5)). It contains algorithm implementations that are considered +insecure, or are no longer in common use such as MD2 or RC4. Should it be needed +(if other providers are loaded and offer implementations of the same algorithms), +the property "provider=legacy" can be used as a search criterion for these +implementations. +.PP +See \fBOSSL_PROVIDER\-legacy\fR\|(7). +.SS "Null provider" +.IX Subsection "Null provider" +The null provider is built in as part of the \fIlibcrypto\fR library. It contains +no algorithms in it at all. When fetching algorithms the default provider will +be automatically loaded if no other provider has been explicitly loaded. To +prevent that from happening you can explicitly load the null provider. +.PP +You can use this if you create your own library context and want to ensure that +all API calls have correctly passed the created library context and are not +accidentally using the default library context. Load the null provider into the +default library context so that the default library context has no algorithm +implementations available. +.PP +See \fBOSSL_PROVIDER\-null\fR\|(7). +.SH CONFIGURATION +.IX Header "CONFIGURATION" +By default OpenSSL will load a configuration file when it is first used. This +will set up various configuration settings within the default library context. +Applications that create their own library contexts may optionally configure +them with a config file using the \fBOSSL_LIB_CTX_load_config\fR\|(3) function. +.PP +The configuration file can be used to automatically load providers and set up +default property query strings. +.PP +For information on the OpenSSL configuration file format see \fBconfig\fR\|(5). +.SH "LIBRARY CONVENTIONS" +.IX Header "LIBRARY CONVENTIONS" +Many OpenSSL functions that "get" or "set" a value follow a naming convention +using the numbers \fB0\fR and \fB1\fR, i.e. "get0", "get1", "set0" and "set1". This +can also apply to some functions that "add" a value to an existing set, i.e. +"add0" and "add1". +.PP +For example the functions: +.PP +.Vb 2 +\& int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); +\& int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj); +.Ve +.PP +In the \fB0\fR version the ownership of the object is passed to (for an add or set) +or retained by (for a get) the parent object. For example after calling the +\&\fBX509_CRL_add0_revoked()\fR function above, ownership of the \fIrev\fR object is passed +to the \fIcrl\fR object. Therefore, after calling this function \fIrev\fR should not +be freed directly. It will be freed implicitly when \fIcrl\fR is freed. +.PP +In the \fB1\fR version the ownership of the object is not passed to or retained by +the parent object. Instead a copy or "up ref" of the object is performed. So +after calling the \fBX509_add1_trust_object()\fR function above the application will +still be responsible for freeing the \fIobj\fR value where appropriate. +.PP +Many OpenSSL functions conform to a naming convention of the form +\&\fBCLASSNAME_func_name()\fR. In this naming convention the \fBCLASSNAME\fR is the name +of an OpenSSL data structure (given in capital letters) that the function is +primarily operating on. The \fBfunc_name\fR portion of the name is usually in +lowercase letters and indicates the purpose of the function. +.SH "DEMO APPLICATIONS" +.IX Header "DEMO APPLICATIONS" +OpenSSL is distributed with a set of demo applications which provide some +examples of how to use the various API functions. To look at them download the +OpenSSL source code from the OpenSSL website +(). Extract the downloaded \fB.tar.gz\fR file for +the version of OpenSSL that you are using and look at the various files in the +\&\fBdemos\fR sub\-directory. +.PP +The Makefiles in the subdirectories give instructions on how to build and run +the demo applications. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-libcrypto\-introduction\fR\|(7) for a more detailed introduction to +using \f(CW\*(C`libcrypto\*(C'\fR and \fBossl\-guide\-libssl\-introduction\fR\|(7) for more information +on \f(CW\*(C`libssl\*(C'\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\fR\|(1), \fBssl\fR\|(7), \fBevp\fR\|(7), \fBOSSL_LIB_CTX\fR\|(3), \fBopenssl\-threads\fR\|(7), +\&\fBproperty\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-base\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7), \fBOSSL_PROVIDER\-null\fR\|(7), +\&\fBopenssl\-glossary\fR\|(7), \fBprovider\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-libssl-introduction.7 b/static/netbsd/man7/ossl-guide-libssl-introduction.7 new file mode 100644 index 00000000..c371155e --- /dev/null +++ b/static/netbsd/man7/ossl-guide-libssl-introduction.7 @@ -0,0 +1,165 @@ +.\" $NetBSD: ossl-guide-libssl-introduction.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-LIBSSL-INTRODUCTION 7" +.TH OSSL-GUIDE-LIBSSL-INTRODUCTION 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-libssl\-introduction, ssl +\&\- OpenSSL Guide: An introduction to libssl +.SH INTRODUCTION +.IX Header "INTRODUCTION" +The OpenSSL \f(CW\*(C`libssl\*(C'\fR library provides implementations of several secure network +communications protocols. Specifically it provides SSL/TLS (SSLv3, TLSv1, +TLSv1.1, TLSv1.2 and TLSv1.3), DTLS (DTLSv1 and DTLSv1.2) and QUIC (client side +only). The library depends on \f(CW\*(C`libcrypto\*(C'\fR for its underlying cryptographic +operations (see \fBossl\-guide\-libcrypto\-introduction\fR\|(7)). +.PP +The set of APIs supplied by \f(CW\*(C`libssl\*(C'\fR is common across all of these different +network protocols, so a developer familiar with writing applications using one +of these protocols should be able to transition to using another with relative +ease. +.PP +An application written to use \f(CW\*(C`libssl\*(C'\fR will include the \fI\fR +header file and will typically use two main data structures, i.e. \fBSSL\fR and +\&\fBSSL_CTX\fR. +.PP +An \fBSSL\fR object is used to represent a connection to a remote peer. Once a +connection with a remote peer has been established data can be exchanged with +that peer. +.PP +When using DTLS any data that is exchanged uses "datagram" semantics, i.e. +the packets of data can be delivered in any order, and they are not guaranteed +to arrive at all. In this case the \fBSSL\fR object used for the connection is also +used for exchanging data with the peer. +.PP +Both TLS and QUIC support the concept of a "stream" of data. Data sent via a +stream is guaranteed to be delivered in order without any data loss. A stream +can be uni\- or bi\-directional. +.PP +SSL/TLS only supports one stream of data per connection and it is always +bi\-directional. In this case the \fBSSL\fR object used for the connection also +represents that stream. See \fBossl\-guide\-tls\-introduction\fR\|(7) for more +information. +.PP +The QUIC protocol can support multiple streams per connection and they can be +uni\- or bi\-directional. In this case an \fBSSL\fR object can represent the +underlying connection, or a stream, or both. Where multiple streams are in use +a separate \fBSSL\fR object is used for each one. See +\&\fBossl\-guide\-quic\-introduction\fR\|(7) for more information. +.PP +An \fBSSL_CTX\fR object is used to create the \fBSSL\fR object for the underlying +connection. A single \fBSSL_CTX\fR object can be used to create many connections +(each represented by a separate \fBSSL\fR object). Many API functions in libssl +exist in two forms: one that takes an \fBSSL_CTX\fR and one that takes an \fBSSL\fR. +Typically settings that you apply to the \fBSSL_CTX\fR will then be inherited by +any \fBSSL\fR object that you create from it. Alternatively you can apply settings +directly to the \fBSSL\fR object without affecting other \fBSSL\fR objects. Note that +you should not normally make changes to an \fBSSL_CTX\fR after the first \fBSSL\fR +object has been created from it. +.SH "DATA STRUCTURES" +.IX Header "DATA STRUCTURES" +As well as \fBSSL_CTX\fR and \fBSSL\fR there are a number of other data structures +that an application may need to use. They are summarised below. +.IP "\fBSSL_METHOD\fR (SSL Method)" 4 +.IX Item "SSL_METHOD (SSL Method)" +This structure is used to indicate the kind of connection you want to make, e.g. +whether it is to represent the client or the server, and whether it is to use +SSL/TLS, DTLS or QUIC. It is passed as a parameter when creating +the \fBSSL_CTX\fR. +.IP "\fBSSL_SESSION\fR (SSL Session)" 4 +.IX Item "SSL_SESSION (SSL Session)" +After establishing a connection with a peer the agreed cryptographic material +can be reused to create future connections with the same peer more rapidly. The +set of data used for such a future connection establishment attempt is collected +together into an \fBSSL_SESSION\fR object. A single successful connection with a +peer may generate zero or more such \fBSSL_SESSION\fR objects for use in future +connection attempts. +.IP "\fBSSL_CIPHER\fR (SSL Cipher)" 4 +.IX Item "SSL_CIPHER (SSL Cipher)" +During connection establishment the client and server agree upon cryptographic +algorithms they are going to use for encryption and other uses. A single set +of cryptographic algorithms that are to be used together is known as a +ciphersuite. Such a set is represented by an \fBSSL_CIPHER\fR object. +.Sp +The set of available ciphersuites that can be used are configured in the +\&\fBSSL_CTX\fR or \fBSSL\fR. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-tls\-introduction\fR\|(7) for an introduction to the SSL/TLS +protocol and \fBossl\-guide\-quic\-introduction\fR\|(7) for an introduction to QUIC. +.PP +See \fBossl\-guide\-libcrypto\-introduction\fR\|(7) for an introduction to \f(CW\*(C`libcrypto\*(C'\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-libcrypto\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7), +\&\fBossl\-guide\-quic\-introduction\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-migration.7 b/static/netbsd/man7/ossl-guide-migration.7 new file mode 100644 index 00000000..c4d2953a --- /dev/null +++ b/static/netbsd/man7/ossl-guide-migration.7 @@ -0,0 +1,2123 @@ +.\" $NetBSD: ossl-guide-migration.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-MIGRATION 7" +.TH OSSL-GUIDE-MIGRATION 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-migration, migration_guide +\&\- OpenSSL Guide: Migrating from older OpenSSL versions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +See the individual manual pages for details. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This guide details the changes required to migrate to new versions of OpenSSL. +Currently this covers OpenSSL 3.0 & 3.1. For earlier versions refer to +. +For an overview of some of the key concepts introduced in OpenSSL 3.0 see +\&\fBcrypto\fR\|(7). +.SH "OPENSSL 3.1" +.IX Header "OPENSSL 3.1" +.SS "Main Changes from OpenSSL 3.0" +.IX Subsection "Main Changes from OpenSSL 3.0" +The FIPS provider in OpenSSL 3.1 includes some non\-FIPS validated algorithms, +consequently the property query \f(CW\*(C`fips=yes\*(C'\fR is mandatory for applications that +want to operate in a FIPS approved manner. The algorithms are: +.IP "Triple DES ECB" 4 +.IX Item "Triple DES ECB" +.PD 0 +.IP "Triple DES CBC" 4 +.IX Item "Triple DES CBC" +.IP EdDSA 4 +.IX Item "EdDSA" +.PD +.PP +There are no other changes requiring additional migration measures since OpenSSL 3.0. +.SH "OPENSSL 3.0" +.IX Header "OPENSSL 3.0" +.SS "Main Changes from OpenSSL 1.1.1" +.IX Subsection "Main Changes from OpenSSL 1.1.1" +\fIMajor Release\fR +.IX Subsection "Major Release" +.PP +OpenSSL 3.0 is a major release and consequently any application that currently +uses an older version of OpenSSL will at the very least need to be recompiled in +order to work with the new version. It is the intention that the large majority +of applications will work unchanged with OpenSSL 3.0 if those applications +previously worked with OpenSSL 1.1.1. However this is not guaranteed and some +changes may be required in some cases. Changes may also be required if +applications need to take advantage of some of the new features available in +OpenSSL 3.0 such as the availability of the FIPS module. +.PP +\fILicense Change\fR +.IX Subsection "License Change" +.PP +In previous versions, OpenSSL was licensed under the dual OpenSSL and SSLeay +licenses +(both licenses apply). From OpenSSL 3.0 this is replaced by the +Apache License v2 . +.PP +\fIProviders and FIPS support\fR +.IX Subsection "Providers and FIPS support" +.PP +One of the key changes from OpenSSL 1.1.1 is the introduction of the Provider +concept. Providers collect together and make available algorithm implementations. +With OpenSSL 3.0 it is possible to specify, either programmatically or via a +config file, which providers you want to use for any given application. +OpenSSL 3.0 comes with 5 different providers as standard. Over time third +parties may distribute additional providers that can be plugged into OpenSSL. +All algorithm implementations available via providers are accessed through the +"high level" APIs (for example those functions prefixed with \f(CW\*(C`EVP\*(C'\fR). They cannot +be accessed using the "Low Level APIs". +.PP +One of the standard providers available is the FIPS provider. This makes +available FIPS validated cryptographic algorithms. +The FIPS provider is disabled by default and needs to be enabled explicitly +at configuration time using the \f(CW\*(C`enable\-fips\*(C'\fR option. If it is enabled, +the FIPS provider gets built and installed in addition to the other standard +providers. No separate installation procedure is necessary. +There is however a dedicated \f(CW\*(C`install_fips\*(C'\fR make target, which serves the +special purpose of installing only the FIPS provider into an existing +OpenSSL installation. +.PP +Not all algorithms may be available for the application at a particular moment. +If the application code uses any digest or cipher algorithm via the EVP interface, +the application should verify the result of the \fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_EncryptInit_ex\fR\|(3), and \fBEVP_DigestInit\fR\|(3) functions. In case when +the requested algorithm is not available, these functions will fail. +.PP +See also "Legacy Algorithms" for information on the legacy provider. +.PP +See also "Completing the installation of the FIPS Module" and +"Using the FIPS Module in applications". +.PP +\fILow Level APIs\fR +.IX Subsection "Low Level APIs" +.PP +OpenSSL has historically provided two sets of APIs for invoking cryptographic +algorithms: the "high level" APIs (such as the \f(CW\*(C`EVP\*(C'\fR APIs) and the "low level" +APIs. The high level APIs are typically designed to work across all algorithm +types. The "low level" APIs are targeted at a specific algorithm implementation. +For example, the EVP APIs provide the functions \fBEVP_EncryptInit_ex\fR\|(3), +\&\fBEVP_EncryptUpdate\fR\|(3) and \fBEVP_EncryptFinal\fR\|(3) to perform symmetric +encryption. Those functions can be used with the algorithms AES, CHACHA, 3DES etc. +On the other hand, to do AES encryption using the low level APIs you would have +to call AES specific functions such as \fBAES_set_encrypt_key\fR\|(3), +\&\fBAES_encrypt\fR\|(3), and so on. The functions for 3DES are different. +Use of the low level APIs has been informally discouraged by the OpenSSL +development team for a long time. However in OpenSSL 3.0 this is made more +formal. All such low level APIs have been deprecated. You may still use them in +your applications, but you may start to see deprecation warnings during +compilation (dependent on compiler support for this). Deprecated APIs may be +removed from future versions of OpenSSL so you are strongly encouraged to update +your code to use the high level APIs instead. +.PP +This is described in more detail in "Deprecation of Low Level Functions" +.PP +\fILegacy Algorithms\fR +.IX Subsection "Legacy Algorithms" +.PP +Some cryptographic algorithms such as \fBMD2\fR and \fBDES\fR that were available via +the EVP APIs are now considered legacy and their use is strongly discouraged. +These legacy EVP algorithms are still available in OpenSSL 3.0 but not by +default. If you want to use them then you must load the legacy provider. +This can be as simple as a config file change, or can be done programmatically. +See \fBOSSL_PROVIDER\-legacy\fR\|(7) for a complete list of algorithms. +Applications using the EVP APIs to access these algorithms should instead use +more modern algorithms. If that is not possible then these applications +should ensure that the legacy provider has been loaded. This can be achieved +either programmatically or via configuration. See \fBcrypto\fR\|(7) man page for +more information about providers. +.PP +\fIEngines and "METHOD" APIs\fR +.IX Subsection "Engines and ""METHOD"" APIs" +.PP +The refactoring to support Providers conflicts internally with the APIs used to +support engines, including the ENGINE API and any function that creates or +modifies custom "METHODS" (for example \fBEVP_MD_meth_new\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3), \fBEVP_PKEY_meth_new\fR\|(3), \fBRSA_meth_new\fR\|(3), +\&\fBEC_KEY_METHOD_new\fR\|(3), etc.). These functions are being deprecated in +OpenSSL 3.0, and users of these APIs should know that their use can likely +bypass provider selection and configuration, with unintended consequences. +This is particularly relevant for applications written to use the OpenSSL 3.0 +FIPS module, as detailed below. Authors and maintainers of external engines are +strongly encouraged to refactor their code transforming engines into providers +using the new Provider API and avoiding deprecated methods. +.PP +\fISupport of legacy engines\fR +.IX Subsection "Support of legacy engines" +.PP +If openssl is not built without engine support or deprecated API support, engines +will still work. However, their applicability will be limited. +.PP +New algorithms provided via engines will still work. +.PP +Engine\-backed keys can be loaded via custom \fBOSSL_STORE\fR implementation. +In this case the \fBEVP_PKEY\fR objects created via \fBENGINE_load_private_key\fR\|(3) +will be considered legacy and will continue to work. +.PP +To ensure the future compatibility, the engines should be turned to providers. +To prefer the provider\-based hardware offload, you can specify the default +properties to prefer your provider. +.PP +Setting engine\-based or application\-based default low\-level crypto method such +as \fBRSA_METHOD\fR or \fBEC_KEY_METHOD\fR is still possible and keys inside the +default provider will use the engine\-based implementation for the crypto +operations. However \fBEVP_PKEY\fRs created by decoding by using \fBOSSL_DECODER\fR, +\&\fBPEM_\fR or \fBd2i_\fR APIs will be provider\-based. To create a fully legacy +\&\fBEVP_PKEY\fRs \fBEVP_PKEY_set1_RSA\fR\|(3), \fBEVP_PKEY_set1_EC_KEY\fR\|(3) or similar +functions must be used. +.PP +\fIVersioning Scheme\fR +.IX Subsection "Versioning Scheme" +.PP +The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release. The new +versioning scheme has this format: +.PP +MAJOR.MINOR.PATCH +.PP +For OpenSSL 1.1.1 and below, different patch levels were indicated by a letter +at the end of the release version number. This will no longer be used and +instead the patch level is indicated by the final number in the version. A +change in the second (MINOR) number indicates that new features may have been +added. OpenSSL versions with the same major number are API and ABI compatible. +If the major number changes then API and ABI compatibility is not guaranteed. +.PP +For more information, see \fBOpenSSL_version\fR\|(3). +.PP +\fIOther major new features\fR +.IX Subsection "Other major new features" +.PP +Certificate Management Protocol (CMP, RFC 9810) +.IX Subsection "Certificate Management Protocol (CMP, RFC 9810)" +.PP +This also covers CRMF (RFC 4211) and HTTP transfer (RFC 9811) +See \fBopenssl\-cmp\fR\|(1) and \fBOSSL_CMP_exec_certreq\fR\|(3) as starting points. +.PP +HTTP(S) client +.IX Subsection "HTTP(S) client" +.PP +A proper HTTP(S) client that supports GET and POST, redirection, plain and +ASN.1\-encoded contents, proxies, and timeouts. +.PP +Key Derivation Function API (EVP_KDF) +.IX Subsection "Key Derivation Function API (EVP_KDF)" +.PP +This simplifies the process of adding new KDF and PRF implementations. +.PP +Previously KDF algorithms had been shoe\-horned into using the EVP_PKEY object +which was not a logical mapping. +Existing applications that use KDF algorithms using EVP_PKEY +(scrypt, TLS1 PRF and HKDF) may be slower as they use an EVP_KDF bridge +internally. +All new applications should use the new \fBEVP_KDF\fR\|(3) interface. +See also "Key Derivation Function (KDF)" in \fBOSSL_PROVIDER\-default\fR\|(7) and +"Key Derivation Function (KDF)" in \fBOSSL_PROVIDER\-FIPS\fR\|(7). +.PP +Message Authentication Code API (EVP_MAC) +.IX Subsection "Message Authentication Code API (EVP_MAC)" +.PP +This simplifies the process of adding MAC implementations. +.PP +This includes a generic EVP_PKEY to EVP_MAC bridge, to facilitate the continued +use of MACs through raw private keys in functionality such as +\&\fBEVP_DigestSign\fR\|(3) and \fBEVP_DigestVerify\fR\|(3). +.PP +All new applications should use the new \fBEVP_MAC\fR\|(3) interface. +See also "Message Authentication Code (MAC)" in \fBOSSL_PROVIDER\-default\fR\|(7) +and "Message Authentication Code (MAC)" in \fBOSSL_PROVIDER\-FIPS\fR\|(7). +.PP +Algorithm Fetching +.IX Subsection "Algorithm Fetching" +.PP +Using calls to convenience functions such as \fBEVP_sha256()\fR and \fBEVP_aes_256_gcm()\fR may +incur a performance penalty when using providers. +Retrieving algorithms from providers involves searching for an algorithm by name. +This is much slower than directly accessing a method table. +It is recommended to prefetch algorithms if an algorithm is used many times. +See "Performance" in \fBcrypto\fR\|(7), "Explicit fetching" in \fBcrypto\fR\|(7) and "Implicit fetching" in \fBcrypto\fR\|(7). +.PP +Support for Linux Kernel TLS +.IX Subsection "Support for Linux Kernel TLS" +.PP +In order to use KTLS, support for it must be compiled in using the +\&\f(CW\*(C`enable\-ktls\*(C'\fR configuration option. It must also be enabled at run time using +the \fBSSL_OP_ENABLE_KTLS\fR option. +.PP +New Algorithms +.IX Subsection "New Algorithms" +.IP \(bu 4 +KDF algorithms "SINGLE STEP" and "SSH" +.Sp +See \fBEVP_KDF\-SS\fR\|(7) and \fBEVP_KDF\-SSHKDF\fR\|(7) +.IP \(bu 4 +MAC Algorithms "GMAC" and "KMAC" +.Sp +See \fBEVP_MAC\-GMAC\fR\|(7) and \fBEVP_MAC\-KMAC\fR\|(7). +.IP \(bu 4 +KEM Algorithm "RSASVE" +.Sp +See \fBEVP_KEM\-RSA\fR\|(7). +.IP \(bu 4 +Cipher Algorithm "AES\-SIV" +.Sp +See "SIV Mode" in \fBEVP_EncryptInit\fR\|(3). +.IP \(bu 4 +AES Key Wrap inverse ciphers supported by EVP layer. +.Sp +The inverse ciphers use AES decryption for wrapping, and AES encryption for +unwrapping. The algorithms are: "AES\-128\-WRAP\-INV", "AES\-192\-WRAP\-INV", +"AES\-256\-WRAP\-INV", "AES\-128\-WRAP\-PAD\-INV", "AES\-192\-WRAP\-PAD\-INV" and +"AES\-256\-WRAP\-PAD\-INV". +.IP \(bu 4 +CTS ciphers added to EVP layer. +.Sp +The algorithms are "AES\-128\-CBC\-CTS", "AES\-192\-CBC\-CTS", "AES\-256\-CBC\-CTS", +"CAMELLIA\-128\-CBC\-CTS", "CAMELLIA\-192\-CBC\-CTS" and "CAMELLIA\-256\-CBC\-CTS". +CS1, CS2 and CS3 variants are supported. +.PP +CMS and PKCS#7 updates +.IX Subsection "CMS and PKCS#7 updates" +.IP \(bu 4 +Added CAdES\-BES signature verification support. +.IP \(bu 4 +Added CAdES\-BES signature scheme and attributes support (RFC 5126) to CMS API. +.IP \(bu 4 +Added AuthEnvelopedData content type structure (RFC 5083) using AES_GCM +.Sp +This uses the AES\-GCM parameter (RFC 5084) for the Cryptographic Message Syntax. +Its purpose is to support encryption and decryption of a digital envelope that +is both authenticated and encrypted using AES GCM mode. +.IP \(bu 4 +\&\fBPKCS7_get_octet_string\fR\|(3) and \fBPKCS7_type_is_other\fR\|(3) were made public. +.PP +PKCS#12 API updates +.IX Subsection "PKCS#12 API updates" +.PP +The default algorithms for pkcs12 creation with the \fBPKCS12_create()\fR function +were changed to more modern PBKDF2 and AES based algorithms. The default +MAC iteration count was changed to PKCS12_DEFAULT_ITER to make it equal +with the password\-based encryption iteration count. The default digest +algorithm for the MAC computation was changed to SHA\-256. The pkcs12 +application now supports \-legacy option that restores the previous +default algorithms to support interoperability with legacy systems. +.PP +Added enhanced PKCS#12 APIs which accept a library context \fBOSSL_LIB_CTX\fR +and (where relevant) a property query. Other APIs which handle PKCS#7 and +PKCS#8 objects have also been enhanced where required. This includes: +.PP +\&\fBPKCS12_add_key_ex\fR\|(3), \fBPKCS12_add_safe_ex\fR\|(3), \fBPKCS12_add_safes_ex\fR\|(3), +\&\fBPKCS12_create_ex\fR\|(3), \fBPKCS12_decrypt_skey_ex\fR\|(3), \fBPKCS12_init_ex\fR\|(3), +\&\fBPKCS12_item_decrypt_d2i_ex\fR\|(3), \fBPKCS12_item_i2d_encrypt_ex\fR\|(3), +\&\fBPKCS12_key_gen_asc_ex\fR\|(3), \fBPKCS12_key_gen_uni_ex\fR\|(3), \fBPKCS12_key_gen_utf8_ex\fR\|(3), +\&\fBPKCS12_pack_p7encdata_ex\fR\|(3), \fBPKCS12_pbe_crypt_ex\fR\|(3), \fBPKCS12_PBE_keyivgen_ex\fR\|(3), +\&\fBPKCS12_SAFEBAG_create_pkcs8_encrypt_ex\fR\|(3), \fBPKCS5_pbe2_set_iv_ex\fR\|(3), +\&\fBPKCS5_pbe_set0_algor_ex\fR\|(3), \fBPKCS5_pbe_set_ex\fR\|(3), \fBPKCS5_pbkdf2_set_ex\fR\|(3), +\&\fBPKCS5_v2_PBE_keyivgen_ex\fR\|(3), \fBPKCS5_v2_scrypt_keyivgen_ex\fR\|(3), +\&\fBPKCS8_decrypt_ex\fR\|(3), \fBPKCS8_encrypt_ex\fR\|(3), \fBPKCS8_set0_pbe_ex\fR\|(3). +.PP +As part of this change the EVP_PBE_xxx APIs can also accept a library +context and property query and will call an extended version of the key/IV +derivation function which supports these parameters. This includes +\&\fBEVP_PBE_CipherInit_ex\fR\|(3), \fBEVP_PBE_find_ex\fR\|(3) and \fBEVP_PBE_scrypt_ex\fR\|(3). +.PP +PKCS#12 KDF versus FIPS +.IX Subsection "PKCS#12 KDF versus FIPS" +.PP +Unlike in 1.x.y, the PKCS12KDF algorithm used when a PKCS#12 structure +is created with a MAC that does not work with the FIPS provider as the PKCS12KDF +is not a FIPS approvable mechanism. +.PP +See \fBEVP_KDF\-PKCS12KDF\fR\|(7), \fBPKCS12_create\fR\|(3), \fBopenssl\-pkcs12\fR\|(1), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7). +.PP +Windows thread synchronization changes +.IX Subsection "Windows thread synchronization changes" +.PP +Windows thread synchronization uses read/write primitives (SRWLock) when +supported by the OS, otherwise CriticalSection continues to be used. +.PP +Trace API +.IX Subsection "Trace API" +.PP +A new generic trace API has been added which provides support for enabling +instrumentation through trace output. This feature is mainly intended as an aid +for developers and is disabled by default. To utilize it, OpenSSL needs to be +configured with the \f(CW\*(C`enable\-trace\*(C'\fR option. +.PP +If the tracing API is enabled, the application can activate trace output by +registering BIOs as trace channels for a number of tracing and debugging +categories. See \fBOSSL_trace_enabled\fR\|(3). +.PP +Key validation updates +.IX Subsection "Key validation updates" +.PP +\&\fBEVP_PKEY_public_check\fR\|(3) and \fBEVP_PKEY_param_check\fR\|(3) now work for +more key types. This includes RSA, DSA, ED25519, X25519, ED448 and X448. +Previously (in 1.1.1) they would return \-2. For key types that do not have +parameters \fBEVP_PKEY_param_check\fR\|(3) will always return 1. +.PP +\fIOther notable deprecations and changes\fR +.IX Subsection "Other notable deprecations and changes" +.PP +The function code part of an OpenSSL error code is no longer relevant +.IX Subsection "The function code part of an OpenSSL error code is no longer relevant" +.PP +This code is now always set to zero. Related functions are deprecated. +.PP +STACK and HASH macros have been cleaned up +.IX Subsection "STACK and HASH macros have been cleaned up" +.PP +The type\-safe wrappers are declared everywhere and implemented once. +See \fBDEFINE_STACK_OF\fR\|(3) and \fBDEFINE_LHASH_OF_EX\fR\|(3). +.PP +The RAND_DRBG subsystem has been removed +.IX Subsection "The RAND_DRBG subsystem has been removed" +.PP +The new \fBEVP_RAND\fR\|(3) is a partial replacement: the DRBG callback framework is +absent. The RAND_DRBG API did not fit well into the new provider concept as +implemented by EVP_RAND and EVP_RAND_CTX. +.PP +Removed \fBFIPS_mode()\fR and \fBFIPS_mode_set()\fR +.IX Subsection "Removed FIPS_mode() and FIPS_mode_set()" +.PP +These functions are legacy APIs that are not applicable to the new provider +model. Applications should instead use +\&\fBEVP_default_properties_is_fips_enabled\fR\|(3) and +\&\fBEVP_default_properties_enable_fips\fR\|(3). +.PP +Key generation is slower +.IX Subsection "Key generation is slower" +.PP +The Miller\-Rabin test now uses 64 rounds, which is used for all prime generation, +including RSA key generation. This affects the time for larger keys sizes. +.PP +The default key generation method for the regular 2\-prime RSA keys was changed +to the FIPS186\-4 B.3.6 method (Generation of Probable Primes with Conditions +Based on Auxiliary Probable Primes). This method is slower than the original +method. +.PP +Change PBKDF2 to conform to SP800\-132 instead of the older PKCS5 RFC2898 +.IX Subsection "Change PBKDF2 to conform to SP800-132 instead of the older PKCS5 RFC2898" +.PP +This checks that the salt length is at least 128 bits, the derived key length is +at least 112 bits, and that the iteration count is at least 1000. +For backwards compatibility these checks are disabled by default in the +default provider, but are enabled by default in the FIPS provider. +.PP +To enable or disable the checks see \fBOSSL_KDF_PARAM_PKCS5\fR in +\&\fBEVP_KDF\-PBKDF2\fR\|(7). The parameter can be set using \fBEVP_KDF_derive\fR\|(3). +.PP +Enforce a minimum DH modulus size of 512 bits +.IX Subsection "Enforce a minimum DH modulus size of 512 bits" +.PP +Smaller sizes now result in an error. +.PP +SM2 key changes +.IX Subsection "SM2 key changes" +.PP +EC EVP_PKEYs with the SM2 curve have been reworked to automatically become +EVP_PKEY_SM2 rather than EVP_PKEY_EC. +.PP +Unlike in previous OpenSSL versions, this means that applications cannot +call \fBEVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)\fR to get SM2 computations. +.PP +Parameter and key generation is also reworked to make it possible +to generate EVP_PKEY_SM2 parameters and keys. Applications must now generate +SM2 keys directly and must not create an EVP_PKEY_EC key first. It is no longer +possible to import an SM2 key with domain parameters other than the SM2 elliptic +curve ones. +.PP +Validation of SM2 keys has been separated from the validation of regular EC +keys, allowing to improve the SM2 validation process to reject loaded private +keys that are not conforming to the SM2 ISO standard. +In particular, a private scalar \fIk\fR outside the range \fI1 <= k < n\-1\fR is +now correctly rejected. +.PP +\fBEVP_PKEY_set_alias_type()\fR method has been removed +.IX Subsection "EVP_PKEY_set_alias_type() method has been removed" +.PP +This function made a \fBEVP_PKEY\fR object mutable after it had been set up. In +OpenSSL 3.0 it was decided that a provided key should not be able to change its +type, so this function has been removed. +.PP +Functions that return an internal key should be treated as read only +.IX Subsection "Functions that return an internal key should be treated as read only" +.PP +Functions such as \fBEVP_PKEY_get0_RSA\fR\|(3) behave slightly differently in +OpenSSL 3.0. Previously they returned a pointer to the low\-level key used +internally by libcrypto. From OpenSSL 3.0 this key may now be held in a +provider. Calling these functions will only return a handle on the internal key +where the EVP_PKEY was constructed using this key in the first place, for +example using a function or macro such as \fBEVP_PKEY_assign_RSA\fR\|(3), +\&\fBEVP_PKEY_set1_RSA\fR\|(3), etc. +Where the EVP_PKEY holds a provider managed key, then these functions now return +a cached copy of the key. Changes to the internal provider key that take place +after the first time the cached key is accessed will not be reflected back in +the cached copy. Similarly any changes made to the cached copy by application +code will not be reflected back in the internal provider key. +.PP +For the above reasons the keys returned from these functions should typically be +treated as read\-only. To emphasise this the value returned from +\&\fBEVP_PKEY_get0_RSA\fR\|(3), \fBEVP_PKEY_get0_DSA\fR\|(3), \fBEVP_PKEY_get0_EC_KEY\fR\|(3) and +\&\fBEVP_PKEY_get0_DH\fR\|(3) have been made const. This may break some existing code. +Applications broken by this change should be modified. The preferred solution is +to refactor the code to avoid the use of these deprecated functions. Failing +this the code should be modified to use a const pointer instead. +The \fBEVP_PKEY_get1_RSA\fR\|(3), \fBEVP_PKEY_get1_DSA\fR\|(3), \fBEVP_PKEY_get1_EC_KEY\fR\|(3) +and \fBEVP_PKEY_get1_DH\fR\|(3) functions continue to return a non\-const pointer to +enable them to be "freed". However they should also be treated as read\-only. +.PP +The public key check has moved from \fBEVP_PKEY_derive()\fR to \fBEVP_PKEY_derive_set_peer()\fR +.IX Subsection "The public key check has moved from EVP_PKEY_derive() to EVP_PKEY_derive_set_peer()" +.PP +This may mean result in an error in \fBEVP_PKEY_derive_set_peer\fR\|(3) rather than +during \fBEVP_PKEY_derive\fR\|(3). +To disable this check use EVP_PKEY_derive_set_peer_ex(dh, peer, 0). +.PP +The print format has cosmetic changes for some functions +.IX Subsection "The print format has cosmetic changes for some functions" +.PP +The output from numerous "printing" functions such as \fBX509_signature_print\fR\|(3), +\&\fBX509_print_ex\fR\|(3), \fBX509_CRL_print_ex\fR\|(3), and other similar functions has been +amended such that there may be cosmetic differences between the output +observed in 1.1.1 and 3.0. This also applies to the \fB\-text\fR output from the +\&\fBopenssl x509\fR and \fBopenssl crl\fR applications. +.PP +Interactive mode from the \fBopenssl\fR program has been removed +.IX Subsection "Interactive mode from the openssl program has been removed" +.PP +From now on, running it without arguments is equivalent to \fBopenssl help\fR. +.PP +The error return values from some control calls (ctrl) have changed +.IX Subsection "The error return values from some control calls (ctrl) have changed" +.PP +One significant change is that controls which used to return \-2 for +invalid inputs, now return \-1 indicating a generic error condition instead. +.PP +DH and DHX key types have different settable parameters +.IX Subsection "DH and DHX key types have different settable parameters" +.PP +Previously (in 1.1.1) these conflicting parameters were allowed, but will now +result in errors. See \fBEVP_PKEY\-DH\fR\|(7) for further details. This affects the +behaviour of \fBopenssl\-genpkey\fR\|(1) for DH parameter generation. +.PP +\fBEVP_CIPHER_CTX_set_flags()\fR ordering change +.IX Subsection "EVP_CIPHER_CTX_set_flags() ordering change" +.PP +If using a cipher from a provider the \fBEVP_CIPH_FLAG_LENGTH_BITS\fR flag can only +be set \fBafter\fR the cipher has been assigned to the cipher context. +See "FLAGS" in \fBEVP_EncryptInit\fR\|(3) for more information. +.PP +Validation of operation context parameters +.IX Subsection "Validation of operation context parameters" +.PP +Due to move of the implementation of cryptographic operations to the +providers, validation of various operation parameters can be postponed until +the actual operation is executed where previously it happened immediately +when an operation parameter was set. +.PP +For example when setting an unsupported curve with +\&\fBEVP_PKEY_CTX_set_ec_paramgen_curve_nid()\fR this function call will not fail +but later keygen operations with the EVP_PKEY_CTX will fail. +.PP +Removal of function code from the error codes +.IX Subsection "Removal of function code from the error codes" +.PP +The function code part of the error code is now always set to 0. For that +reason the \fBERR_GET_FUNC()\fR macro was removed. Applications must resolve +the error codes only using the library number and the reason code. +.PP +ChaCha20\-Poly1305 cipher does not allow a truncated IV length to be used +.IX Subsection "ChaCha20-Poly1305 cipher does not allow a truncated IV length to be used" +.PP +In OpenSSL 3.0 setting the IV length to any value other than 12 will result in an +error. +Prior to OpenSSL 3.0 the ivlen could be smaller that the required 12 byte length, +using EVP_CIPHER_CTX_ctrl(ctx, EVP_CRTL_AEAD_SET_IVLEN, ivlen, NULL). This resulted +in an IV that had leading zero padding. +.SS "Installation and Compilation" +.IX Subsection "Installation and Compilation" +Please refer to the INSTALL.md file in the top of the distribution for +instructions on how to build and install OpenSSL 3.0. Please also refer to the +various platform specific NOTES files for your specific platform. +.SS "Upgrading from OpenSSL 1.1.1" +.IX Subsection "Upgrading from OpenSSL 1.1.1" +Upgrading to OpenSSL 3.0 from OpenSSL 1.1.1 should be relatively straight +forward in most cases. The most likely area where you will encounter problems +is if you have used low level APIs in your code (as discussed above). In that +case you are likely to start seeing deprecation warnings when compiling your +application. If this happens you have 3 options: +.IP 1. 4 +Ignore the warnings. They are just warnings. The deprecated functions are still present and you may still use them. However be aware that they may be removed from a future version of OpenSSL. +.IP 2. 4 +Suppress the warnings. Refer to your compiler documentation on how to do this. +.IP 3. 4 +Remove your usage of the low level APIs. In this case you will need to rewrite your code to use the high level APIs instead +.PP +\fIError code changes\fR +.IX Subsection "Error code changes" +.PP +As OpenSSL 3.0 provides a brand new Encoder/Decoder mechanism for working with +widely used file formats, application code that checks for particular error +reason codes on key loading failures might need an update. +.PP +Password\-protected keys may deserve special attention. If only some errors +are treated as an indicator that the user should be asked about the password again, +it\*(Aqs worth testing these scenarios and processing the newly relevant codes. +.PP +There may be more cases to treat specially, depending on the calling application code. +.SS "Upgrading from OpenSSL 1.0.2" +.IX Subsection "Upgrading from OpenSSL 1.0.2" +Upgrading to OpenSSL 3.0 from OpenSSL 1.0.2 is likely to be significantly more +difficult. In addition to the issues discussed above in the section about +"Upgrading from OpenSSL 1.1.1", the main things to be aware of are: +.IP 1. 4 +The build and installation procedure has changed significantly. +.Sp +Check the file INSTALL.md in the top of the installation for instructions on how +to build and install OpenSSL for your platform. Also read the various NOTES +files in the same directory, as applicable for your platform. +.IP 2. 4 +Many structures have been made opaque in OpenSSL 3.0. +.Sp +The structure definitions have been removed from the public header files and +moved to internal header files. In practice this means that you can no longer +stack allocate some structures. Instead they must be heap allocated through some +function call (typically those function names have a \f(CW\*(C`_new\*(C'\fR suffix to them). +Additionally you must use "setter" or "getter" functions to access the fields +within those structures. +.Sp +For example code that previously looked like this: +.Sp +.Vb 1 +\& EVP_MD_CTX md_ctx; +\& +\& /* This line will now generate compiler errors */ +\& EVP_MD_CTX_init(&md_ctx); +.Ve +.Sp +The code needs to be amended to look like this: +.Sp +.Vb 1 +\& EVP_MD_CTX *md_ctx; +\& +\& md_ctx = EVP_MD_CTX_new(); +\& ... +\& ... +\& EVP_MD_CTX_free(md_ctx); +.Ve +.IP 3. 4 +Support for TLSv1.3 has been added. +.Sp +This has a number of implications for SSL/TLS applications. See the +TLS1.3 page for further details. +.PP +More details about the breaking changes between OpenSSL versions 1.0.2 and 1.1.0 +can be found on the +OpenSSL 1.1.0 Changes page . +.PP +\fIUpgrading from the OpenSSL 2.0 FIPS Object Module\fR +.IX Subsection "Upgrading from the OpenSSL 2.0 FIPS Object Module" +.PP +The OpenSSL 2.0 FIPS Object Module was a separate download that had to be built +separately and then integrated into your main OpenSSL 1.0.2 build. +In OpenSSL 3.0 the FIPS support is fully integrated into the mainline version of +OpenSSL and is no longer a separate download. For further information see +"Completing the installation of the FIPS Module". +.PP +The function calls \fBFIPS_mode()\fR and \fBFIPS_mode_set()\fR have been removed +from OpenSSL 3.0. You should rewrite your application to not use them. +See \fBfips_module\fR\|(7) and \fBOSSL_PROVIDER\-FIPS\fR\|(7) for details. +.SS "Completing the installation of the FIPS Module" +.IX Subsection "Completing the installation of the FIPS Module" +The FIPS Module will be built and installed automatically if FIPS support has +been configured. The current documentation can be found in the +README\-FIPS file. +.SS Programming +.IX Subsection "Programming" +Applications written to work with OpenSSL 1.1.1 will mostly just work with +OpenSSL 3.0. However changes will be required if you want to take advantage of +some of the new features that OpenSSL 3.0 makes available. In order to do that +you need to understand some new concepts introduced in OpenSSL 3.0. +Read "Library contexts" in \fBcrypto\fR\|(7) for further information. +.PP +\fILibrary Context\fR +.IX Subsection "Library Context" +.PP +A library context allows different components of a complex application to each +use a different library context and have different providers loaded with +different configuration settings. +See "Library contexts" in \fBcrypto\fR\|(7) for further info. +.PP +If the user creates an \fBOSSL_LIB_CTX\fR via \fBOSSL_LIB_CTX_new\fR\|(3) then many +functions may need to be changed to pass additional parameters to handle the +library context. +.PP +Using a Library Context \- Old functions that should be changed +.IX Subsection "Using a Library Context - Old functions that should be changed" +.PP +If a library context is needed then all EVP_* digest functions that return a +\&\fBconst EVP_MD *\fR such as \fBEVP_sha256()\fR should be replaced with a call to +\&\fBEVP_MD_fetch\fR\|(3). See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7). +.PP +If a library context is needed then all EVP_* cipher functions that return a +\&\fBconst EVP_CIPHER *\fR such as \fBEVP_aes_128_cbc()\fR should be replaced vith a call to +\&\fBEVP_CIPHER_fetch\fR\|(3). See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7). +.PP +Some functions can be passed an object that has already been set up with a library +context such as \fBd2i_X509\fR\|(3), \fBd2i_X509_CRL\fR\|(3), \fBd2i_X509_REQ\fR\|(3) and +\&\fBd2i_X509_PUBKEY\fR\|(3). If NULL is passed instead then the created object will be +set up with the default library context. Use \fBX509_new_ex\fR\|(3), +\&\fBX509_CRL_new_ex\fR\|(3), \fBX509_REQ_new_ex\fR\|(3) and \fBX509_PUBKEY_new_ex\fR\|(3) if a +library context is required. +.PP +All functions listed below with a \fINAME\fR have a replacement function \fINAME_ex\fR +that takes \fBOSSL_LIB_CTX\fR as an additional argument. Functions that have other +mappings are listed along with the respective name. +.IP \(bu 4 +\&\fBASN1_item_new\fR\|(3), \fBASN1_item_d2i\fR\|(3), \fBASN1_item_d2i_fp\fR\|(3), +\&\fBASN1_item_d2i_bio\fR\|(3), \fBASN1_item_sign\fR\|(3) and \fBASN1_item_verify\fR\|(3) +.IP \(bu 4 +\&\fBBIO_new\fR\|(3) +.IP \(bu 4 +\&\fBb2i_RSA_PVK_bio()\fR and \fBi2b_PVK_bio()\fR +.IP \(bu 4 +\&\fBBN_CTX_new\fR\|(3) and \fBBN_CTX_secure_new\fR\|(3) +.IP \(bu 4 +\&\fBCMS_AuthEnvelopedData_create\fR\|(3), \fBCMS_ContentInfo_new\fR\|(3), \fBCMS_data_create\fR\|(3), +\&\fBCMS_digest_create\fR\|(3), \fBCMS_EncryptedData_encrypt\fR\|(3), \fBCMS_encrypt\fR\|(3), +\&\fBCMS_EnvelopedData_create\fR\|(3), \fBCMS_ReceiptRequest_create0\fR\|(3) and \fBCMS_sign\fR\|(3) +.IP \(bu 4 +\&\fBCONF_modules_load_file\fR\|(3) +.IP \(bu 4 +\&\fBCTLOG_new\fR\|(3), \fBCTLOG_new_from_base64\fR\|(3) and \fBCTLOG_STORE_new\fR\|(3) +.IP \(bu 4 +\&\fBCT_POLICY_EVAL_CTX_new\fR\|(3) +.IP \(bu 4 +\&\fBd2i_AutoPrivateKey\fR\|(3), \fBd2i_PrivateKey\fR\|(3) and \fBd2i_PUBKEY\fR\|(3) +.IP \(bu 4 +\&\fBd2i_PrivateKey_bio\fR\|(3) and \fBd2i_PrivateKey_fp\fR\|(3) +.Sp +Use \fBd2i_PrivateKey_ex_bio\fR\|(3) and \fBd2i_PrivateKey_ex_fp\fR\|(3) +.IP \(bu 4 +\&\fBEC_GROUP_new\fR\|(3) +.Sp +Use \fBEC_GROUP_new_by_curve_name_ex\fR\|(3) or \fBEC_GROUP_new_from_params\fR\|(3). +.IP \(bu 4 +\&\fBEVP_DigestSignInit\fR\|(3) and \fBEVP_DigestVerifyInit\fR\|(3) +.IP \(bu 4 +\&\fBEVP_PBE_CipherInit\fR\|(3), \fBEVP_PBE_find\fR\|(3) and \fBEVP_PBE_scrypt\fR\|(3) +.IP \(bu 4 +\&\fBPKCS5_PBE_keyivgen\fR\|(3) +.IP \(bu 4 +\&\fBEVP_PKCS82PKEY\fR\|(3) +.IP \(bu 4 +\&\fBEVP_PKEY_CTX_new_id\fR\|(3) +.Sp +Use \fBEVP_PKEY_CTX_new_from_name\fR\|(3) +.IP \(bu 4 +\&\fBEVP_PKEY_derive_set_peer\fR\|(3), \fBEVP_PKEY_new_raw_private_key\fR\|(3) +and \fBEVP_PKEY_new_raw_public_key\fR\|(3) +.IP \(bu 4 +\&\fBEVP_SignFinal\fR\|(3) and \fBEVP_VerifyFinal\fR\|(3) +.IP \(bu 4 +\&\fBNCONF_new\fR\|(3) +.IP \(bu 4 +\&\fBOCSP_RESPID_match\fR\|(3) and \fBOCSP_RESPID_set_by_key\fR\|(3) +.IP \(bu 4 +\&\fBOPENSSL_thread_stop\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_STORE_open\fR\|(3) +.IP \(bu 4 +\&\fBPEM_read_bio_Parameters\fR\|(3), \fBPEM_read_bio_PrivateKey\fR\|(3), \fBPEM_read_bio_PUBKEY\fR\|(3), +\&\fBPEM_read_PrivateKey\fR\|(3) and \fBPEM_read_PUBKEY\fR\|(3) +.IP \(bu 4 +\&\fBPEM_write_bio_PrivateKey\fR\|(3), \fBPEM_write_bio_PUBKEY\fR\|(3), \fBPEM_write_PrivateKey\fR\|(3) +and \fBPEM_write_PUBKEY\fR\|(3) +.IP \(bu 4 +\&\fBPEM_X509_INFO_read_bio\fR\|(3) and \fBPEM_X509_INFO_read\fR\|(3) +.IP \(bu 4 +\&\fBPKCS12_add_key\fR\|(3), \fBPKCS12_add_safe\fR\|(3), \fBPKCS12_add_safes\fR\|(3), +\&\fBPKCS12_create\fR\|(3), \fBPKCS12_decrypt_skey\fR\|(3), \fBPKCS12_init\fR\|(3), \fBPKCS12_item_decrypt_d2i\fR\|(3), +\&\fBPKCS12_item_i2d_encrypt\fR\|(3), \fBPKCS12_key_gen_asc\fR\|(3), \fBPKCS12_key_gen_uni\fR\|(3), +\&\fBPKCS12_key_gen_utf8\fR\|(3), \fBPKCS12_pack_p7encdata\fR\|(3), \fBPKCS12_pbe_crypt\fR\|(3), +\&\fBPKCS12_PBE_keyivgen\fR\|(3), \fBPKCS12_SAFEBAG_create_pkcs8_encrypt\fR\|(3) +.IP \(bu 4 +\&\fBPKCS5_pbe_set0_algor\fR\|(3), \fBPKCS5_pbe_set\fR\|(3), \fBPKCS5_pbe2_set_iv\fR\|(3), +\&\fBPKCS5_pbkdf2_set\fR\|(3) and \fBPKCS5_v2_scrypt_keyivgen\fR\|(3) +.IP \(bu 4 +\&\fBPKCS7_encrypt\fR\|(3), \fBPKCS7_new\fR\|(3) and \fBPKCS7_sign\fR\|(3) +.IP \(bu 4 +\&\fBPKCS8_decrypt\fR\|(3), \fBPKCS8_encrypt\fR\|(3) and \fBPKCS8_set0_pbe\fR\|(3) +.IP \(bu 4 +\&\fBRAND_bytes\fR\|(3) and \fBRAND_priv_bytes\fR\|(3) +.IP \(bu 4 +\&\fBSMIME_write_ASN1\fR\|(3) +.IP \(bu 4 +\&\fBSSL_load_client_CA_file\fR\|(3) +.IP \(bu 4 +\&\fBSSL_CTX_new\fR\|(3) +.IP \(bu 4 +\&\fBTS_RESP_CTX_new\fR\|(3) +.IP \(bu 4 +\&\fBX509_CRL_new\fR\|(3) +.IP \(bu 4 +\&\fBX509_load_cert_crl_file\fR\|(3) and \fBX509_load_cert_file\fR\|(3) +.IP \(bu 4 +\&\fBX509_LOOKUP_by_subject\fR\|(3) and \fBX509_LOOKUP_ctrl\fR\|(3) +.IP \(bu 4 +\&\fBX509_NAME_hash\fR\|(3) +.IP \(bu 4 +\&\fBX509_new\fR\|(3) +.IP \(bu 4 +\&\fBX509_REQ_new\fR\|(3) and \fBX509_REQ_verify\fR\|(3) +.IP \(bu 4 +\&\fBX509_STORE_CTX_new\fR\|(3), \fBX509_STORE_set_default_paths\fR\|(3), \fBX509_STORE_load_file\fR\|(3), +\&\fBX509_STORE_load_locations\fR\|(3) and \fBX509_STORE_load_store\fR\|(3) +.PP +New functions that use a Library context +.IX Subsection "New functions that use a Library context" +.PP +The following functions can be passed a library context if required. +Passing NULL will use the default library context. +.IP \(bu 4 +\&\fBBIO_new_from_core_bio\fR\|(3) +.IP \(bu 4 +\&\fBEVP_ASYM_CIPHER_fetch\fR\|(3) and \fBEVP_ASYM_CIPHER_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_CIPHER_fetch\fR\|(3) and \fBEVP_CIPHER_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_default_properties_enable_fips\fR\|(3) and +\&\fBEVP_default_properties_is_fips_enabled\fR\|(3) +.IP \(bu 4 +\&\fBEVP_KDF_fetch\fR\|(3) and \fBEVP_KDF_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_KEM_fetch\fR\|(3) and \fBEVP_KEM_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_KEYEXCH_fetch\fR\|(3) and \fBEVP_KEYEXCH_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_KEYMGMT_fetch\fR\|(3) and \fBEVP_KEYMGMT_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_MAC_fetch\fR\|(3) and \fBEVP_MAC_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_MD_fetch\fR\|(3) and \fBEVP_MD_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_PKEY_CTX_new_from_pkey\fR\|(3) +.IP \(bu 4 +\&\fBEVP_PKEY_Q_keygen\fR\|(3) +.IP \(bu 4 +\&\fBEVP_Q_mac\fR\|(3) and \fBEVP_Q_digest\fR\|(3) +.IP \(bu 4 +\&\fBEVP_RAND\fR\|(3) and \fBEVP_RAND_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBEVP_set_default_properties\fR\|(3) +.IP \(bu 4 +\&\fBEVP_SIGNATURE_fetch\fR\|(3) and \fBEVP_SIGNATURE_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_CMP_CTX_new\fR\|(3) and \fBOSSL_CMP_SRV_CTX_new\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_CRMF_ENCRYPTEDVALUE_get1_encCert\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_CRMF_MSG_create_popo\fR\|(3) and \fBOSSL_CRMF_MSGS_verify_popo\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_CRMF_pbm_new\fR\|(3) and \fBOSSL_CRMF_pbmp_new\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_DECODER_CTX_add_extra\fR\|(3) and \fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_DECODER_fetch\fR\|(3) and \fBOSSL_DECODER_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_ENCODER_CTX_add_extra\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_ENCODER_fetch\fR\|(3) and \fBOSSL_ENCODER_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_LIB_CTX_free\fR\|(3), \fBOSSL_LIB_CTX_load_config\fR\|(3) and \fBOSSL_LIB_CTX_set0_default\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_PROVIDER_add_builtin\fR\|(3), \fBOSSL_PROVIDER_available\fR\|(3), +\&\fBOSSL_PROVIDER_do_all\fR\|(3), \fBOSSL_PROVIDER_load\fR\|(3), +\&\fBOSSL_PROVIDER_set_default_search_path\fR\|(3) and \fBOSSL_PROVIDER_try_load\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_SELF_TEST_get_callback\fR\|(3) and \fBOSSL_SELF_TEST_set_callback\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_STORE_attach\fR\|(3) +.IP \(bu 4 +\&\fBOSSL_STORE_LOADER_fetch\fR\|(3) and \fBOSSL_STORE_LOADER_do_all_provided\fR\|(3) +.IP \(bu 4 +\&\fBRAND_get0_primary\fR\|(3), \fBRAND_get0_private\fR\|(3), \fBRAND_get0_public\fR\|(3), +\&\fBRAND_set_DRBG_type\fR\|(3) and \fBRAND_set_seed_source_type\fR\|(3) +.PP +\fIProviders\fR +.IX Subsection "Providers" +.PP +Providers are described in detail here "Providers" in \fBcrypto\fR\|(7). +See also "OPENSSL PROVIDERS" in \fBcrypto\fR\|(7). +.PP +\fIFetching algorithms and property queries\fR +.IX Subsection "Fetching algorithms and property queries" +.PP +Implicit and Explicit Fetching is described in detail here +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7). +.PP +\fIMapping EVP controls and flags to provider \fR\f(BIOSSL_PARAM\fR\fI\|(3) parameters\fR +.IX Subsection "Mapping EVP controls and flags to provider OSSL_PARAM parameters" +.PP +The existing functions for controls (such as \fBEVP_CIPHER_CTX_ctrl\fR\|(3)) and +manipulating flags (such as \fBEVP_MD_CTX_set_flags\fR\|(3))internally use +\&\fBOSSL_PARAMS\fR to pass information to/from provider objects. +See \fBOSSL_PARAM\fR\|(3) for additional information related to parameters. +.PP +For ciphers see "CONTROLS" in \fBEVP_EncryptInit\fR\|(3), "FLAGS" in \fBEVP_EncryptInit\fR\|(3) and +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.PP +For digests see "CONTROLS" in \fBEVP_DigestInit\fR\|(3), "FLAGS" in \fBEVP_DigestInit\fR\|(3) and +"PARAMETERS" in \fBEVP_DigestInit\fR\|(3). +.PP +\fIDeprecation of Low Level Functions\fR +.IX Subsection "Deprecation of Low Level Functions" +.PP +A significant number of APIs have been deprecated in OpenSSL 3.0. +This section describes some common categories of deprecations. +See "Deprecated function mappings" for the list of deprecated functions +that refer to these categories. +.PP +Providers are a replacement for engines and low\-level method overrides +.IX Subsection "Providers are a replacement for engines and low-level method overrides" +.PP +Any accessor that uses an ENGINE is deprecated (such as \fBEVP_PKEY_set1_engine()\fR). +Applications using engines should instead use providers. +.PP +Before providers were added algorithms were overridden by changing the methods +used by algorithms. All these methods such as \fBRSA_new_method()\fR and \fBRSA_meth_new()\fR +are now deprecated and can be replaced by using providers instead. +.PP +Deprecated i2d and d2i functions for low\-level key types +.IX Subsection "Deprecated i2d and d2i functions for low-level key types" +.PP +Any i2d and d2i functions such as \fBd2i_DHparams()\fR that take a low\-level key type +have been deprecated. Applications should instead use the \fBOSSL_DECODER\fR\|(3) and +\&\fBOSSL_ENCODER\fR\|(3) APIs to read and write files. +See "Migration" in \fBd2i_RSAPrivateKey\fR\|(3) for further details. +.PP +Deprecated low\-level key object getters and setters +.IX Subsection "Deprecated low-level key object getters and setters" +.PP +Applications that set or get low\-level key objects (such as \fBEVP_PKEY_set1_DH()\fR +or \fBEVP_PKEY_get0()\fR) should instead use the OSSL_ENCODER +(See \fBOSSL_ENCODER_to_bio\fR\|(3)) or OSSL_DECODER (See \fBOSSL_DECODER_from_bio\fR\|(3)) +APIs, or alternatively use \fBEVP_PKEY_fromdata\fR\|(3) or \fBEVP_PKEY_todata\fR\|(3). +.PP +Deprecated low\-level key parameter getters +.IX Subsection "Deprecated low-level key parameter getters" +.PP +Functions that access low\-level objects directly such as \fBRSA_get0_n\fR\|(3) are now +deprecated. Applications should use one of: +\&\fBEVP_PKEY_get_bn_param\fR\|(3), +\&\fBEVP_PKEY_get_int_param\fR\|(3), +\&\fBEVP_PKEY_get_size_t_param\fR\|(3), +\&\fBEVP_PKEY_get_utf8_string_param\fR\|(3), +\&\fBEVP_PKEY_get_octet_string_param\fR\|(3), or +\&\fBEVP_PKEY_get_params\fR\|(3), +to access fields from an EVP_PKEY. +Gettable parameters are listed in: +"Common RSA parameters" in \fBEVP_PKEY\-RSA\fR\|(7), +"Common EC parameters" in \fBEVP_PKEY\-EC\fR\|(7), +"DSA parameters" in \fBEVP_PKEY\-DSA\fR\|(7), +"DH parameters" in \fBEVP_PKEY\-DH\fR\|(7), +"FFC parameters" in \fBEVP_PKEY\-FFC\fR\|(7), +"Common X25519, X448, ED25519 and ED448 parameters" in \fBEVP_PKEY\-X25519\fR\|(7), +"Common parameters" in \fBEVP_PKEY\-ML\-DSA\fR\|(7), +and +"Common parameters" in \fBEVP_PKEY\-ML\-KEM\fR\|(7). +Applications may also use \fBEVP_PKEY_todata\fR\|(3) to return all fields. +.PP +Deprecated low\-level key parameter setters +.IX Subsection "Deprecated low-level key parameter setters" +.PP +Functions that access low\-level objects directly such as \fBRSA_set0_crt_params\fR\|(3) +are now deprecated. Applications should use \fBEVP_PKEY_fromdata\fR\|(3) to create +new keys from user provided key data. Keys should be immutable once they are +created, so if required the user may use \fBEVP_PKEY_todata\fR\|(3), \fBOSSL_PARAM_merge\fR\|(3), +and \fBEVP_PKEY_fromdata\fR\|(3) to create a modified key. +See "Examples" in \fBEVP_PKEY\-DH\fR\|(7) for more information. +See "Deprecated low\-level key generation functions" for information on +generating a key using parameters. +.PP +Deprecated low\-level object creation +.IX Subsection "Deprecated low-level object creation" +.PP +Low\-level objects were created using methods such as \fBRSA_new\fR\|(3), +\&\fBRSA_up_ref\fR\|(3) and \fBRSA_free\fR\|(3). Applications should instead use the +high\-level EVP_PKEY APIs, e.g. \fBEVP_PKEY_new\fR\|(3), \fBEVP_PKEY_up_ref\fR\|(3) and +\&\fBEVP_PKEY_free\fR\|(3). +See also \fBEVP_PKEY_CTX_new_from_name\fR\|(3) and \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3). +.PP +EVP_PKEYs may be created in a variety of ways: +See also "Deprecated low\-level key generation functions", +"Deprecated low\-level key reading and writing functions" and +"Deprecated low\-level key parameter setters". +.PP +Deprecated low\-level encryption functions +.IX Subsection "Deprecated low-level encryption functions" +.PP +Low\-level encryption functions such as \fBAES_encrypt\fR\|(3) and \fBAES_decrypt\fR\|(3) +have been informally discouraged from use for a long time. Applications should +instead use the high level EVP APIs \fBEVP_EncryptInit_ex\fR\|(3), +\&\fBEVP_EncryptUpdate\fR\|(3), and \fBEVP_EncryptFinal_ex\fR\|(3) or +\&\fBEVP_DecryptInit_ex\fR\|(3), \fBEVP_DecryptUpdate\fR\|(3) and \fBEVP_DecryptFinal_ex\fR\|(3). +.PP +Deprecated low\-level digest functions +.IX Subsection "Deprecated low-level digest functions" +.PP +Use of low\-level digest functions such as \fBSHA1_Init\fR\|(3) have been +informally discouraged from use for a long time. Applications should instead +use the high level EVP APIs \fBEVP_DigestInit_ex\fR\|(3), \fBEVP_DigestUpdate\fR\|(3) +and \fBEVP_DigestFinal_ex\fR\|(3), or the quick one\-shot \fBEVP_Q_digest\fR\|(3). +.PP +Note that the functions \fBSHA1\fR\|(3), \fBSHA224\fR\|(3), \fBSHA256\fR\|(3), \fBSHA384\fR\|(3) +and \fBSHA512\fR\|(3) have changed to macros that use \fBEVP_Q_digest\fR\|(3). +.PP +Deprecated low\-level signing functions +.IX Subsection "Deprecated low-level signing functions" +.PP +Use of low\-level signing functions such as \fBDSA_sign\fR\|(3) have been +informally discouraged for a long time. Instead applications should use +\&\fBEVP_DigestSign\fR\|(3) and \fBEVP_DigestVerify\fR\|(3). +See also \fBEVP_SIGNATURE\-RSA\fR\|(7), \fBEVP_SIGNATURE\-DSA\fR\|(7), +\&\fBEVP_SIGNATURE\-ECDSA\fR\|(7) and \fBEVP_SIGNATURE\-ED25519\fR\|(7). +.PP +Deprecated low\-level MAC functions +.IX Subsection "Deprecated low-level MAC functions" +.PP +Low\-level mac functions such as \fBCMAC_Init\fR\|(3) are deprecated. +Applications should instead use the new \fBEVP_MAC\fR\|(3) interface, using +\&\fBEVP_MAC_CTX_new\fR\|(3), \fBEVP_MAC_CTX_free\fR\|(3), \fBEVP_MAC_init\fR\|(3), +\&\fBEVP_MAC_update\fR\|(3) and \fBEVP_MAC_final\fR\|(3) or the single\-shot MAC function +\&\fBEVP_Q_mac\fR\|(3). +See \fBEVP_MAC\fR\|(3), \fBEVP_MAC\-HMAC\fR\|(7), \fBEVP_MAC\-CMAC\fR\|(7), \fBEVP_MAC\-GMAC\fR\|(7), +\&\fBEVP_MAC\-KMAC\fR\|(7), \fBEVP_MAC\-BLAKE2\fR\|(7), \fBEVP_MAC\-Poly1305\fR\|(7) and +\&\fBEVP_MAC\-Siphash\fR\|(7) for additional information. +.PP +Note that the one\-shot method \fBHMAC()\fR is still available for compatibility purposes, +but this can also be replaced by using EVP_Q_MAC if a library context is required. +.PP +Deprecated low\-level validation functions +.IX Subsection "Deprecated low-level validation functions" +.PP +Low\-level validation functions such as \fBDH_check\fR\|(3) have been informally +discouraged from use for a long time. Applications should instead use the high\-level +EVP_PKEY APIs such as \fBEVP_PKEY_check\fR\|(3), \fBEVP_PKEY_param_check\fR\|(3), +\&\fBEVP_PKEY_param_check_quick\fR\|(3), \fBEVP_PKEY_public_check\fR\|(3), +\&\fBEVP_PKEY_public_check_quick\fR\|(3), \fBEVP_PKEY_private_check\fR\|(3), +and \fBEVP_PKEY_pairwise_check\fR\|(3). +.PP +Deprecated low\-level key exchange functions +.IX Subsection "Deprecated low-level key exchange functions" +.PP +Many low\-level functions have been informally discouraged from use for a long +time. Applications should instead use \fBEVP_PKEY_derive\fR\|(3). +See \fBEVP_KEYEXCH\-DH\fR\|(7), \fBEVP_KEYEXCH\-ECDH\fR\|(7) and \fBEVP_KEYEXCH\-X25519\fR\|(7). +.PP +Deprecated low\-level key generation functions +.IX Subsection "Deprecated low-level key generation functions" +.PP +Many low\-level functions have been informally discouraged from use for a long +time. Applications should instead use \fBEVP_PKEY_keygen_init\fR\|(3) and +\&\fBEVP_PKEY_generate\fR\|(3) as described in \fBEVP_PKEY\-DSA\fR\|(7), \fBEVP_PKEY\-DH\fR\|(7), +\&\fBEVP_PKEY\-RSA\fR\|(7), \fBEVP_PKEY\-EC\fR\|(7) and \fBEVP_PKEY\-X25519\fR\|(7). +The \*(Aqquick\*(Aq one\-shot function \fBEVP_PKEY_Q_keygen\fR\|(3) and macros for the most +common cases: <\fBEVP_RSA_gen\fR\|(3)> and \fBEVP_EC_gen\fR\|(3) may also be used. +.PP +Deprecated low\-level key reading and writing functions +.IX Subsection "Deprecated low-level key reading and writing functions" +.PP +Use of low\-level objects (such as DSA) has been informally discouraged from use +for a long time. Functions to read and write these low\-level objects (such as +\&\fBPEM_read_DSA_PUBKEY()\fR) should be replaced. Applications should instead use +\&\fBOSSL_ENCODER_to_bio\fR\|(3) and \fBOSSL_DECODER_from_bio\fR\|(3). +.PP +Deprecated low\-level key printing functions +.IX Subsection "Deprecated low-level key printing functions" +.PP +Use of low\-level objects (such as DSA) has been informally discouraged from use +for a long time. Functions to print these low\-level objects such as +\&\fBDSA_print()\fR should be replaced with the equivalent EVP_PKEY functions. +Application should use one of \fBEVP_PKEY_print_public\fR\|(3), +\&\fBEVP_PKEY_print_private\fR\|(3), \fBEVP_PKEY_print_params\fR\|(3), +\&\fBEVP_PKEY_print_public_fp\fR\|(3), \fBEVP_PKEY_print_private_fp\fR\|(3) or +\&\fBEVP_PKEY_print_params_fp\fR\|(3). Note that internally these use +\&\fBOSSL_ENCODER_to_bio\fR\|(3) and \fBOSSL_DECODER_from_bio\fR\|(3). +.PP +\fIDeprecated function mappings\fR +.IX Subsection "Deprecated function mappings" +.PP +The following functions have been deprecated in 3.0. +.IP \(bu 4 +\&\fBAES_bi_ige_encrypt()\fR and \fBAES_ige_encrypt()\fR +.Sp +There is no replacement for the IGE functions. New code should not use these modes. +These undocumented functions were never integrated into the EVP layer. +They implemented the AES Infinite Garble Extension (IGE) mode and AES +Bi\-directional IGE mode. These modes were never formally standardised and +usage of these functions is believed to be very small. In particular +\&\fBAES_bi_ige_encrypt()\fR has a known bug. It accepts 2 AES keys, but only one +is ever used. The security implications are believed to be minimal, but +this issue was never fixed for backwards compatibility reasons. +.IP \(bu 4 +\&\fBAES_encrypt()\fR, \fBAES_decrypt()\fR, \fBAES_set_encrypt_key()\fR, \fBAES_set_decrypt_key()\fR, +\&\fBAES_cbc_encrypt()\fR, \fBAES_cfb128_encrypt()\fR, \fBAES_cfb1_encrypt()\fR, \fBAES_cfb8_encrypt()\fR, +\&\fBAES_ecb_encrypt()\fR, \fBAES_ofb128_encrypt()\fR +.IP \(bu 4 +\&\fBAES_unwrap_key()\fR, \fBAES_wrap_key()\fR +.Sp +See "Deprecated low\-level encryption functions" +.IP \(bu 4 +\&\fBAES_options()\fR +.Sp +There is no replacement. It returned a string indicating if the AES code was unrolled. +.IP \(bu 4 +\&\fBASN1_digest()\fR, \fBASN1_sign()\fR, \fBASN1_verify()\fR +.Sp +There are no replacements. These old functions are not used, and could be +disabled with the macro NO_ASN1_OLD since OpenSSL 0.9.7. +.IP \(bu 4 +\&\fBASN1_STRING_length_set()\fR +.Sp +Use \fBASN1_STRING_set\fR\|(3) or \fBASN1_STRING_set0\fR\|(3) instead. +This was a potentially unsafe function that could change the bounds of a +previously passed in pointer. +.IP \(bu 4 +\&\fBBF_encrypt()\fR, \fBBF_decrypt()\fR, \fBBF_set_key()\fR, \fBBF_cbc_encrypt()\fR, \fBBF_cfb64_encrypt()\fR, +\&\fBBF_ecb_encrypt()\fR, \fBBF_ofb64_encrypt()\fR +.Sp +See "Deprecated low\-level encryption functions". +The Blowfish algorithm has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBBF_options()\fR +.Sp +There is no replacement. This option returned a constant string. +.IP \(bu 4 +\&\fBBIO_get_callback()\fR, \fBBIO_set_callback()\fR, \fBBIO_debug_callback()\fR +.Sp +Use the respective non\-deprecated \fB_ex()\fR functions. +.IP \(bu 4 +\&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR +.Sp +Use \fBBN_check_prime\fR\|(3) which avoids possible misuse and always uses at least +64 rounds of the Miller\-Rabin primality test. +.IP \(bu 4 +\&\fBBN_pseudo_rand()\fR, \fBBN_pseudo_rand_range()\fR +.Sp +Use \fBBN_rand\fR\|(3) and \fBBN_rand_range\fR\|(3). +.IP \(bu 4 +\&\fBBN_X931_derive_prime_ex()\fR, \fBBN_X931_generate_prime_ex()\fR, \fBBN_X931_generate_Xpq()\fR +.Sp +There are no replacements for these low\-level functions. They were used internally +by \fBRSA_X931_derive_ex()\fR and \fBRSA_X931_generate_key_ex()\fR which are also deprecated. +Use \fBEVP_PKEY_keygen\fR\|(3) instead. +.IP \(bu 4 +\&\fBCamellia_encrypt()\fR, \fBCamellia_decrypt()\fR, \fBCamellia_set_key()\fR, +\&\fBCamellia_cbc_encrypt()\fR, \fBCamellia_cfb128_encrypt()\fR, \fBCamellia_cfb1_encrypt()\fR, +\&\fBCamellia_cfb8_encrypt()\fR, \fBCamellia_ctr128_encrypt()\fR, \fBCamellia_ecb_encrypt()\fR, +\&\fBCamellia_ofb128_encrypt()\fR +.Sp +See "Deprecated low\-level encryption functions". +.IP \(bu 4 +\&\fBCAST_encrypt()\fR, \fBCAST_decrypt()\fR, \fBCAST_set_key()\fR, \fBCAST_cbc_encrypt()\fR, +\&\fBCAST_cfb64_encrypt()\fR, \fBCAST_ecb_encrypt()\fR, \fBCAST_ofb64_encrypt()\fR +.Sp +See "Deprecated low\-level encryption functions". +The CAST algorithm has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBCMAC_CTX_new()\fR, \fBCMAC_CTX_cleanup()\fR, \fBCMAC_CTX_copy()\fR, \fBCMAC_CTX_free()\fR, +\&\fBCMAC_CTX_get0_cipher_ctx()\fR +.Sp +See "Deprecated low\-level MAC functions". +.IP \(bu 4 +\&\fBCMAC_Init()\fR, \fBCMAC_Update()\fR, \fBCMAC_Final()\fR, \fBCMAC_resume()\fR +.Sp +See "Deprecated low\-level MAC functions". +.IP \(bu 4 +\&\fBCRYPTO_mem_ctrl()\fR, \fBCRYPTO_mem_debug_free()\fR, \fBCRYPTO_mem_debug_malloc()\fR, +\&\fBCRYPTO_mem_debug_pop()\fR, \fBCRYPTO_mem_debug_push()\fR, \fBCRYPTO_mem_debug_realloc()\fR, +\&\fBCRYPTO_mem_leaks()\fR, \fBCRYPTO_mem_leaks_cb()\fR, \fBCRYPTO_mem_leaks_fp()\fR, +\&\fBCRYPTO_set_mem_debug()\fR +.Sp +Memory\-leak checking has been deprecated in favor of more modern development +tools, such as compiler memory and leak sanitizers or Valgrind. +.IP \(bu 4 +\&\fBCRYPTO_cts128_encrypt_block()\fR, \fBCRYPTO_cts128_encrypt()\fR, +\&\fBCRYPTO_cts128_decrypt_block()\fR, \fBCRYPTO_cts128_decrypt()\fR, +\&\fBCRYPTO_nistcts128_encrypt_block()\fR, \fBCRYPTO_nistcts128_encrypt()\fR, +\&\fBCRYPTO_nistcts128_decrypt_block()\fR, \fBCRYPTO_nistcts128_decrypt()\fR +.Sp +Use the higher level functions \fBEVP_CipherInit_ex2()\fR, \fBEVP_CipherUpdate()\fR and +\&\fBEVP_CipherFinal_ex()\fR instead. +See the "cts_mode" parameter in +"Gettable and Settable EVP_CIPHER_CTX parameters" in \fBEVP_EncryptInit\fR\|(3). +See "EXAMPLES" in \fBEVP_EncryptInit\fR\|(3) for a AES\-256\-CBC\-CTS example. +.IP \(bu 4 +\&\fBd2i_DHparams()\fR, \fBd2i_DHxparams()\fR, \fBd2i_DSAparams()\fR, \fBd2i_DSAPrivateKey()\fR, +\&\fBd2i_DSAPrivateKey_bio()\fR, \fBd2i_DSAPrivateKey_fp()\fR, \fBd2i_DSA_PUBKEY()\fR, +\&\fBd2i_DSA_PUBKEY_bio()\fR, \fBd2i_DSA_PUBKEY_fp()\fR, \fBd2i_DSAPublicKey()\fR, +\&\fBd2i_ECParameters()\fR, \fBd2i_ECPrivateKey()\fR, \fBd2i_ECPrivateKey_bio()\fR, +\&\fBd2i_ECPrivateKey_fp()\fR, \fBd2i_EC_PUBKEY()\fR, \fBd2i_EC_PUBKEY_bio()\fR, +\&\fBd2i_EC_PUBKEY_fp()\fR, \fBd2i_RSAPrivateKey()\fR, +\&\fBd2i_RSAPrivateKey_bio()\fR, \fBd2i_RSAPrivateKey_fp()\fR, \fBd2i_RSA_PUBKEY()\fR, +\&\fBd2i_RSA_PUBKEY_bio()\fR, \fBd2i_RSA_PUBKEY_fp()\fR, \fBd2i_RSAPublicKey()\fR, +\&\fBd2i_RSAPublicKey_bio()\fR, \fBd2i_RSAPublicKey_fp()\fR +.Sp +See "Deprecated i2d and d2i functions for low\-level key types" +.IP \(bu 4 +\&\fBo2i_ECPublicKey()\fR +.Sp +Use \fBEVP_PKEY_set1_encoded_public_key\fR\|(3). +See "Deprecated low\-level key parameter setters" +.IP \(bu 4 +\&\fBDES_crypt()\fR, \fBDES_fcrypt()\fR, \fBDES_encrypt1()\fR, \fBDES_encrypt2()\fR, \fBDES_encrypt3()\fR, +\&\fBDES_decrypt3()\fR, \fBDES_ede3_cbc_encrypt()\fR, \fBDES_ede3_cfb64_encrypt()\fR, +\&\fBDES_ede3_cfb_encrypt()\fR,\fBDES_ede3_ofb64_encrypt()\fR, +\&\fBDES_ecb_encrypt()\fR, \fBDES_ecb3_encrypt()\fR, \fBDES_ofb64_encrypt()\fR, \fBDES_ofb_encrypt()\fR, +DES_cfb64_encrypt \fBDES_cfb_encrypt()\fR, \fBDES_cbc_encrypt()\fR, \fBDES_ncbc_encrypt()\fR, +\&\fBDES_pcbc_encrypt()\fR, \fBDES_xcbc_encrypt()\fR, \fBDES_cbc_cksum()\fR, \fBDES_quad_cksum()\fR, +\&\fBDES_check_key_parity()\fR, \fBDES_is_weak_key()\fR, \fBDES_key_sched()\fR, \fBDES_options()\fR, +\&\fBDES_random_key()\fR, \fBDES_set_key()\fR, \fBDES_set_key_checked()\fR, \fBDES_set_key_unchecked()\fR, +\&\fBDES_set_odd_parity()\fR, \fBDES_string_to_2keys()\fR, \fBDES_string_to_key()\fR +.Sp +See "Deprecated low\-level encryption functions". +Algorithms for "DESX\-CBC", "DES\-ECB", "DES\-CBC", "DES\-OFB", "DES\-CFB", +"DES\-CFB1" and "DES\-CFB8" have been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBDH_bits()\fR, \fBDH_security_bits()\fR, \fBDH_size()\fR +.Sp +Use \fBEVP_PKEY_get_bits\fR\|(3), \fBEVP_PKEY_get_security_bits\fR\|(3) and +\&\fBEVP_PKEY_get_size\fR\|(3). +.IP \(bu 4 +\&\fBDH_check()\fR, \fBDH_check_ex()\fR, \fBDH_check_params()\fR, \fBDH_check_params_ex()\fR, +\&\fBDH_check_pub_key()\fR, \fBDH_check_pub_key_ex()\fR +.Sp +See "Deprecated low\-level validation functions" +.IP \(bu 4 +\&\fBDH_clear_flags()\fR, \fBDH_test_flags()\fR, \fBDH_set_flags()\fR +.Sp +The \fBDH_FLAG_CACHE_MONT_P\fR flag has been deprecated without replacement. +The \fBDH_FLAG_TYPE_DH\fR and \fBDH_FLAG_TYPE_DHX\fR have been deprecated. +Use \fBEVP_PKEY_is_a()\fR to determine the type of a key. +There is no replacement for setting these flags. +.IP \(bu 4 +\&\fBDH_compute_key()\fR \fBDH_compute_key_padded()\fR +.Sp +See "Deprecated low\-level key exchange functions". +.IP \(bu 4 +\&\fBDH_new()\fR, \fBDH_new_by_nid()\fR, \fBDH_free()\fR, \fBDH_up_ref()\fR +.Sp +See "Deprecated low\-level object creation" +.IP \(bu 4 +\&\fBDH_generate_key()\fR, \fBDH_generate_parameters_ex()\fR +.Sp +See "Deprecated low\-level key generation functions". +.IP \(bu 4 +\&\fBDH_get0_pqg()\fR, \fBDH_get0_p()\fR, \fBDH_get0_q()\fR, \fBDH_get0_g()\fR, \fBDH_get0_key()\fR, +\&\fBDH_get0_priv_key()\fR, \fBDH_get0_pub_key()\fR, \fBDH_get_length()\fR, \fBDH_get_nid()\fR +.Sp +See "Deprecated low\-level key parameter getters" +.IP \(bu 4 +\&\fBDH_get_1024_160()\fR, \fBDH_get_2048_224()\fR, \fBDH_get_2048_256()\fR +.Sp +Applications should instead set the \fBOSSL_PKEY_PARAM_GROUP_NAME\fR as specified in +"DH parameters" in \fBEVP_PKEY\-DH\fR\|(7)) to one of "dh_1024_160", "dh_2048_224" or +"dh_2048_256" when generating a DH key. +.IP \(bu 4 +\&\fBDH_KDF_X9_42()\fR +.Sp +Applications should use \fBEVP_PKEY_CTX_set_dh_kdf_type\fR\|(3) instead. +.IP \(bu 4 +\&\fBDH_get_default_method()\fR, \fBDH_get0_engine()\fR, DH_meth_*(), \fBDH_new_method()\fR, +\&\fBDH_OpenSSL()\fR, \fBDH_get_ex_data()\fR, \fBDH_set_default_method()\fR, \fBDH_set_method()\fR, +\&\fBDH_set_ex_data()\fR +.Sp +See "Providers are a replacement for engines and low\-level method overrides" +.IP \(bu 4 +\&\fBDHparams_print()\fR, \fBDHparams_print_fp()\fR +.Sp +See "Deprecated low\-level key printing functions" +.IP \(bu 4 +\&\fBDH_set0_key()\fR, \fBDH_set0_pqg()\fR, \fBDH_set_length()\fR +.Sp +See "Deprecated low\-level key parameter setters" +.IP \(bu 4 +\&\fBDSA_bits()\fR, \fBDSA_security_bits()\fR, \fBDSA_size()\fR +.Sp +Use \fBEVP_PKEY_get_bits\fR\|(3), \fBEVP_PKEY_get_security_bits\fR\|(3) and +\&\fBEVP_PKEY_get_size\fR\|(3). +.IP \(bu 4 +\&\fBDHparams_dup()\fR, \fBDSA_dup_DH()\fR +.Sp +There is no direct replacement. Applications may use \fBEVP_PKEY_copy_parameters\fR\|(3) +and \fBEVP_PKEY_dup\fR\|(3) instead. +.IP \(bu 4 +\&\fBDSA_generate_key()\fR, \fBDSA_generate_parameters_ex()\fR +.Sp +See "Deprecated low\-level key generation functions". +.IP \(bu 4 +\&\fBDSA_get0_engine()\fR, \fBDSA_get_default_method()\fR, \fBDSA_get_ex_data()\fR, +\&\fBDSA_get_method()\fR, DSA_meth_*(), \fBDSA_new_method()\fR, \fBDSA_OpenSSL()\fR, +\&\fBDSA_set_default_method()\fR, \fBDSA_set_ex_data()\fR, \fBDSA_set_method()\fR +.Sp +See "Providers are a replacement for engines and low\-level method overrides". +.IP \(bu 4 +\&\fBDSA_get0_p()\fR, \fBDSA_get0_q()\fR, \fBDSA_get0_g()\fR, \fBDSA_get0_pqg()\fR, \fBDSA_get0_key()\fR, +\&\fBDSA_get0_priv_key()\fR, \fBDSA_get0_pub_key()\fR +.Sp +See "Deprecated low\-level key parameter getters". +.IP \(bu 4 +\&\fBDSA_new()\fR, \fBDSA_free()\fR, \fBDSA_up_ref()\fR +.Sp +See "Deprecated low\-level object creation" +.IP \(bu 4 +\&\fBDSAparams_dup()\fR +.Sp +There is no direct replacement. Applications may use \fBEVP_PKEY_copy_parameters\fR\|(3) +and \fBEVP_PKEY_dup\fR\|(3) instead. +.IP \(bu 4 +\&\fBDSAparams_print()\fR, \fBDSAparams_print_fp()\fR, \fBDSA_print()\fR, \fBDSA_print_fp()\fR +.Sp +See "Deprecated low\-level key printing functions" +.IP \(bu 4 +\&\fBDSA_set0_key()\fR, \fBDSA_set0_pqg()\fR +.Sp +See "Deprecated low\-level key parameter setters" +.IP \(bu 4 +\&\fBDSA_set_flags()\fR, \fBDSA_clear_flags()\fR, \fBDSA_test_flags()\fR +.Sp +The \fBDSA_FLAG_CACHE_MONT_P\fR flag has been deprecated without replacement. +.IP \(bu 4 +\&\fBDSA_sign()\fR, \fBDSA_do_sign()\fR, \fBDSA_sign_setup()\fR, \fBDSA_verify()\fR, \fBDSA_do_verify()\fR +.Sp +See "Deprecated low\-level signing functions". +.IP \(bu 4 +\&\fBECDH_compute_key()\fR +.Sp +See "Deprecated low\-level key exchange functions". +.IP \(bu 4 +\&\fBECDH_KDF_X9_62()\fR +.Sp +Applications may either set this using the helper function +\&\fBEVP_PKEY_CTX_set_ecdh_kdf_type\fR\|(3) or by setting an \fBOSSL_PARAM\fR\|(3) using the +"kdf\-type" as shown in "EXAMPLES" in \fBEVP_KEYEXCH\-ECDH\fR\|(7) +.IP \(bu 4 +\&\fBECDSA_sign()\fR, \fBECDSA_sign_ex()\fR, \fBECDSA_sign_setup()\fR, \fBECDSA_do_sign()\fR, +\&\fBECDSA_do_sign_ex()\fR, \fBECDSA_verify()\fR, \fBECDSA_do_verify()\fR +.Sp +See "Deprecated low\-level signing functions". +.IP \(bu 4 +\&\fBECDSA_size()\fR +.Sp +Applications should use \fBEVP_PKEY_get_size\fR\|(3). +.IP \(bu 4 +\&\fBEC_GF2m_simple_method()\fR, \fBEC_GFp_mont_method()\fR, \fBEC_GFp_nist_method()\fR, +\&\fBEC_GFp_nistp224_method()\fR, \fBEC_GFp_nistp256_method()\fR, \fBEC_GFp_nistp521_method()\fR, +\&\fBEC_GFp_simple_method()\fR +.Sp +There are no replacements for these functions. Applications should rely on the +library automatically assigning a suitable method internally when an EC_GROUP +is constructed. +.IP \(bu 4 +\&\fBEC_GROUP_clear_free()\fR +.Sp +Use \fBEC_GROUP_free\fR\|(3) instead. +.IP \(bu 4 +\&\fBEC_GROUP_get_curve_GF2m()\fR, \fBEC_GROUP_get_curve_GFp()\fR, \fBEC_GROUP_set_curve_GF2m()\fR, +\&\fBEC_GROUP_set_curve_GFp()\fR +.Sp +Applications should use \fBEC_GROUP_get_curve\fR\|(3) and \fBEC_GROUP_set_curve\fR\|(3). +.IP \(bu 4 +\&\fBEC_GROUP_have_precompute_mult()\fR, \fBEC_GROUP_precompute_mult()\fR, +\&\fBEC_KEY_precompute_mult()\fR +.Sp +These functions are not widely used. Applications should instead switch to +named curves which OpenSSL has hardcoded lookup tables for. +.IP \(bu 4 +\&\fBEC_GROUP_new()\fR, \fBEC_GROUP_method_of()\fR, \fBEC_POINT_method_of()\fR +.Sp +EC_METHOD is now an internal\-only concept and a suitable EC_METHOD is assigned +internally without application intervention. +Users of \fBEC_GROUP_new()\fR should switch to a different suitable constructor. +.IP \(bu 4 +\&\fBEC_KEY_can_sign()\fR +.Sp +Applications should use \fBEVP_PKEY_can_sign\fR\|(3) instead. +.IP \(bu 4 +\&\fBEC_KEY_check_key()\fR +.Sp +See "Deprecated low\-level validation functions" +.IP \(bu 4 +\&\fBEC_KEY_set_flags()\fR, \fBEC_KEY_get_flags()\fR, \fBEC_KEY_clear_flags()\fR +.Sp +See "Common EC parameters" in \fBEVP_PKEY\-EC\fR\|(7) which handles flags as separate +parameters for \fBOSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT\fR, +\&\fBOSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE\fR, \fBOSSL_PKEY_PARAM_EC_ENCODING\fR, +\&\fBOSSL_PKEY_PARAM_USE_COFACTOR_ECDH\fR and +\&\fBOSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC\fR. +See also "EXAMPLES" in \fBEVP_PKEY\-EC\fR\|(7) +.IP \(bu 4 +\&\fBEC_KEY_dup()\fR, \fBEC_KEY_copy()\fR +.Sp +There is no direct replacement. Applications may use \fBEVP_PKEY_copy_parameters\fR\|(3) +and \fBEVP_PKEY_dup\fR\|(3) instead. +.IP \(bu 4 +\&\fBEC_KEY_decoded_from_explicit_params()\fR +.Sp +There is no replacement. +.IP \(bu 4 +\&\fBEC_KEY_generate_key()\fR +.Sp +See "Deprecated low\-level key generation functions". +.IP \(bu 4 +\&\fBEC_KEY_get0_group()\fR, \fBEC_KEY_get0_private_key()\fR, \fBEC_KEY_get0_public_key()\fR, +\&\fBEC_KEY_get_conv_form()\fR, \fBEC_KEY_get_enc_flags()\fR +.Sp +See "Deprecated low\-level key parameter getters". +.IP \(bu 4 +\&\fBEC_KEY_get0_engine()\fR, \fBEC_KEY_get_default_method()\fR, \fBEC_KEY_get_method()\fR, +\&\fBEC_KEY_new_method()\fR, \fBEC_KEY_get_ex_data()\fR, \fBEC_KEY_OpenSSL()\fR, +\&\fBEC_KEY_set_ex_data()\fR, \fBEC_KEY_set_default_method()\fR, EC_KEY_METHOD_*(), +\&\fBEC_KEY_set_method()\fR +.Sp +See "Providers are a replacement for engines and low\-level method overrides" +.IP \(bu 4 +\&\fBEC_METHOD_get_field_type()\fR +.Sp +Use \fBEC_GROUP_get_field_type\fR\|(3) instead. +See "Providers are a replacement for engines and low\-level method overrides" +.IP \(bu 4 +\&\fBEC_KEY_key2buf()\fR, \fBEC_KEY_oct2key()\fR, \fBEC_KEY_oct2priv()\fR, \fBEC_KEY_priv2buf()\fR, +\&\fBEC_KEY_priv2oct()\fR +.Sp +There are no replacements for these. +.IP \(bu 4 +\&\fBEC_KEY_new()\fR, \fBEC_KEY_new_by_curve_name()\fR, \fBEC_KEY_free()\fR, \fBEC_KEY_up_ref()\fR +.Sp +See "Deprecated low\-level object creation" +.IP \(bu 4 +\&\fBEC_KEY_print()\fR, \fBEC_KEY_print_fp()\fR +.Sp +See "Deprecated low\-level key printing functions" +.IP \(bu 4 +\&\fBEC_KEY_set_asn1_flag()\fR, \fBEC_KEY_set_conv_form()\fR, \fBEC_KEY_set_enc_flags()\fR +.Sp +See "Deprecated low\-level key parameter setters". +.IP \(bu 4 +\&\fBEC_KEY_set_group()\fR, \fBEC_KEY_set_private_key()\fR, \fBEC_KEY_set_public_key()\fR, +\&\fBEC_KEY_set_public_key_affine_coordinates()\fR +.Sp +See "Deprecated low\-level key parameter setters". +.IP \(bu 4 +\&\fBECParameters_print()\fR, \fBECParameters_print_fp()\fR, \fBECPKParameters_print()\fR, +\&\fBECPKParameters_print_fp()\fR +.Sp +See "Deprecated low\-level key printing functions" +.IP \(bu 4 +\&\fBEC_POINT_bn2point()\fR, \fBEC_POINT_point2bn()\fR +.Sp +These functions were not particularly useful, since EC point serialization +formats are not individual big\-endian integers. +.IP \(bu 4 +\&\fBEC_POINT_get_affine_coordinates_GF2m()\fR, \fBEC_POINT_get_affine_coordinates_GFp()\fR, +\&\fBEC_POINT_set_affine_coordinates_GF2m()\fR, \fBEC_POINT_set_affine_coordinates_GFp()\fR +.Sp +Applications should use \fBEC_POINT_get_affine_coordinates\fR\|(3) and +\&\fBEC_POINT_set_affine_coordinates\fR\|(3) instead. +.IP \(bu 4 +\&\fBEC_POINT_get_Jprojective_coordinates_GFp()\fR, \fBEC_POINT_set_Jprojective_coordinates_GFp()\fR +.Sp +These functions are not widely used. Applications should instead use the +\&\fBEC_POINT_set_affine_coordinates\fR\|(3) and \fBEC_POINT_get_affine_coordinates\fR\|(3) +functions. +.IP \(bu 4 +\&\fBEC_POINT_make_affine()\fR, \fBEC_POINTs_make_affine()\fR +.Sp +There is no replacement. These functions were not widely used, and OpenSSL +automatically performs this conversion when needed. +.IP \(bu 4 +\&\fBEC_POINT_set_compressed_coordinates_GF2m()\fR, \fBEC_POINT_set_compressed_coordinates_GFp()\fR +.Sp +Applications should use \fBEC_POINT_set_compressed_coordinates\fR\|(3) instead. +.IP \(bu 4 +\&\fBEC_POINTs_mul()\fR +.Sp +This function is not widely used. Applications should instead use the +\&\fBEC_POINT_mul\fR\|(3) function. +.IP \(bu 4 +\&\fBENGINE_*()\fR +.Sp +All engine functions are deprecated. An engine should be rewritten as a provider. +See "Providers are a replacement for engines and low\-level method overrides". +.IP \(bu 4 +\&\fBERR_load_*()\fR, \fBERR_func_error_string()\fR, \fBERR_get_error_line()\fR, +\&\fBERR_get_error_line_data()\fR, \fBERR_get_state()\fR +.Sp +OpenSSL now loads error strings automatically so these functions are not needed. +.IP \(bu 4 +\&\fBERR_peek_error_line_data()\fR, \fBERR_peek_last_error_line_data()\fR +.Sp +The new functions are \fBERR_peek_error_func\fR\|(3), \fBERR_peek_last_error_func\fR\|(3), +\&\fBERR_peek_error_data\fR\|(3), \fBERR_peek_last_error_data\fR\|(3), \fBERR_get_error_all\fR\|(3), +\&\fBERR_peek_error_all\fR\|(3) and \fBERR_peek_last_error_all\fR\|(3). +Applications should use \fBERR_get_error_all\fR\|(3), or pick information +with ERR_peek functions and finish off with getting the error code by using +\&\fBERR_get_error\fR\|(3). +.IP \(bu 4 +\&\fBEVP_CIPHER_CTX_iv()\fR, \fBEVP_CIPHER_CTX_iv_noconst()\fR, \fBEVP_CIPHER_CTX_original_iv()\fR +.Sp +Applications should instead use \fBEVP_CIPHER_CTX_get_updated_iv\fR\|(3), +\&\fBEVP_CIPHER_CTX_get_updated_iv\fR\|(3) and \fBEVP_CIPHER_CTX_get_original_iv\fR\|(3) +respectively. +See \fBEVP_CIPHER_CTX_get_original_iv\fR\|(3) for further information. +.IP \(bu 4 +\&\fBEVP_CIPHER_meth_*()\fR, \fBEVP_MD_CTX_set_update_fn()\fR, \fBEVP_MD_CTX_update_fn()\fR, +\&\fBEVP_MD_meth_*()\fR +.Sp +See "Providers are a replacement for engines and low\-level method overrides". +.IP \(bu 4 +\&\fBEVP_PKEY_CTRL_PKCS7_ENCRYPT()\fR, \fBEVP_PKEY_CTRL_PKCS7_DECRYPT()\fR, +\&\fBEVP_PKEY_CTRL_PKCS7_SIGN()\fR, \fBEVP_PKEY_CTRL_CMS_ENCRYPT()\fR, +\&\fBEVP_PKEY_CTRL_CMS_DECRYPT()\fR, and \fBEVP_PKEY_CTRL_CMS_SIGN()\fR +.Sp +These control operations are not invoked by the OpenSSL library anymore and +are replaced by direct checks of the key operation against the key type +when the operation is initialized. +.IP \(bu 4 +\&\fBEVP_PKEY_CTX_get0_dh_kdf_ukm()\fR, \fBEVP_PKEY_CTX_get0_ecdh_kdf_ukm()\fR +.Sp +See the "kdf\-ukm" item in "DH key exchange parameters" in \fBEVP_KEYEXCH\-DH\fR\|(7) and +"ECDH Key Exchange parameters" in \fBEVP_KEYEXCH\-ECDH\fR\|(7). +These functions are obsolete and should not be required. +.IP \(bu 4 +\&\fBEVP_PKEY_CTX_set_rsa_keygen_pubexp()\fR +.Sp +Applications should use \fBEVP_PKEY_CTX_set1_rsa_keygen_pubexp\fR\|(3) instead. +.IP \(bu 4 +\&\fBEVP_PKEY_cmp()\fR, \fBEVP_PKEY_cmp_parameters()\fR +.Sp +Applications should use \fBEVP_PKEY_eq\fR\|(3) and \fBEVP_PKEY_parameters_eq\fR\|(3) instead. +See \fBEVP_PKEY_copy_parameters\fR\|(3) for further details. +.IP \(bu 4 +\&\fBEVP_PKEY_encrypt_old()\fR, \fBEVP_PKEY_decrypt_old()\fR, +.Sp +Applications should use \fBEVP_PKEY_encrypt_init\fR\|(3) and \fBEVP_PKEY_encrypt\fR\|(3) or +\&\fBEVP_PKEY_decrypt_init\fR\|(3) and \fBEVP_PKEY_decrypt\fR\|(3) instead. +.IP \(bu 4 +\&\fBEVP_PKEY_get0()\fR +.Sp +This function returns NULL if the key comes from a provider. +.IP \(bu 4 +\&\fBEVP_PKEY_get0_DH()\fR, \fBEVP_PKEY_get0_DSA()\fR, \fBEVP_PKEY_get0_EC_KEY()\fR, \fBEVP_PKEY_get0_RSA()\fR, +\&\fBEVP_PKEY_get1_DH()\fR, \fBEVP_PKEY_get1_DSA()\fR, EVP_PKEY_get1_EC_KEY and \fBEVP_PKEY_get1_RSA()\fR, +\&\fBEVP_PKEY_get0_hmac()\fR, \fBEVP_PKEY_get0_poly1305()\fR, \fBEVP_PKEY_get0_siphash()\fR +.Sp +See "Functions that return an internal key should be treated as read only". +.IP \(bu 4 +\&\fBEVP_PKEY_meth_*()\fR +.Sp +See "Providers are a replacement for engines and low\-level method overrides". +.IP \(bu 4 +\&\fBEVP_PKEY_new_CMAC_key()\fR +.Sp +See "Deprecated low\-level MAC functions". +.IP \(bu 4 +\&\fBEVP_PKEY_assign()\fR, \fBEVP_PKEY_set1_DH()\fR, \fBEVP_PKEY_set1_DSA()\fR, +\&\fBEVP_PKEY_set1_EC_KEY()\fR, \fBEVP_PKEY_set1_RSA()\fR +.Sp +See "Deprecated low\-level key object getters and setters" +.IP \(bu 4 +\&\fBEVP_PKEY_set1_tls_encodedpoint()\fR \fBEVP_PKEY_get1_tls_encodedpoint()\fR +.Sp +These functions were previously used by libssl to set or get an encoded public +key into/from an EVP_PKEY object. With OpenSSL 3.0 these are replaced by the more +generic functions \fBEVP_PKEY_set1_encoded_public_key\fR\|(3) and +\&\fBEVP_PKEY_get1_encoded_public_key\fR\|(3). +The old versions have been converted to deprecated macros that just call the +new functions. +.IP \(bu 4 +\&\fBEVP_PKEY_set1_engine()\fR, \fBEVP_PKEY_get0_engine()\fR +.Sp +See "Providers are a replacement for engines and low\-level method overrides". +.IP \(bu 4 +\&\fBEVP_PKEY_set_alias_type()\fR +.Sp +This function has been removed. There is no replacement. +See "\fBEVP_PKEY_set_alias_type()\fR method has been removed" +.IP \(bu 4 +\&\fBHMAC_Init_ex()\fR, \fBHMAC_Update()\fR, \fBHMAC_Final()\fR, \fBHMAC_size()\fR +.Sp +See "Deprecated low\-level MAC functions". +.IP \(bu 4 +\&\fBHMAC_CTX_new()\fR, \fBHMAC_CTX_free()\fR, \fBHMAC_CTX_copy()\fR, \fBHMAC_CTX_reset()\fR, +\&\fBHMAC_CTX_set_flags()\fR, \fBHMAC_CTX_get_md()\fR +.Sp +See "Deprecated low\-level MAC functions". +.IP \(bu 4 +\&\fBi2d_DHparams()\fR, \fBi2d_DHxparams()\fR +.Sp +See "Deprecated low\-level key reading and writing functions" +and "Migration" in \fBd2i_RSAPrivateKey\fR\|(3) +.IP \(bu 4 +\&\fBi2d_DSAparams()\fR, \fBi2d_DSAPrivateKey()\fR, \fBi2d_DSAPrivateKey_bio()\fR, +\&\fBi2d_DSAPrivateKey_fp()\fR, \fBi2d_DSA_PUBKEY()\fR, \fBi2d_DSA_PUBKEY_bio()\fR, +\&\fBi2d_DSA_PUBKEY_fp()\fR, \fBi2d_DSAPublicKey()\fR +.Sp +See "Deprecated low\-level key reading and writing functions" +and "Migration" in \fBd2i_RSAPrivateKey\fR\|(3) +.IP \(bu 4 +\&\fBi2d_ECParameters()\fR, \fBi2d_ECPrivateKey()\fR, \fBi2d_ECPrivateKey_bio()\fR, +\&\fBi2d_ECPrivateKey_fp()\fR, \fBi2d_EC_PUBKEY()\fR, \fBi2d_EC_PUBKEY_bio()\fR, +\&\fBi2d_EC_PUBKEY_fp()\fR +.Sp +See "Deprecated low\-level key reading and writing functions" +and "Migration" in \fBd2i_RSAPrivateKey\fR\|(3) +.IP \(bu 4 +\&\fBi2o_ECPublicKey()\fR +.Sp +Use \fBEVP_PKEY_get1_encoded_public_key\fR\|(3). +See "Deprecated low\-level key parameter getters" +.IP \(bu 4 +\&\fBi2d_RSAPrivateKey()\fR, \fBi2d_RSAPrivateKey_bio()\fR, \fBi2d_RSAPrivateKey_fp()\fR, +\&\fBi2d_RSA_PUBKEY()\fR, \fBi2d_RSA_PUBKEY_bio()\fR, \fBi2d_RSA_PUBKEY_fp()\fR, +\&\fBi2d_RSAPublicKey()\fR, \fBi2d_RSAPublicKey_bio()\fR, \fBi2d_RSAPublicKey_fp()\fR +.Sp +See "Deprecated low\-level key reading and writing functions" +and "Migration" in \fBd2i_RSAPrivateKey\fR\|(3) +.IP \(bu 4 +\&\fBIDEA_encrypt()\fR, \fBIDEA_set_decrypt_key()\fR, \fBIDEA_set_encrypt_key()\fR, +\&\fBIDEA_cbc_encrypt()\fR, \fBIDEA_cfb64_encrypt()\fR, \fBIDEA_ecb_encrypt()\fR, +\&\fBIDEA_ofb64_encrypt()\fR +.Sp +See "Deprecated low\-level encryption functions". +IDEA has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBIDEA_options()\fR +.Sp +There is no replacement. This function returned a constant string. +.IP \(bu 4 +\&\fBMD2()\fR, \fBMD2_Init()\fR, \fBMD2_Update()\fR, \fBMD2_Final()\fR +.Sp +See "Deprecated low\-level encryption functions". +MD2 has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBMD2_options()\fR +.Sp +There is no replacement. This function returned a constant string. +.IP \(bu 4 +\&\fBMD4()\fR, \fBMD4_Init()\fR, \fBMD4_Update()\fR, \fBMD4_Final()\fR, \fBMD4_Transform()\fR +.Sp +See "Deprecated low\-level encryption functions". +MD4 has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBMDC2()\fR, \fBMDC2_Init()\fR, \fBMDC2_Update()\fR, \fBMDC2_Final()\fR +.Sp +See "Deprecated low\-level encryption functions". +MDC2 has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBMD5()\fR, \fBMD5_Init()\fR, \fBMD5_Update()\fR, \fBMD5_Final()\fR, \fBMD5_Transform()\fR +.Sp +See "Deprecated low\-level encryption functions". +.IP \(bu 4 +\&\fBNCONF_WIN32()\fR +.Sp +This undocumented function has no replacement. +See "HISTORY" in \fBconfig\fR\|(5) for more details. +.IP \(bu 4 +\&\fBOCSP_parse_url()\fR +.Sp +Use \fBOSSL_HTTP_parse_url\fR\|(3) instead. +.IP \(bu 4 +\&\fBOCSP_REQ_CTX\fR type and \fBOCSP_REQ_CTX_*()\fR functions +.Sp +These methods were used to collect all necessary data to form a HTTP request, +and to perform the HTTP transfer with that request. With OpenSSL 3.0, the +type is \fBOSSL_HTTP_REQ_CTX\fR, and the deprecated functions are replaced +with \fBOSSL_HTTP_REQ_CTX_*()\fR. See \fBOSSL_HTTP_REQ_CTX\fR\|(3) for additional +details. +.IP \(bu 4 +\&\fBOPENSSL_fork_child()\fR, \fBOPENSSL_fork_parent()\fR, \fBOPENSSL_fork_prepare()\fR +.Sp +There is no replacement for these functions. These pthread fork support methods +were unused by OpenSSL. +.IP \(bu 4 +\&\fBOSSL_STORE_ctrl()\fR, \fBOSSL_STORE_do_all_loaders()\fR, \fBOSSL_STORE_LOADER_get0_engine()\fR, +\&\fBOSSL_STORE_LOADER_get0_scheme()\fR, \fBOSSL_STORE_LOADER_new()\fR, +\&\fBOSSL_STORE_LOADER_set_attach()\fR, \fBOSSL_STORE_LOADER_set_close()\fR, +\&\fBOSSL_STORE_LOADER_set_ctrl()\fR, \fBOSSL_STORE_LOADER_set_eof()\fR, +\&\fBOSSL_STORE_LOADER_set_error()\fR, \fBOSSL_STORE_LOADER_set_expect()\fR, +\&\fBOSSL_STORE_LOADER_set_find()\fR, \fBOSSL_STORE_LOADER_set_load()\fR, +\&\fBOSSL_STORE_LOADER_set_open()\fR, \fBOSSL_STORE_LOADER_set_open_ex()\fR, +\&\fBOSSL_STORE_register_loader()\fR, \fBOSSL_STORE_unregister_loader()\fR, +\&\fBOSSL_STORE_vctrl()\fR +.Sp +These functions helped applications and engines create loaders for +schemes they supported. These are all deprecated and discouraged in favour of +provider implementations, see \fBprovider\-storemgmt\fR\|(7). +.IP \(bu 4 +\&\fBPEM_read_DHparams()\fR, \fBPEM_read_bio_DHparams()\fR, +\&\fBPEM_read_DSAparams()\fR, \fBPEM_read_bio_DSAparams()\fR, +\&\fBPEM_read_DSAPrivateKey()\fR, \fBPEM_read_DSA_PUBKEY()\fR, +PEM_read_bio_DSAPrivateKey and \fBPEM_read_bio_DSA_PUBKEY()\fR, +\&\fBPEM_read_ECPKParameters()\fR, \fBPEM_read_ECPrivateKey()\fR, \fBPEM_read_EC_PUBKEY()\fR, +\&\fBPEM_read_bio_ECPKParameters()\fR, \fBPEM_read_bio_ECPrivateKey()\fR, \fBPEM_read_bio_EC_PUBKEY()\fR, +\&\fBPEM_read_RSAPrivateKey()\fR, \fBPEM_read_RSA_PUBKEY()\fR, \fBPEM_read_RSAPublicKey()\fR, +\&\fBPEM_read_bio_RSAPrivateKey()\fR, \fBPEM_read_bio_RSA_PUBKEY()\fR, \fBPEM_read_bio_RSAPublicKey()\fR, +\&\fBPEM_write_bio_DHparams()\fR, \fBPEM_write_bio_DHxparams()\fR, \fBPEM_write_DHparams()\fR, \fBPEM_write_DHxparams()\fR, +\&\fBPEM_write_DSAparams()\fR, \fBPEM_write_DSAPrivateKey()\fR, \fBPEM_write_DSA_PUBKEY()\fR, +\&\fBPEM_write_bio_DSAparams()\fR, \fBPEM_write_bio_DSAPrivateKey()\fR, \fBPEM_write_bio_DSA_PUBKEY()\fR, +\&\fBPEM_write_ECPKParameters()\fR, \fBPEM_write_ECPrivateKey()\fR, \fBPEM_write_EC_PUBKEY()\fR, +\&\fBPEM_write_bio_ECPKParameters()\fR, \fBPEM_write_bio_ECPrivateKey()\fR, \fBPEM_write_bio_EC_PUBKEY()\fR, +\&\fBPEM_write_RSAPrivateKey()\fR, \fBPEM_write_RSA_PUBKEY()\fR, \fBPEM_write_RSAPublicKey()\fR, +\&\fBPEM_write_bio_RSAPrivateKey()\fR, \fBPEM_write_bio_RSA_PUBKEY()\fR, +\&\fBPEM_write_bio_RSAPublicKey()\fR, +.Sp +See "Deprecated low\-level key reading and writing functions" +.IP \(bu 4 +\&\fBPKCS1_MGF1()\fR +.Sp +See "Deprecated low\-level encryption functions". +.IP \(bu 4 +\&\fBRAND_get_rand_method()\fR, \fBRAND_set_rand_method()\fR, \fBRAND_OpenSSL()\fR, +\&\fBRAND_set_rand_engine()\fR +.Sp +Applications should instead use \fBRAND_set_DRBG_type\fR\|(3), +\&\fBEVP_RAND\fR\|(3) and \fBEVP_RAND\fR\|(7). +See \fBRAND_set_rand_method\fR\|(3) for more details. +.IP \(bu 4 +\&\fBRC2_encrypt()\fR, \fBRC2_decrypt()\fR, \fBRC2_set_key()\fR, \fBRC2_cbc_encrypt()\fR, \fBRC2_cfb64_encrypt()\fR, +\&\fBRC2_ecb_encrypt()\fR, \fBRC2_ofb64_encrypt()\fR, +\&\fBRC4()\fR, \fBRC4_set_key()\fR, \fBRC4_options()\fR, +\&\fBRC5_32_encrypt()\fR, \fBRC5_32_set_key()\fR, \fBRC5_32_decrypt()\fR, \fBRC5_32_cbc_encrypt()\fR, +\&\fBRC5_32_cfb64_encrypt()\fR, \fBRC5_32_ecb_encrypt()\fR, \fBRC5_32_ofb64_encrypt()\fR +.Sp +See "Deprecated low\-level encryption functions". +The Algorithms "RC2", "RC4" and "RC5" have been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBRIPEMD160()\fR, \fBRIPEMD160_Init()\fR, \fBRIPEMD160_Update()\fR, \fBRIPEMD160_Final()\fR, +\&\fBRIPEMD160_Transform()\fR +.Sp +See "Deprecated low\-level digest functions". +The RIPE algorithm has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBRSA_bits()\fR, \fBRSA_security_bits()\fR, \fBRSA_size()\fR +.Sp +Use \fBEVP_PKEY_get_bits\fR\|(3), \fBEVP_PKEY_get_security_bits\fR\|(3) and +\&\fBEVP_PKEY_get_size\fR\|(3). +.IP \(bu 4 +\&\fBRSA_check_key()\fR, \fBRSA_check_key_ex()\fR +.Sp +See "Deprecated low\-level validation functions" +.IP \(bu 4 +\&\fBRSA_clear_flags()\fR, \fBRSA_flags()\fR, \fBRSA_set_flags()\fR, \fBRSA_test_flags()\fR, +\&\fBRSA_setup_blinding()\fR, \fBRSA_blinding_off()\fR, \fBRSA_blinding_on()\fR +.Sp +All of these RSA flags have been deprecated without replacement: +.Sp +\&\fBRSA_FLAG_BLINDING\fR, \fBRSA_FLAG_CACHE_PRIVATE\fR, \fBRSA_FLAG_CACHE_PUBLIC\fR, +\&\fBRSA_FLAG_EXT_PKEY\fR, \fBRSA_FLAG_NO_BLINDING\fR, \fBRSA_FLAG_THREAD_SAFE\fR +\&\fBRSA_METHOD_FLAG_NO_CHECK\fR +.IP \(bu 4 +\&\fBRSA_generate_key_ex()\fR, \fBRSA_generate_multi_prime_key()\fR +.Sp +See "Deprecated low\-level key generation functions". +.IP \(bu 4 +\&\fBRSA_get0_engine()\fR +.Sp +See "Providers are a replacement for engines and low\-level method overrides" +.IP \(bu 4 +\&\fBRSA_get0_crt_params()\fR, \fBRSA_get0_d()\fR, \fBRSA_get0_dmp1()\fR, \fBRSA_get0_dmq1()\fR, +\&\fBRSA_get0_e()\fR, \fBRSA_get0_factors()\fR, \fBRSA_get0_iqmp()\fR, \fBRSA_get0_key()\fR, +\&\fBRSA_get0_multi_prime_crt_params()\fR, \fBRSA_get0_multi_prime_factors()\fR, \fBRSA_get0_n()\fR, +\&\fBRSA_get0_p()\fR, \fBRSA_get0_pss_params()\fR, \fBRSA_get0_q()\fR, +\&\fBRSA_get_multi_prime_extra_count()\fR +.Sp +See "Deprecated low\-level key parameter getters" +.IP \(bu 4 +\&\fBRSA_new()\fR, \fBRSA_free()\fR, \fBRSA_up_ref()\fR +.Sp +See "Deprecated low\-level object creation". +.IP \(bu 4 +\&\fBRSA_get_default_method()\fR, RSA_get_ex_data and \fBRSA_get_method()\fR +.Sp +See "Providers are a replacement for engines and low\-level method overrides". +.IP \(bu 4 +\&\fBRSA_get_version()\fR +.Sp +There is no replacement. +.IP \(bu 4 +\&\fBRSA_meth_*()\fR, \fBRSA_new_method()\fR, RSA_null_method and \fBRSA_PKCS1_OpenSSL()\fR +.Sp +See "Providers are a replacement for engines and low\-level method overrides". +.IP \(bu 4 +\&\fBRSA_padding_add_*()\fR, \fBRSA_padding_check_*()\fR +.Sp +See "Deprecated low\-level signing functions" and +"Deprecated low\-level encryption functions". +.IP \(bu 4 +\&\fBRSA_print()\fR, \fBRSA_print_fp()\fR +.Sp +See "Deprecated low\-level key printing functions" +.IP \(bu 4 +\&\fBRSA_public_encrypt()\fR, \fBRSA_private_decrypt()\fR +.Sp +See "Deprecated low\-level encryption functions" +.IP \(bu 4 +\&\fBRSA_private_encrypt()\fR, \fBRSA_public_decrypt()\fR +.Sp +This is equivalent to doing sign and verify recover operations (with a padding +mode of none). See "Deprecated low\-level signing functions". +.IP \(bu 4 +\&\fBRSAPrivateKey_dup()\fR, \fBRSAPublicKey_dup()\fR +.Sp +There is no direct replacement. Applications may use \fBEVP_PKEY_dup\fR\|(3). +.IP \(bu 4 +\&\fBRSAPublicKey_it()\fR, \fBRSAPrivateKey_it()\fR +.Sp +See "Deprecated low\-level key reading and writing functions" +.IP \(bu 4 +\&\fBRSA_set0_crt_params()\fR, \fBRSA_set0_factors()\fR, \fBRSA_set0_key()\fR, +\&\fBRSA_set0_multi_prime_params()\fR +.Sp +See "Deprecated low\-level key parameter setters". +.IP \(bu 4 +\&\fBRSA_set_default_method()\fR, \fBRSA_set_method()\fR, \fBRSA_set_ex_data()\fR +.Sp +See "Providers are a replacement for engines and low\-level method overrides" +.IP \(bu 4 +\&\fBRSA_sign()\fR, \fBRSA_sign_ASN1_OCTET_STRING()\fR, \fBRSA_verify()\fR, +\&\fBRSA_verify_ASN1_OCTET_STRING()\fR, \fBRSA_verify_PKCS1_PSS()\fR, +\&\fBRSA_verify_PKCS1_PSS_mgf1()\fR +.Sp +See "Deprecated low\-level signing functions". +.IP \(bu 4 +\&\fBRSA_X931_derive_ex()\fR, \fBRSA_X931_generate_key_ex()\fR, \fBRSA_X931_hash_id()\fR +.Sp +There are no replacements for these functions. +X931 padding can be set using "Signature Parameters" in \fBEVP_SIGNATURE\-RSA\fR\|(7). +See \fBOSSL_SIGNATURE_PARAM_PAD_MODE\fR. +.IP \(bu 4 +\&\fBSEED_encrypt()\fR, \fBSEED_decrypt()\fR, \fBSEED_set_key()\fR, \fBSEED_cbc_encrypt()\fR, +\&\fBSEED_cfb128_encrypt()\fR, \fBSEED_ecb_encrypt()\fR, \fBSEED_ofb128_encrypt()\fR +.Sp +See "Deprecated low\-level encryption functions". +The SEED algorithm has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBSHA1_Init()\fR, \fBSHA1_Update()\fR, \fBSHA1_Final()\fR, \fBSHA1_Transform()\fR, +\&\fBSHA224_Init()\fR, \fBSHA224_Update()\fR, \fBSHA224_Final()\fR, +\&\fBSHA256_Init()\fR, \fBSHA256_Update()\fR, \fBSHA256_Final()\fR, \fBSHA256_Transform()\fR, +\&\fBSHA384_Init()\fR, \fBSHA384_Update()\fR, \fBSHA384_Final()\fR, +\&\fBSHA512_Init()\fR, \fBSHA512_Update()\fR, \fBSHA512_Final()\fR, \fBSHA512_Transform()\fR +.Sp +See "Deprecated low\-level digest functions". +.IP \(bu 4 +\&\fBSRP_Calc_A()\fR, \fBSRP_Calc_B()\fR, \fBSRP_Calc_client_key()\fR, \fBSRP_Calc_server_key()\fR, +\&\fBSRP_Calc_u()\fR, \fBSRP_Calc_x()\fR, \fBSRP_check_known_gN_param()\fR, \fBSRP_create_verifier()\fR, +\&\fBSRP_create_verifier_BN()\fR, \fBSRP_get_default_gN()\fR, \fBSRP_user_pwd_free()\fR, \fBSRP_user_pwd_new()\fR, +\&\fBSRP_user_pwd_set0_sv()\fR, \fBSRP_user_pwd_set1_ids()\fR, \fBSRP_user_pwd_set_gN()\fR, +\&\fBSRP_VBASE_add0_user()\fR, \fBSRP_VBASE_free()\fR, \fBSRP_VBASE_get1_by_user()\fR, \fBSRP_VBASE_init()\fR, +\&\fBSRP_VBASE_new()\fR, \fBSRP_Verify_A_mod_N()\fR, \fBSRP_Verify_B_mod_N()\fR +.Sp +There are no replacements for the SRP functions. +.IP \(bu 4 +\&\fBSSL_CTX_set_tmp_dh_callback()\fR, \fBSSL_set_tmp_dh_callback()\fR, +\&\fBSSL_CTX_set_tmp_dh()\fR, \fBSSL_set_tmp_dh()\fR +.Sp +These are used to set the Diffie\-Hellman (DH) parameters that are to be used by +servers requiring ephemeral DH keys. Instead applications should consider using +the built\-in DH parameters that are available by calling \fBSSL_CTX_set_dh_auto\fR\|(3) +or \fBSSL_set_dh_auto\fR\|(3). If custom parameters are necessary then applications can +use the alternative functions \fBSSL_CTX_set0_tmp_dh_pkey\fR\|(3) and +\&\fBSSL_set0_tmp_dh_pkey\fR\|(3). There is no direct replacement for the "callback" +functions. The callback was originally useful in order to have different +parameters for export and non\-export ciphersuites. Export ciphersuites are no +longer supported by OpenSSL. Use of the callback functions should be replaced +by one of the other methods described above. +.IP \(bu 4 +\&\fBSSL_CTX_set_tlsext_ticket_key_cb()\fR +.Sp +Use the new \fBSSL_CTX_set_tlsext_ticket_key_evp_cb\fR\|(3) function instead. +.IP \(bu 4 +\&\fBWHIRLPOOL()\fR, \fBWHIRLPOOL_Init()\fR, \fBWHIRLPOOL_Update()\fR, \fBWHIRLPOOL_Final()\fR, +\&\fBWHIRLPOOL_BitUpdate()\fR +.Sp +See "Deprecated low\-level digest functions". +The Whirlpool algorithm has been moved to the Legacy Provider. +.IP \(bu 4 +\&\fBX509_certificate_type()\fR +.Sp +This was an undocumented function. Applications can use \fBX509_get0_pubkey\fR\|(3) +and \fBX509_get0_signature\fR\|(3) instead. +.IP \(bu 4 +\&\fBX509_http_nbio()\fR, \fBX509_CRL_http_nbio()\fR +.Sp +Use \fBX509_load_http\fR\|(3) and \fBX509_CRL_load_http\fR\|(3) instead. +.PP +\fINID handling for provided keys and algorithms\fR +.IX Subsection "NID handling for provided keys and algorithms" +.PP +The following functions for NID (numeric id) handling have changed semantics. +.IP \(bu 4 +\&\fBEVP_PKEY_id()\fR, \fBEVP_PKEY_get_id()\fR +.Sp +This function was previously used to reliably return the NID of +an EVP_PKEY object, e.g., to look up the name of the algorithm of +such EVP_PKEY by calling \fBOBJ_nid2sn\fR\|(3). With the introduction +of \fBprovider\fR\|(7)s \fBEVP_PKEY_id()\fR or its new equivalent +\&\fBEVP_PKEY_get_id\fR\|(3) might now also return the value \-1 +(\fBEVP_PKEY_KEYMGMT\fR) indicating the use of a provider to +implement the EVP_PKEY object. Therefore, the use of +\&\fBEVP_PKEY_get0_type_name\fR\|(3) is recommended for retrieving +the name of the EVP_PKEY algorithm. +.SS "Using the FIPS Module in applications" +.IX Subsection "Using the FIPS Module in applications" +See \fBfips_module\fR\|(7) and \fBOSSL_PROVIDER\-FIPS\fR\|(7) for details. +.SS "OpenSSL command line application changes" +.IX Subsection "OpenSSL command line application changes" +\fINew applications\fR +.IX Subsection "New applications" +.PP +\&\fBopenssl kdf\fR uses the new \fBEVP_KDF\fR\|(3) API. +\&\fBopenssl kdf\fR uses the new \fBEVP_MAC\fR\|(3) API. +.PP +\fIAdded options\fR +.IX Subsection "Added options" +.PP +\&\fB\-provider_path\fR and \fB\-provider\fR are available to all apps and can be used +multiple times to load any providers, such as the \*(Aqlegacy\*(Aq provider or third +party providers. If used then the \*(Aqdefault\*(Aq provider would also need to be +specified if required. The \fB\-provider_path\fR must be specified before the +\&\fB\-provider\fR option. +.PP +The \fBlist\fR app has many new options. See \fBopenssl\-list\fR\|(1) for more +information. +.PP +\&\fB\-crl_lastupdate\fR and \fB\-crl_nextupdate\fR used by \fBopenssl ca\fR allows +explicit setting of fields in the generated CRL. +.PP +\fIRemoved options\fR +.IX Subsection "Removed options" +.PP +Interactive mode is not longer available. +.PP +The \fB\-crypt\fR option used by \fBopenssl passwd\fR. +The \fB\-c\fR option used by \fBopenssl x509\fR, \fBopenssl dhparam\fR, +\&\fBopenssl dsaparam\fR, and \fBopenssl ecparam\fR. +.PP +\fIOther Changes\fR +.IX Subsection "Other Changes" +.PP +The output of Command line applications may have minor changes. +These are primarily changes in capitalisation and white space. However, in some +cases, there are additional differences. +For example, the DH parameters output from \fBopenssl dhparam\fR now lists \*(AqP\*(Aq, +\&\*(AqQ\*(Aq, \*(AqG\*(Aq and \*(Aqpcounter\*(Aq instead of \*(Aqprime\*(Aq, \*(Aqgenerator\*(Aq, \*(Aqsubgroup order\*(Aq and +\&\*(Aqcounter\*(Aq respectively. +.PP +The \fBopenssl\fR commands that read keys, certificates, and CRLs now +automatically detect the PEM or DER format of the input files so it is not +necessary to explicitly specify the input format anymore. However if the +input format option is used the specified format will be required. +.PP +\&\fBopenssl speed\fR no longer uses low\-level API calls. +This implies some of the performance numbers might not be comparable with the +previous releases due to higher overhead. This applies particularly to +measuring performance on smaller data chunks. +.PP +b, \fBopenssl dsa\fR, \fBopenssl gendsa\fR, \fBopenssl dsaparam\fR, +\&\fBopenssl genrsa\fR and \fBopenssl rsa\fR have been modified to use PKEY APIs. +\&\fBopenssl genrsa\fR and \fBopenssl rsa\fR now write PKCS #8 keys by default. +.PP +\fIDefault settings\fR +.IX Subsection "Default settings" +.PP +"SHA256" is now the default digest for TS query used by \fBopenssl ts\fR. +.PP +\fIDeprecated apps\fR +.IX Subsection "Deprecated apps" +.PP +\&\fBopenssl rsautl\fR is deprecated, use \fBopenssl pkeyutl\fR instead. +\&\fBopenssl dhparam\fR, \fBopenssl dsa\fR, \fBopenssl gendsa\fR, \fBopenssl dsaparam\fR, +\&\fBopenssl genrsa\fR, \fBopenssl rsa\fR, \fBopenssl genrsa\fR and \fBopenssl rsa\fR are +now in maintenance mode and no new features will be added to them. +.SS "TLS Changes" +.IX Subsection "TLS Changes" +.IP \(bu 4 +TLS 1.3 FFDHE key exchange support added +.Sp +This uses DH safe prime named groups. +.IP \(bu 4 +Support for fully "pluggable" TLSv1.3 groups. +.Sp +This means that providers may supply their own group implementations (using +either the "key exchange" or the "key encapsulation" methods) which will +automatically be detected and used by libssl. +.IP \(bu 4 +SSL and SSL_CTX options are now 64 bit instead of 32 bit. +.Sp +The signatures of the functions to get and set options on SSL and +SSL_CTX objects changed from "unsigned long" to "uint64_t" type. +.Sp +This may require source code changes. For example it is no longer possible +to use the \fBSSL_OP_\fR macro values in preprocessor \f(CW\*(C`#if\*(C'\fR conditions. +However it is still possible to test whether these macros are defined or not. +.Sp +See \fBSSL_CTX_get_options\fR\|(3), \fBSSL_CTX_set_options\fR\|(3), +\&\fBSSL_get_options\fR\|(3) and \fBSSL_set_options\fR\|(3). +.IP \(bu 4 +\&\fBSSL_set1_host()\fR and \fBSSL_add1_host()\fR Changes +.Sp +These functions now take IP literal addresses as well as actual hostnames. +.IP \(bu 4 +Added SSL option SSL_OP_CLEANSE_PLAINTEXT +.Sp +If the option is set, openssl cleanses (zeroizes) plaintext bytes from +internal buffers after delivering them to the application. Note, +the application is still responsible for cleansing other copies +(e.g.: data received by \fBSSL_read\fR\|(3)). +.IP \(bu 4 +Client\-initiated renegotiation is disabled by default. +.Sp +To allow it, use the \fB\-client_renegotiation\fR option, +the \fBSSL_OP_ALLOW_CLIENT_RENEGOTIATION\fR flag, or the \f(CW\*(C`ClientRenegotiation\*(C'\fR +config parameter as appropriate. +.IP \(bu 4 +Secure renegotiation is now required by default for TLS connections +.Sp +Support for RFC 5746 secure renegotiation is now required by default for +SSL or TLS connections to succeed. Applications that require the ability +to connect to legacy peers will need to explicitly set +SSL_OP_LEGACY_SERVER_CONNECT. Accordingly, SSL_OP_LEGACY_SERVER_CONNECT +is no longer set as part of SSL_OP_ALL. +.IP \(bu 4 +Combining the Configure options no\-ec and no\-dh no longer disables TLSv1.3 +.Sp +Typically if OpenSSL has no EC or DH algorithms then it cannot support +connections with TLSv1.3. However OpenSSL now supports "pluggable" groups +through providers. Therefore third party providers may supply group +implementations even where there are no built\-in ones. Attempting to create +TLS connections in such a build without also disabling TLSv1.3 at run time or +using third party provider groups may result in handshake failures. TLSv1.3 +can be disabled at compile time using the "no\-tls1_3" Configure option. +.IP \(bu 4 +\&\fBSSL_CTX_set_ciphersuites()\fR and \fBSSL_set_ciphersuites()\fR changes. +.Sp +The methods now ignore unknown ciphers. +.IP \(bu 4 +Security callback change. +.Sp +The security callback, which can be customised by application code, supports +the security operation SSL_SECOP_TMP_DH. This is defined to take an EVP_PKEY +in the "other" parameter. In most places this is what is passed. All these +places occur server side. However there was one client side call of this +security operation and it passed a DH object instead. This is incorrect +according to the definition of SSL_SECOP_TMP_DH, and is inconsistent with all +of the other locations. Therefore this client side call has been changed to +pass an EVP_PKEY instead. +.IP \(bu 4 +New SSL option SSL_OP_IGNORE_UNEXPECTED_EOF +.Sp +The SSL option SSL_OP_IGNORE_UNEXPECTED_EOF is introduced. If that option +is set, an unexpected EOF is ignored, it pretends a close notify was received +instead and so the returned error becomes SSL_ERROR_ZERO_RETURN. +.IP \(bu 4 +The security strength of SHA1 and MD5 based signatures in TLS has been reduced. +.Sp +This results in SSL 3, TLS 1.0, TLS 1.1 and DTLS 1.0 no longer +working at the default security level of 1 and instead requires security +level 0. The security level can be changed either using the cipher string +with \f(CW@SECLEVEL\fR, or calling \fBSSL_CTX_set_security_level\fR\|(3). This also means +that where the signature algorithms extension is missing from a ClientHello +then the handshake will fail in TLS 1.2 at security level 1. This is because, +although this extension is optional, failing to provide one means that +OpenSSL will fallback to a default set of signature algorithms. This default +set requires the availability of SHA1. +.IP \(bu 4 +X509 certificates signed using SHA1 are no longer allowed at security level 1 and above. +.Sp +In TLS/SSL the default security level is 1. It can be set either using the cipher +string with \f(CW@SECLEVEL\fR, or calling \fBSSL_CTX_set_security_level\fR\|(3). If the +leaf certificate is signed with SHA\-1, a call to \fBSSL_CTX_use_certificate\fR\|(3) +will fail if the security level is not lowered first. +Outside TLS/SSL, the default security level is \-1 (effectively 0). It can +be set using \fBX509_VERIFY_PARAM_set_auth_level\fR\|(3) or using the \fB\-auth_level\fR +options of the commands. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBfips_module\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The migration guide was created for OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-quic-client-block.7 b/static/netbsd/man7/ossl-guide-quic-client-block.7 new file mode 100644 index 00000000..478d5315 --- /dev/null +++ b/static/netbsd/man7/ossl-guide-quic-client-block.7 @@ -0,0 +1,466 @@ +.\" $NetBSD: ossl-guide-quic-client-block.7,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-QUIC-CLIENT-BLOCK 7" +.TH OSSL-GUIDE-QUIC-CLIENT-BLOCK 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-quic\-client\-block +\&\- OpenSSL Guide: Writing a simple blocking QUIC client +.SH "SIMPLE BLOCKING QUIC CLIENT EXAMPLE" +.IX Header "SIMPLE BLOCKING QUIC CLIENT EXAMPLE" +This page will present various source code samples demonstrating how to write +a simple blocking QUIC client application which connects to a server, sends an +HTTP/1.0 request to it, and reads back the response. Note that HTTP/1.0 over +QUIC is non\-standard and will not be supported by real world servers. This is +for demonstration purposes only. +.PP +We assume that you already have OpenSSL installed on your system; that you +already have some fundamental understanding of OpenSSL concepts, TLS and QUIC +(see \fBossl\-guide\-libraries\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7) +and \fBossl\-guide\-quic\-introduction\fR\|(7)); and that you know how to +write and build C code and link it against the libcrypto and libssl libraries +that are provided by OpenSSL. It also assumes that you have a basic +understanding of UDP/IP and sockets. The example code that we build in this +tutorial will amend the blocking TLS client example that is covered in +\&\fBossl\-guide\-tls\-client\-block\fR\|(7). Only the differences between that client and +this one will be discussed so we also assume that you have run through and +understand that tutorial. +.PP +For this tutorial our client will be using a single QUIC stream. A subsequent +tutorial will discuss how to write a multi\-stream client (see +\&\fBossl\-guide\-quic\-multi\-stream\fR\|(7)). +.PP +The complete source code for this example blocking QUIC client is available in +the \f(CW\*(C`demos/guide\*(C'\fR directory of the OpenSSL source distribution in the file +\&\f(CW\*(C`quic\-client\-block.c\*(C'\fR. It is also available online at +. +.SS "Creating the SSL_CTX and SSL objects" +.IX Subsection "Creating the SSL_CTX and SSL objects" +In the TLS tutorial (\fBossl\-guide\-tls\-client\-block\fR\|(7)) we created an \fBSSL_CTX\fR +object for our client and used it to create an \fBSSL\fR object to represent the +TLS connection. A QUIC connection works in exactly the same way. We first create +an \fBSSL_CTX\fR object and then use it to create an \fBSSL\fR object to represent the +QUIC connection. +.PP +As in the TLS example the first step is to create an \fBSSL_CTX\fR object for our +client. This is done in the same way as before except that we use a different +"method". OpenSSL offers two different QUIC client methods, i.e. +\&\fBOSSL_QUIC_client_method\fR\|(3) and \fBOSSL_QUIC_client_thread_method\fR\|(3). +.PP +The first one is the equivalent of \fBTLS_client_method\fR\|(3) but for the QUIC +protocol. The second one is the same, but it will additionally create a +background thread for handling time based events (known as "thread assisted +mode", see \fBossl\-guide\-quic\-introduction\fR\|(7)). For this tutorial we will be +using \fBOSSL_QUIC_client_method\fR\|(3) because we will not be leaving the QUIC +connection idle in our application and so thread assisted mode is not needed. +.PP +.Vb 10 +\& /* +\& * Create an SSL_CTX which we can use to create SSL objects from. We +\& * want an SSL_CTX for creating clients so we use OSSL_QUIC_client_method() +\& * here. +\& */ +\& ctx = SSL_CTX_new(OSSL_QUIC_client_method()); +\& if (ctx == NULL) { +\& printf("Failed to create the SSL_CTX\en"); +\& goto end; +\& } +.Ve +.PP +The other setup steps that we applied to the \fBSSL_CTX\fR for TLS also apply to +QUIC except for restricting the TLS versions that we are willing to accept. The +QUIC protocol implementation in OpenSSL currently only supports TLSv1.3. There +is no need to call \fBSSL_CTX_set_min_proto_version\fR\|(3) or +\&\fBSSL_CTX_set_max_proto_version\fR\|(3) in an OpenSSL QUIC application, and any such +call will be ignored. +.PP +Once the \fBSSL_CTX\fR is created, the \fBSSL\fR object is constructed in exactly the +same way as for the TLS application. +.SS "Creating the socket and BIO" +.IX Subsection "Creating the socket and BIO" +A major difference between TLS and QUIC is the underlying transport protocol. +TLS uses TCP while QUIC uses UDP. The way that the QUIC socket is created in our +example code is much the same as for TLS. We use the \fBBIO_lookup_ex\fR\|(3) and +\&\fBBIO_socket\fR\|(3) helper functions as we did in the previous tutorial except that +we pass \fBSOCK_DGRAM\fR as an argument to indicate UDP (instead of \fBSOCK_STREAM\fR +for TCP). +.PP +.Vb 6 +\& /* +\& * Lookup IP address info for the server. +\& */ +\& if (!BIO_lookup_ex(hostname, port, BIO_LOOKUP_CLIENT, family, SOCK_DGRAM, 0, +\& &res)) +\& return NULL; +\& +\& /* +\& * Loop through all the possible addresses for the server and find one +\& * we can connect to. +\& */ +\& for (ai = res; ai != NULL; ai = BIO_ADDRINFO_next(ai)) { +\& /* +\& * Create a TCP socket. We could equally use non\-OpenSSL calls such +\& * as "socket" here for this and the subsequent connect and close +\& * functions. But for portability reasons and also so that we get +\& * errors on the OpenSSL stack in the event of a failure we use +\& * OpenSSL\*(Aqs versions of these functions. +\& */ +\& sock = BIO_socket(BIO_ADDRINFO_family(ai), SOCK_DGRAM, 0, 0); +\& if (sock == \-1) +\& continue; +\& +\& /* Connect the socket to the server\*(Aqs address */ +\& if (!BIO_connect(sock, BIO_ADDRINFO_address(ai), 0)) { +\& BIO_closesocket(sock); +\& sock = \-1; +\& continue; +\& } +\& +\& /* Set to nonblocking mode */ +\& if (!BIO_socket_nbio(sock, 1)) { +\& BIO_closesocket(sock); +\& sock = \-1; +\& continue; +\& } +\& +\& break; +\& } +\& +\& if (sock != \-1) { +\& *peer_addr = BIO_ADDR_dup(BIO_ADDRINFO_address(ai)); +\& if (*peer_addr == NULL) { +\& BIO_closesocket(sock); +\& return NULL; +\& } +\& } +\& +\& /* Free the address information resources we allocated earlier */ +\& BIO_ADDRINFO_free(res); +.Ve +.PP +You may notice a couple of other differences between this code and the version +that we used for TLS. +.PP +Firstly, we set the socket into nonblocking mode. This must always be done for +an OpenSSL QUIC application. This may be surprising considering that we are +trying to write a blocking client. Despite this the \fBSSL\fR object will still +have blocking behaviour. See \fBossl\-guide\-quic\-introduction\fR\|(7) for further +information on this. +.PP +Secondly, we take note of the IP address of the peer that we are connecting to. +We store that information away. We will need it later. +.PP +See \fBBIO_lookup_ex\fR\|(3), \fBBIO_socket\fR\|(3), \fBBIO_connect\fR\|(3), +\&\fBBIO_closesocket\fR\|(3), \fBBIO_ADDRINFO_next\fR\|(3), \fBBIO_ADDRINFO_address\fR\|(3), +\&\fBBIO_ADDRINFO_free\fR\|(3) and \fBBIO_ADDR_dup\fR\|(3) for further information on the +functions used here. In the above example code the \fBhostname\fR and \fBport\fR +variables are strings, e.g. "www.example.com" and "443". +.PP +As for our TLS client, once the socket has been created and connected we need to +associate it with a BIO object: +.PP +.Vb 1 +\& BIO *bio; +\& +\& /* Create a BIO to wrap the socket */ +\& bio = BIO_new(BIO_s_datagram()); +\& if (bio == NULL) { +\& BIO_closesocket(sock); +\& return NULL; +\& } +\& +\& /* +\& * Associate the newly created BIO with the underlying socket. By +\& * passing BIO_CLOSE here the socket will be automatically closed when +\& * the BIO is freed. Alternatively you can use BIO_NOCLOSE, in which +\& * case you must close the socket explicitly when it is no longer +\& * needed. +\& */ +\& BIO_set_fd(bio, sock, BIO_CLOSE); +.Ve +.PP +Note the use of \fBBIO_s_datagram\fR\|(3) here as opposed to \fBBIO_s_socket\fR\|(3) that +we used for our TLS client. This is again due to the fact that QUIC uses UDP +instead of TCP for its transport layer. See \fBBIO_new\fR\|(3), \fBBIO_s_datagram\fR\|(3) +and \fBBIO_set_fd\fR\|(3) for further information on these functions. +.SS "Setting the server\*(Aqs hostname" +.IX Subsection "Setting the server's hostname" +As in the TLS tutorial we need to set the server\*(Aqs hostname both for SNI (Server +Name Indication) and for certificate validation purposes. The steps for this are +identical to the TLS tutorial and won\*(Aqt be repeated here. +.SS "Setting the ALPN" +.IX Subsection "Setting the ALPN" +ALPN (Application\-Layer Protocol Negotiation) is a feature of TLS that enables +the application to negotiate which protocol will be used over the connection. +For example, if you intend to use HTTP/3 over the connection then the ALPN value +for that is "h3" (see +). +OpenSSL provides the ability for a client to specify the ALPN to use via the +\&\fBSSL_set_alpn_protos\fR\|(3) function. This is optional for a TLS client and so our +simple client that we developed in \fBossl\-guide\-tls\-client\-block\fR\|(7) did not use +it. However QUIC mandates that the TLS handshake used in establishing a QUIC +connection must use ALPN. +.PP +.Vb 1 +\& unsigned char alpn[] = { 8, \*(Aqh\*(Aq, \*(Aqt\*(Aq, \*(Aqt\*(Aq, \*(Aqp\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq, \*(Aq.\*(Aq, \*(Aq0\*(Aq }; +\& +\& /* SSL_set_alpn_protos returns 0 for success! */ +\& if (SSL_set_alpn_protos(ssl, alpn, sizeof(alpn)) != 0) { +\& printf("Failed to set the ALPN for the connection\en"); +\& goto end; +\& } +.Ve +.PP +The ALPN is specified using a length prefixed array of unsigned chars (it is not +a NUL terminated string). Our original TLS blocking client demo was using +HTTP/1.0. We will use the same for this example. Unlike most OpenSSL functions +\&\fBSSL_set_alpn_protos\fR\|(3) returns zero for success and nonzero for failure. +.SS "Setting the peer address" +.IX Subsection "Setting the peer address" +An OpenSSL QUIC application must specify the target address of the server that +is being connected to. In "Creating the socket and BIO" above we saved that +address away for future use. Now we need to use it via the +\&\fBSSL_set1_initial_peer_addr\fR\|(3) function. +.PP +.Vb 5 +\& /* Set the IP address of the remote peer */ +\& if (!SSL_set1_initial_peer_addr(ssl, peer_addr)) { +\& printf("Failed to set the initial peer address\en"); +\& goto end; +\& } +.Ve +.PP +Note that we will need to free the \fBpeer_addr\fR value that we allocated via +\&\fBBIO_ADDR_dup\fR\|(3) earlier: +.PP +.Vb 1 +\& BIO_ADDR_free(peer_addr); +.Ve +.SS "The handshake and application data transfer" +.IX Subsection "The handshake and application data transfer" +Once initial setup of the \fBSSL\fR object is complete then we perform the +handshake via \fBSSL_connect\fR\|(3) in exactly the same way as we did for the TLS +client, so we won\*(Aqt repeat it here. +.PP +We can also perform data transfer using a default QUIC stream that is +automatically associated with the \fBSSL\fR object for us. We can transmit data +using \fBSSL_write_ex\fR\|(3), and receive data using \fBSSL_read_ex\fR\|(3) in the same +way as for TLS. The main difference is that we have to account for failures +slightly differently. With QUIC the stream can be reset by the peer (which is +fatal for that stream), but the underlying connection itself may still be +healthy. +.PP +First, we write the entire request to the stream. We also must make sure to +signal to the server that we have finished writing. This can be done by passing +the SSL_WRITE_FLAG_CONCLUDE flag to \fBSSL_write_ex2\fR\|(3) or by calling +\&\fBSSL_stream_conclude\fR\|(3). Since the first way is more efficient, we choose to +do that. +.PP +.Vb 10 +\& /* Write an HTTP GET request to the peer */ +\& if (!SSL_write_ex(ssl, request_start, strlen(request_start), &written)) { +\& printf("Failed to write start of HTTP request\en"); +\& goto end; +\& } +\& if (!SSL_write_ex(ssl, hostname, strlen(hostname), &written)) { +\& printf("Failed to write hostname in HTTP request\en"); +\& goto end; +\& } +\& if (!SSL_write_ex2(ssl, request_end, strlen(request_end), +\& SSL_WRITE_FLAG_CONCLUDE, &written)) { +\& printf("Failed to write end of HTTP request\en"); +\& goto end; +\& } +.Ve +.PP +Then, we read the response from the server. +.PP +.Vb 10 +\& /* +\& * Get up to sizeof(buf) bytes of the response. We keep reading until the +\& * server closes the connection. +\& */ +\& while (SSL_read_ex(ssl, buf, sizeof(buf), &readbytes)) { +\& /* +\& * OpenSSL does not guarantee that the returned data is a string or +\& * that it is NUL terminated so we use fwrite() to write the exact +\& * number of bytes that we read. The data could be non\-printable or +\& * have NUL characters in the middle of it. For this simple example +\& * we\*(Aqre going to print it to stdout anyway. +\& */ +\& fwrite(buf, 1, readbytes, stdout); +\& } +\& /* In case the response didn\*(Aqt finish with a newline we add one now */ +\& printf("\en"); +\& +\& /* +\& * Check whether we finished the while loop above normally or as the +\& * result of an error. The 0 argument to SSL_get_error() is the return +\& * code we received from the SSL_read_ex() call. It must be 0 in order +\& * to get here. Normal completion is indicated by SSL_ERROR_ZERO_RETURN. In +\& * QUIC terms this means that the peer has sent FIN on the stream to +\& * indicate that no further data will be sent. +\& */ +\& switch (SSL_get_error(ssl, 0)) { +\& case SSL_ERROR_ZERO_RETURN: +\& /* Normal completion of the stream */ +\& break; +\& +\& case SSL_ERROR_SSL: +\& /* +\& * Some stream fatal error occurred. This could be because of a stream +\& * reset \- or some failure occurred on the underlying connection. +\& */ +\& switch (SSL_get_stream_read_state(ssl)) { +\& case SSL_STREAM_STATE_RESET_REMOTE: +\& printf("Stream reset occurred\en"); +\& /* The stream has been reset but the connection is still healthy. */ +\& break; +\& +\& case SSL_STREAM_STATE_CONN_CLOSED: +\& printf("Connection closed\en"); +\& /* Connection is already closed. Skip SSL_shutdown() */ +\& goto end; +\& +\& default: +\& printf("Unknown stream failure\en"); +\& break; +\& } +\& break; +\& +\& default: +\& /* Some other unexpected error occurred */ +\& printf ("Failed reading remaining data\en"); +\& break; +\& } +.Ve +.PP +In the above code example you can see that \fBSSL_ERROR_SSL\fR indicates a stream +fatal error. We can use \fBSSL_get_stream_read_state\fR\|(3) to determine whether the +stream has been reset, or if some other fatal error has occurred. +.SS "Shutting down the connection" +.IX Subsection "Shutting down the connection" +In the TLS tutorial we knew that the server had finished sending data because +\&\fBSSL_read_ex\fR\|(3) returned 0, and \fBSSL_get_error\fR\|(3) returned +\&\fBSSL_ERROR_ZERO_RETURN\fR. The same is true with QUIC except that +\&\fBSSL_ERROR_ZERO_RETURN\fR should be interpreted slightly differently. With TLS +we knew that this meant that the server had sent a "close_notify" alert. No +more data will be sent from the server on that connection. +.PP +With QUIC it means that the server has indicated "FIN" on the stream, meaning +that it will no longer send any more data on that stream. However this only +gives us information about the stream itself and does not tell us anything about +the underlying connection. More data could still be sent from the server on some +other stream. Additionally, although the server will not send any more data to +the client, it does not prevent the client from sending more data to the server. +.PP +In this tutorial, once we have finished reading data from the server on the one +stream that we are using, we will close the connection down. As before we do +this via the \fBSSL_shutdown\fR\|(3) function. This example for QUIC is very similar +to the TLS version. However the \fBSSL_shutdown\fR\|(3) function will need to be +called more than once: +.PP +.Vb 11 +\& /* +\& * Repeatedly call SSL_shutdown() until the connection is fully +\& * closed. +\& */ +\& do { +\& ret = SSL_shutdown(ssl); +\& if (ret < 0) { +\& printf("Error shutting down: %d\en", ret); +\& goto end; +\& } +\& } while (ret != 1); +.Ve +.PP +The shutdown process is in two stages. In the first stage we wait until all the +data we have buffered for sending on any stream has been successfully sent and +acknowledged by the peer, and then we send a CONNECTION_CLOSE to the peer to +indicate that the connection is no longer usable. This immediately closes the +connection and no more data can be sent or received. \fBSSL_shutdown\fR\|(3) returns +0 once the first stage has been completed. +.PP +In the second stage the connection enters a "closing" state. Application data +cannot be sent or received in this state, but late arriving packets coming from +the peer will be handled appropriately. Once this stage has completed +successfully \fBSSL_shutdown\fR\|(3) will return 1 to indicate success. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-quic\-multi\-stream\fR\|(7) to read a tutorial on how to modify the +client developed on this page to support multiple streams. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7), +\&\fBossl\-guide\-tls\-client\-block\fR\|(7), \fBossl\-guide\-quic\-introduction\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-quic-client-non-block.7 b/static/netbsd/man7/ossl-guide-quic-client-non-block.7 new file mode 100644 index 00000000..33e9a9bf --- /dev/null +++ b/static/netbsd/man7/ossl-guide-quic-client-non-block.7 @@ -0,0 +1,533 @@ +.\" $NetBSD: ossl-guide-quic-client-non-block.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-QUIC-CLIENT-NON-BLOCK 7" +.TH OSSL-GUIDE-QUIC-CLIENT-NON-BLOCK 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-quic\-client\-non\-block +\&\- OpenSSL Guide: Writing a simple nonblocking QUIC client +.SH "SIMPLE NONBLOCKING QUIC CLIENT EXAMPLE" +.IX Header "SIMPLE NONBLOCKING QUIC CLIENT EXAMPLE" +This page will build on the example developed on the +\&\fBossl\-guide\-quic\-client\-block\fR\|(7) page which demonstrates how to write a simple +blocking QUIC client. On this page we will amend that demo code so that it +supports nonblocking functionality. +.PP +The complete source code for this example nonblocking QUIC client is available +in the \fBdemos/guide\fR directory of the OpenSSL source distribution in the file +\&\fBquic\-client\-non\-block.c\fR. It is also available online at +. +.PP +As we saw in the previous example an OpenSSL QUIC application always uses a +nonblocking socket. However, despite this, the \fBSSL\fR object still has blocking +behaviour. When the \fBSSL\fR object has blocking behaviour then this means that +it waits (blocks) until data is available to read if you attempt to read from +it when there is no data yet. Similarly it waits when writing if the \fBSSL\fR +object is currently unable to write at the moment. This can simplify the +development of code because you do not have to worry about what to do in these +cases. The execution of the code will simply stop until it is able to continue. +However in many cases you do not want this behaviour. Rather than stopping and +waiting your application may need to go and do other tasks whilst the \fBSSL\fR +object is unable to read/write, for example updating a GUI or performing +operations on some other connection or stream. +.PP +We will see later in this tutorial how to change the \fBSSL\fR object so that it +has nonblocking behaviour. With a nonblocking \fBSSL\fR object, functions such as +\&\fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(3) will return immediately with a non\-fatal +error if they are currently unable to read or write respectively. +.PP +Since this page is building on the example developed on the +\&\fBossl\-guide\-quic\-client\-block\fR\|(7) page we assume that you are familiar with it +and we only explain how this example differs. +.SS "Performing work while waiting for the socket" +.IX Subsection "Performing work while waiting for the socket" +In a nonblocking application you will need work to perform in the event that +we want to read or write to the \fBSSL\fR object but we are currently unable to. +In fact this is the whole point of using a nonblocking \fBSSL\fR object, i.e. to +give the application the opportunity to do something else. Whatever it is that +the application has to do, it must also be prepared to come back and retry the +operation that it previously attempted periodically to see if it can now +complete. Ideally it would only do this in the event that something has changed +such that it might succeed on the retry attempt, but this does not have to be +the case. It can retry at any time. +.PP +Note that it is important that you retry exactly the same operation that you +tried last time. You cannot start something new. For example if you were +attempting to write the text "Hello World" and the operation failed because the +\&\fBSSL\fR object is currently unable to write, then you cannot then attempt to +write some other text when you retry the operation. +.PP +In this demo application we will create a helper function which simulates doing +other work. In fact, for the sake of simplicity, it will do nothing except wait +for the state of the underlying socket to change or until a timeout expires +after which the state of the \fBSSL\fR object might have changed. We will call our +function \f(CWwait_for_activity()\fR. +.PP +.Vb 6 +\& static void wait_for_activity(SSL *ssl) +\& { +\& fd_set wfds, rfds; +\& int width, sock, isinfinite; +\& struct timeval tv; +\& struct timeval *tvp = NULL; +\& +\& /* Get hold of the underlying file descriptor for the socket */ +\& sock = SSL_get_fd(ssl); +\& +\& FD_ZERO(&wfds); +\& FD_ZERO(&rfds); +\& +\& /* +\& * Find out if we would like to write to the socket, or read from it (or +\& * both) +\& */ +\& if (SSL_net_write_desired(ssl)) +\& FD_SET(sock, &wfds); +\& if (SSL_net_read_desired(ssl)) +\& FD_SET(sock, &rfds); +\& width = sock + 1; +\& +\& /* +\& * Find out when OpenSSL would next like to be called, regardless of +\& * whether the state of the underlying socket has changed or not. +\& */ +\& if (SSL_get_event_timeout(ssl, &tv, &isinfinite) && !isinfinite) +\& tvp = &tv; +\& +\& /* +\& * Wait until the socket is writeable or readable. We use select here +\& * for the sake of simplicity and portability, but you could equally use +\& * poll/epoll or similar functions +\& * +\& * NOTE: For the purposes of this demonstration code this effectively +\& * makes this demo block until it has something more useful to do. In a +\& * real application you probably want to go and do other work here (e.g. +\& * update a GUI, or service other connections). +\& * +\& * Let\*(Aqs say for example that you want to update the progress counter on +\& * a GUI every 100ms. One way to do that would be to use the timeout in +\& * the last parameter to "select" below. If the tvp value is greater +\& * than 100ms then use 100ms instead. Then, when select returns, you +\& * check if it did so because of activity on the file descriptors or +\& * because of the timeout. If the 100ms GUI timeout has expired but the +\& * tvp timeout has not then go and update the GUI and then restart the +\& * "select" (with updated timeouts). +\& */ +\& +\& select(width, &rfds, &wfds, NULL, tvp); +\&} +.Ve +.PP +If you are familiar with how to write nonblocking applications in OpenSSL for +TLS (see \fBossl\-guide\-tls\-client\-non\-block\fR\|(7)) then you should note that there +is an important difference here between the way a QUIC application and a TLS +application works. With a TLS application if we try to read or write something +to the \fBSSL\fR object and we get a "retry" response (\fBSSL_ERROR_WANT_READ\fR or +\&\fBSSL_ERROR_WANT_WRITE\fR) then we can assume that is because OpenSSL attempted to +read or write to the underlying socket and the socket signalled the "retry". +With QUIC that is not the case. OpenSSL may signal retry as a result of an +\&\fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(3) (or similar) call which indicates the +state of the stream. This is entirely independent of whether the underlying +socket needs to retry or not. +.PP +To determine whether OpenSSL currently wants to read or write to the underlying +socket for a QUIC application we must call the \fBSSL_net_read_desired\fR\|(3) and +\&\fBSSL_net_write_desired\fR\|(3) functions. +.PP +It is also important with QUIC that we periodically call an I/O function (or +otherwise call the \fBSSL_handle_events\fR\|(3) function) to ensure that the QUIC +connection remains healthy. This is particularly important with a nonblocking +application because you are likely to leave the \fBSSL\fR object idle for a while +while the application goes off to do other work. The \fBSSL_get_event_timeout\fR\|(3) +function can be used to determine what the deadline is for the next time we need +to call an I/O function (or call \fBSSL_handle_events\fR\|(3)). +.PP +An alternative to using \fBSSL_get_event_timeout\fR\|(3) to find the next deadline +that OpenSSL must be called again by is to use "thread assisted" mode. In +"thread assisted" mode OpenSSL spawns an additional thread which will +periodically call \fBSSL_handle_events\fR\|(3) automatically, meaning that the +application can leave the connection idle safe in the knowledge that the +connection will still be maintained in a healthy state. See +"Creating the SSL_CTX and SSL objects" below for further details about this. +.PP +In this example we are using the \f(CW\*(C`select\*(C'\fR function to check the +readability/writeability of the socket because it is very simple to use and is +available on most Operating Systems. However you could use any other similar +function to do the same thing. \f(CW\*(C`select\*(C'\fR waits for the state of the underlying +socket(s) to become readable/writeable or until the timeout has expired before +returning. +.SS "Handling errors from OpenSSL I/O functions" +.IX Subsection "Handling errors from OpenSSL I/O functions" +A QUIC application that has been configured for nonblocking behaviour will need +to be prepared to handle errors returned from OpenSSL I/O functions such as +\&\fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(3). Errors may be fatal for the stream (for +example because the stream has been reset or because the underlying connection +has failed), or non\-fatal (for example because we are trying to read from the +stream but no data has not yet arrived from the peer for that stream). +.PP +\&\fBSSL_read_ex\fR\|(3) and \fBSSL_write_ex\fR\|(3) will return 0 to indicate an error and +\&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) will return 0 or a negative value to indicate +an error. \fBSSL_shutdown\fR\|(3) will return a negative value to incidate an error. +.PP +In the event of an error an application should call \fBSSL_get_error\fR\|(3) to find +out what type of error has occurred. If the error is non\-fatal and can be +retried then \fBSSL_get_error\fR\|(3) will return \fBSSL_ERROR_WANT_READ\fR or +\&\fBSSL_ERROR_WANT_WRITE\fR depending on whether OpenSSL wanted to read to or write +from the stream but was unable to. Note that a call to \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_read\fR\|(3) can still generate \fBSSL_ERROR_WANT_WRITE\fR. Similarly calls to +\&\fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) might generate \fBSSL_ERROR_WANT_READ\fR. +.PP +Another type of non\-fatal error that may occur is \fBSSL_ERROR_ZERO_RETURN\fR. This +indicates an EOF (End\-Of\-File) which can occur if you attempt to read data from +an \fBSSL\fR object but the peer has indicated that it will not send any more data +on the stream. In this case you may still want to write data to the stream but +you will not receive any more data. +.PP +Fatal errors that may occur are \fBSSL_ERROR_SYSCALL\fR and \fBSSL_ERROR_SSL\fR. These +indicate that the stream is no longer usable. For example, this could be because +the stream has been reset by the peer, or because the underlying connection has +failed. You can consult the OpenSSL error stack for further details (for example +by calling \fBERR_print_errors\fR\|(3) to print out details of errors that have +occurred). You can also consult the return value of +\&\fBSSL_get_stream_read_state\fR\|(3) to determine whether the error is local to the +stream, or whether the underlying connection has also failed. A return value +of \fBSSL_STREAM_STATE_RESET_REMOTE\fR tells you that the stream has been reset by +the peer and \fBSSL_STREAM_STATE_CONN_CLOSED\fR tells you that the underlying +connection has closed. +.PP +In our demo application we will write a function to handle these errors from +OpenSSL I/O functions: +.PP +.Vb 8 +\& static int handle_io_failure(SSL *ssl, int res) +\& { +\& switch (SSL_get_error(ssl, res)) { +\& case SSL_ERROR_WANT_READ: +\& case SSL_ERROR_WANT_WRITE: +\& /* Temporary failure. Wait until we can read/write and try again */ +\& wait_for_activity(ssl); +\& return 1; +\& +\& case SSL_ERROR_ZERO_RETURN: +\& /* EOF */ +\& return 0; +\& +\& case SSL_ERROR_SYSCALL: +\& return \-1; +\& +\& case SSL_ERROR_SSL: +\& /* +\& * Some stream fatal error occurred. This could be because of a +\& * stream reset \- or some failure occurred on the underlying +\& * connection. +\& */ +\& switch (SSL_get_stream_read_state(ssl)) { +\& case SSL_STREAM_STATE_RESET_REMOTE: +\& printf("Stream reset occurred\en"); +\& /* +\& * The stream has been reset but the connection is still +\& * healthy. +\& */ +\& break; +\& +\& case SSL_STREAM_STATE_CONN_CLOSED: +\& printf("Connection closed\en"); +\& /* Connection is already closed. */ +\& break; +\& +\& default: +\& printf("Unknown stream failure\en"); +\& break; +\& } +\& /* +\& * If the failure is due to a verification error we can get more +\& * information about it from SSL_get_verify_result(). +\& */ +\& if (SSL_get_verify_result(ssl) != X509_V_OK) +\& printf("Verify error: %s\en", +\& X509_verify_cert_error_string(SSL_get_verify_result(ssl))); +\& return \-1; +\& +\& default: +\& return \-1; +\& } +\& } +.Ve +.PP +This function takes as arguments the \fBSSL\fR object that represents the +connection, as well as the return code from the I/O function that failed. In +the event of a non\-fatal failure, it waits until a retry of the I/O operation +might succeed (by using the \f(CWwait_for_activity()\fR function that we developed +in the previous section). It returns 1 in the event of a non\-fatal error +(except EOF), 0 in the event of EOF, or \-1 if a fatal error occurred. +.SS "Creating the SSL_CTX and SSL objects" +.IX Subsection "Creating the SSL_CTX and SSL objects" +In order to connect to a server we must create \fBSSL_CTX\fR and \fBSSL\fR objects for +this. Most of the steps to do this are the same as for a blocking client and are +explained on the \fBossl\-guide\-quic\-client\-block\fR\|(7) page. We won\*(Aqt repeat that +information here. +.PP +One key difference is that we must put the \fBSSL\fR object into nonblocking mode +(the default is blocking mode). To do that we use the +\&\fBSSL_set_blocking_mode\fR\|(3) function: +.PP +.Vb 9 +\& /* +\& * The underlying socket is always nonblocking with QUIC, but the default +\& * behaviour of the SSL object is still to block. We set it for nonblocking +\& * mode in this demo. +\& */ +\& if (!SSL_set_blocking_mode(ssl, 0)) { +\& printf("Failed to turn off blocking mode\en"); +\& goto end; +\& } +.Ve +.PP +Although the demo application that we are developing here does not use it, it is +possible to use "thread assisted mode" when developing QUIC applications. +Normally, when writing an OpenSSL QUIC application, it is important that +\&\fBSSL_handle_events\fR\|(3) (or alternatively any I/O function) is called on the +connection \fBSSL\fR object periodically to maintain the connection in a healthy +state. See "Performing work while waiting for the socket" for more discussion +on this. This is particularly important to keep in mind when writing a +nonblocking QUIC application because it is common to leave the \fBSSL\fR connection +object idle for some time when using nonblocking mode. By using "thread assisted +mode" a separate thread is created by OpenSSL to do this automatically which +means that the application developer does not need to handle this aspect. To do +this we must use \fBOSSL_QUIC_client_thread_method\fR\|(3) when we construct the +\&\fBSSL_CTX\fR as shown below: +.PP +.Vb 5 +\& ctx = SSL_CTX_new(OSSL_QUIC_client_thread_method()); +\& if (ctx == NULL) { +\& printf("Failed to create the SSL_CTX\en"); +\& goto end; +\& } +.Ve +.SS "Performing the handshake" +.IX Subsection "Performing the handshake" +As in the demo for a blocking QUIC client we use the \fBSSL_connect\fR\|(3) function +to perform the handshake with the server. Since we are using a nonblocking +\&\fBSSL\fR object it is very likely that calls to this function will fail with a +non\-fatal error while we are waiting for the server to respond to our handshake +messages. In such a case we must retry the same \fBSSL_connect\fR\|(3) call at a +later time. In this demo we do this in a loop: +.PP +.Vb 7 +\& /* Do the handshake with the server */ +\& while ((ret = SSL_connect(ssl)) != 1) { +\& if (handle_io_failure(ssl, ret) == 1) +\& continue; /* Retry */ +\& printf("Failed to connect to server\en"); +\& goto end; /* Cannot retry: error */ +\& } +.Ve +.PP +We continually call \fBSSL_connect\fR\|(3) until it gives us a success response. +Otherwise we use the \f(CWhandle_io_failure()\fR function that we created earlier to +work out what we should do next. Note that we do not expect an EOF to occur at +this stage, so such a response is treated in the same way as a fatal error. +.SS "Sending and receiving data" +.IX Subsection "Sending and receiving data" +As with the blocking QUIC client demo we use the \fBSSL_write_ex\fR\|(3) function to +send data to the server. As with \fBSSL_connect\fR\|(3) above, because we are using +a nonblocking \fBSSL\fR object, this call could fail with a non\-fatal error. In +that case we should retry exactly the same \fBSSL_write_ex\fR\|(3) call again. Note +that the parameters must be \fIexactly\fR the same, i.e. the same pointer to the +buffer to write with the same length. You must not attempt to send different +data on a retry. An optional mode does exist +(\fBSSL_MODE_ACCEPT_MOVING_WRITE_BUFFER\fR) which will configure OpenSSL to allow +the buffer being written to change from one retry to the next. However, in this +case, you must still retry exactly the same data \- even though the buffer that +contains that data may change location. See \fBSSL_CTX_set_mode\fR\|(3) for further +details. As in the TLS tutorials (\fBossl\-guide\-tls\-client\-block\fR\|(7)) we write +the request in three chunks. +.PP +First, we write the entire request to the stream. We also must make sure to +signal to the server that we have finished writing. This can be done by passing +the SSL_WRITE_FLAG_CONCLUDE flag to \fBSSL_write_ex2\fR\|(3) or by calling +\&\fBSSL_stream_conclude\fR\|(3). Since the first way is more efficient, we choose to +do that. +.PP +.Vb 10 +\& /* Write an HTTP GET request to the peer */ +\& while (!SSL_write_ex(ssl, request_start, strlen(request_start), &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write start of HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& while (!SSL_write_ex(ssl, hostname, strlen(hostname), &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write hostname in HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& while (!SSL_write_ex2(ssl, request_end, strlen(request_end), +\& SSL_WRITE_FLAG_CONCLUDE, &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write end of HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +.Ve +.PP +On a write we do not expect to see an EOF response so we treat that case in the +same way as a fatal error. +.PP +Reading a response back from the server is similar: +.PP +.Vb 10 +\& do { +\& /* +\& * Get up to sizeof(buf) bytes of the response. We keep reading until +\& * the server closes the connection. +\& */ +\& while (!eof && !SSL_read_ex(ssl, buf, sizeof(buf), &readbytes)) { +\& switch (handle_io_failure(ssl, 0)) { +\& case 1: +\& continue; /* Retry */ +\& case 0: +\& eof = 1; +\& continue; +\& case \-1: +\& default: +\& printf("Failed reading remaining data\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& } +\& /* +\& * OpenSSL does not guarantee that the returned data is a string or +\& * that it is NUL terminated so we use fwrite() to write the exact +\& * number of bytes that we read. The data could be non\-printable or +\& * have NUL characters in the middle of it. For this simple example +\& * we\*(Aqre going to print it to stdout anyway. +\& */ +\& if (!eof) +\& fwrite(buf, 1, readbytes, stdout); +\& } while (!eof); +\& /* In case the response didn\*(Aqt finish with a newline we add one now */ +\& printf("\en"); +.Ve +.PP +The main difference this time is that it is valid for us to receive an EOF +response when trying to read data from the server. This will occur when the +server closes down the connection after sending all the data in its response. +.PP +In this demo we just print out all the data we\*(Aqve received back in the response +from the server. We continue going around the loop until we either encounter a +fatal error, or we receive an EOF (indicating a graceful finish). +.SS "Shutting down the connection" +.IX Subsection "Shutting down the connection" +As in the QUIC blocking example we must shutdown the connection when we are +finished with it. +.PP +Even though we have received EOF on the stream that we were reading from above, +this tell us nothing about the state of the underlying connection. Our demo +application will initiate the connection shutdown process via +\&\fBSSL_shutdown\fR\|(3). +.PP +Since our application is initiating the shutdown then we might expect to see +\&\fBSSL_shutdown\fR\|(3) give a return value of 0, and then we should continue to call +it until we receive a return value of 1 (meaning we have successfully completed +the shutdown). Since we are using a nonblocking \fBSSL\fR object we might expect to +have to retry this operation several times. If \fBSSL_shutdown\fR\|(3) returns a +negative result then we must call \fBSSL_get_error\fR\|(3) to work out what to do +next. We use our \fBhandle_io_failure()\fR function that we developed earlier for +this: +.PP +.Vb 8 +\& /* +\& * Repeatedly call SSL_shutdown() until the connection is fully +\& * closed. +\& */ +\& while ((ret = SSL_shutdown(ssl)) != 1) { +\& if (ret < 0 && handle_io_failure(ssl, ret) == 1) +\& continue; /* Retry */ +\& } +.Ve +.SS "Final clean up" +.IX Subsection "Final clean up" +As with the blocking QUIC client example, once our connection is finished with +we must free it. The steps to do this for this example are the same as for the +blocking example, so we won\*(Aqt repeat it here. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-quic\-client\-block\fR\|(7) to read a tutorial on how to write a +blocking QUIC client. See \fBossl\-guide\-quic\-multi\-stream\fR\|(7) to see how to write +a multi\-stream QUIC client. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-quic\-introduction\fR\|(7), +\&\fBossl\-guide\-quic\-client\-block\fR\|(7), \fBossl\-guide\-quic\-multi\-stream\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-quic-introduction.7 b/static/netbsd/man7/ossl-guide-quic-introduction.7 new file mode 100644 index 00000000..7e19ec88 --- /dev/null +++ b/static/netbsd/man7/ossl-guide-quic-introduction.7 @@ -0,0 +1,237 @@ +.\" $NetBSD: ossl-guide-quic-introduction.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-QUIC-INTRODUCTION 7" +.TH OSSL-GUIDE-QUIC-INTRODUCTION 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-quic\-introduction +\&\- OpenSSL Guide: An introduction to QUIC in OpenSSL +.SH INTRODUCTION +.IX Header "INTRODUCTION" +This page will provide an introduction to some basic QUIC concepts and +background and how it is used within OpenSSL. It assumes that you have a basic +understanding of UDP/IP and sockets. It also assumes that you are familiar with +some OpenSSL and TLS fundamentals (see \fBossl\-guide\-libraries\-introduction\fR\|(7) +and \fBossl\-guide\-tls\-introduction\fR\|(7)). +.SH "WHAT IS QUIC?" +.IX Header "WHAT IS QUIC?" +QUIC is a general purpose protocol for enabling applications to securely +communicate over a network. It is defined in RFC9000 (see +). QUIC integrates parts of the +TLS protocol for connection establishment but independently protects packets. +It provides similar security guarantees to TLS such as confidentiality, +integrity and authentication (see \fBossl\-guide\-tls\-introduction\fR\|(7)). +.PP +QUIC delivers a number of advantages: +.IP "Multiple streams" 4 +.IX Item "Multiple streams" +It supports multiple streams of communication (see "QUIC STREAMS" below), +allowing application protocols built on QUIC to create arbitrarily many +bytestreams for communication between a client and server. This allows an +application protocol to avoid problems where one packet of data is held up +waiting on another packet being delivered (commonly referred to as +"head\-of\-line blocking"). It also enables an application to open additional +logical streams without requiring a round\-trip exchange of packets between the +client and server as is required when opening an additional TLS/TCP +connection. +.IP HTTP/3 4 +.IX Item "HTTP/3" +Since QUIC is the basis of HTTP/3, support for QUIC also enables applications +to use HTTP/3 using a suitable third\-party library. +.IP "Fast connection initiation" 4 +.IX Item "Fast connection initiation" +Future versions of OpenSSL will offer support for 0\-RTT connection initiation, +allowing a connection to be initiated to a server and application data to be +transmitted without any waiting time. This is similar to TLS 1.3\*(Aqs 0\-RTT +functionality but also avoids the round trip needed to open a TCP socket; thus, +it is similar to a combination of TLS 1.3 0\-RTT and TCP Fast Open. +.IP "Connection migration" 4 +.IX Item "Connection migration" +Future versions of OpenSSL will offer support for connection migration, allowing +connections to seamlessly survive IP address changes. +.IP "Datagram based use cases" 4 +.IX Item "Datagram based use cases" +Future versions of OpenSSL will offer support for the QUIC datagram extension, +allowing support for both TLS and DTLS\-style use cases on a single connection. +.IP "Implemented as application library" 4 +.IX Item "Implemented as application library" +Because most QUIC implementations, including OpenSSL\*(Aqs implementation, are +implemented as an application library rather than by an operating system, an +application can gain the benefit of QUIC without needing to wait for an OS +update to be deployed. Future evolutions and enhancements to the QUIC protocol +can be delivered as quickly as an application can be updated without dependency +on an OS update cadence. +.IP "Multiplexing over a single UDP socket" 4 +.IX Item "Multiplexing over a single UDP socket" +Because QUIC is UDP\-based, it is possible to multiplex a QUIC connection on the +same UDP socket as some other UDP\-based protocols, such as RTP. +.SH "QUIC TIME BASED EVENTS" +.IX Header "QUIC TIME BASED EVENTS" +A key difference between the TLS implementation and the QUIC implementation in +OpenSSL is how time is handled. The QUIC protocol requires various actions to be +performed on a regular basis regardless of whether application data is being +transmitted or received. +.PP +OpenSSL introduces a new function \fBSSL_handle_events\fR\|(3) that will +automatically process any outstanding time based events that must be handled. +Alternatively calling any I/O function such as \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_write_ex\fR\|(3) will also process these events. There is also +\&\fBSSL_get_event_timeout\fR\|(3) which tells an application the amount of time that +remains until \fBSSL_handle_events\fR\|(3) (or any I/O function) must be called. +.PP +Fortunately a blocking application that does not leave the QUIC connection idle, +and is regularly calling I/O functions does not typically need to worry about +this. However if you are developing a nonblocking application or one that may +leave the QUIC connection idle for a period of time then you will need to +arrange to call these functions. +.PP +OpenSSL provides an optional "thread assisted mode" that will automatically +create a background thread and will regularly call \fBSSL_handle_events\fR\|(3) in a +thread safe manner. This provides a simple way for an application to satisfy the +QUIC requirements for time based events without having to implement special +logic to accomplish it. +.SH "QUIC AND TLS" +.IX Header "QUIC AND TLS" +QUIC reuses parts of the TLS protocol in its implementation. Specifically the +TLS handshake also exists in QUIC. The TLS handshake messages are wrapped up in +QUIC protocol messages in order to send them to the peer. Once the TLS handshake +is complete all application data is sent entirely using QUIC protocol messages +without using TLS \- although some TLS handshake messages may still be sent in +some circumstances. +.PP +This relationship between QUIC and TLS means that many of the API functions in +OpenSSL that apply to TLS connections also apply to QUIC connections and +applications can use them in exactly the same way. Some functions do not apply +to QUIC at all, and others have altered semantics. You should refer to the +documentation pages for each function for information on how it applies to QUIC. +Typically if QUIC is not mentioned in the manual pages then the functions apply +to both TLS and QUIC. +.SH "QUIC STREAMS" +.IX Header "QUIC STREAMS" +QUIC introduces the concept of "streams". A stream provides a reliable +mechanism for sending and receiving application data between the endpoints. The +bytes transmitted are guaranteed to be received in the same order they were sent +without any loss of data or reordering of the bytes. A TLS application +effectively has one bi\-directional stream available to it per TLS connection. A +QUIC application can have multiple uni\-directional or bi\-directional streams +available to it for each connection. +.PP +In OpenSSL an \fBSSL\fR object is used to represent both connections and streams. +A QUIC application creates an initial \fBSSL\fR object to represent the connection +(known as the connection \fBSSL\fR object). Once the connection is complete +additional \fBSSL\fR objects can be created to represent streams (known as stream +\&\fBSSL\fR objects). Unless configured otherwise, a "default" stream is also +associated with the connection \fBSSL\fR object so you can still write data and +read data to/from it. Some OpenSSL API functions can only be used with +connection \fBSSL\fR objects, and some can only be used with stream \fBSSL\fR objects. +Check the documentation for each function to confirm what type of \fBSSL\fR object +can be used in any particular context. A connection \fBSSL\fR object that has a +default stream attached to it can be used in contexts that require a connection +\&\fBSSL\fR object or in contexts that require a stream \fBSSL\fR object. +.SH "SOCKETS AND BLOCKING" +.IX Header "SOCKETS AND BLOCKING" +TLS assumes "stream" type semantics for its underlying transport layer protocol +(usually achieved by using TCP). However QUIC assumes "datagram" type semantics +by using UDP. An OpenSSL application using QUIC is responsible for creating a +BIO to represent the underlying transport layer. This BIO must support datagrams +and is typically \fBBIO_s_datagram\fR\|(3), but other \fBBIO\fR choices are available. +See \fBbio\fR\|(7) for an introduction to OpenSSL\*(Aqs \fBBIO\fR concept. +.PP +A significant difference between OpenSSL TLS applications and OpenSSL QUIC +applications is the way that blocking is implemented. In TLS if your application +expects blocking behaviour then you configure the underlying socket for +blocking. Conversely if your application wants nonblocking behaviour then the +underlying socket is configured to be nonblocking. +.PP +With an OpenSSL QUIC application the underlying socket must always be configured +to be nonblocking. Howevever the \fBSSL\fR object will, by default, still operate +in blocking mode. So, from an application\*(Aqs perspective, calls to functions such +as \fBSSL_read_ex\fR\|(3), \fBSSL_write_ex\fR\|(3) and other I/O functions will still +block. OpenSSL itself provides that blocking capability for QUIC instead of the +socket. If nonblocking behaviour is desired then the application must call +\&\fBSSL_set_blocking_mode\fR\|(3). +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-quic\-client\-block\fR\|(7) to see an example of applying these +concepts in order to write a simple blocking QUIC client. +.PP +See \fBossl\-guide\-quic\-server\-block\fR\|(7) to see an example of applying these +concepts in order to write a simple blocking QUIC server. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7), +\&\fBossl\-guide\-tls\-client\-block\fR\|(7), \fBossl\-guide\-quic\-client\-block\fR\|(7), +\&\fBossl\-guide\-quic\-client\-non\-block\fR\|(7), \fBossl\-guide\-quic\-multi\-stream\fR\|(7), +\&\fBossl\-guide\-quic\-server\-block\fR\|(7), \fBossl\-guide\-quic\-server\-non\-block\fR\|(7), +\&\fBbio\fR\|(7), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-quic-multi-stream.7 b/static/netbsd/man7/ossl-guide-quic-multi-stream.7 new file mode 100644 index 00000000..e0cf1488 --- /dev/null +++ b/static/netbsd/man7/ossl-guide-quic-multi-stream.7 @@ -0,0 +1,458 @@ +.\" $NetBSD: ossl-guide-quic-multi-stream.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-QUIC-MULTI-STREAM 7" +.TH OSSL-GUIDE-QUIC-MULTI-STREAM 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-quic\-multi\-stream +\&\- OpenSSL Guide: Writing a simple multi\-stream QUIC client +.SH INTRODUCTION +.IX Header "INTRODUCTION" +This page will introduce some important concepts required to write a simple +QUIC multi\-stream application. It assumes a basic understanding of QUIC and how +it is used in OpenSSL. See \fBossl\-guide\-quic\-introduction\fR\|(7) and +\&\fBossl\-guide\-quic\-client\-block\fR\|(7). +.SH "QUIC STREAMS" +.IX Header "QUIC STREAMS" +In a QUIC multi\-stream application we separate out the concepts of a QUIC +"connection" and a QUIC "stream". A connection object represents the overarching +details of the connection between a client and a server including all its +negotiated and configured parameters. We use the \fBSSL\fR object for that in an +OpenSSL application (known as the connection \fBSSL\fR object). It is created by an +application calling \fBSSL_new\fR\|(3). +.PP +Separately a connection can have zero or more streams associated with it +(although a connection with zero streams is probably not very useful, so +normally you would have at least one). A stream is used to send and receive +data between the two peers. Each stream is also represented by an \fBSSL\fR +object. A stream is logically independent of all the other streams associated +with the same connection. Data sent on a stream is guaranteed to be delivered +in the order that it was sent within that stream. The same is not true across +streams, e.g. if an application sends data on stream 1 first and then sends some +more data on stream 2 second, then the remote peer may receive the data sent on +stream 2 before it receives the data sent on stream 1. +.PP +Once the connection \fBSSL\fR object has completed its handshake (i.e. +\&\fBSSL_connect\fR\|(3) has returned 1), stream \fBSSL\fR objects are created by the +application calling \fBSSL_new_stream\fR\|(3) or \fBSSL_accept_stream\fR\|(3) (see +"CREATING NEW STREAMS" below). +.PP +The same threading rules apply to \fBSSL\fR objects as for most OpenSSL objects +(see \fBossl\-guide\-libraries\-introduction\fR\|(7)). In particular most OpenSSL +functions are thread safe, but the \fBSSL\fR object is not. This means that you can +use an \fBSSL\fR object representing one stream at the same time as another thread +is using a different \fBSSL\fR object for a different stream on the same +connection. But you cannot use the same \fBSSL\fR object on two different threads +at the same time (without additional application level locking). +.SH "THE DEFAULT STREAM" +.IX Header "THE DEFAULT STREAM" +A connection \fBSSL\fR object may also (optionally) be associated with a stream. +This stream is known as the default stream. The default stream is automatically +created and associated with the \fBSSL\fR object when the application calls +\&\fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3), \fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) and +passes the connection \fBSSL\fR object as a parameter. +.PP +If a client application calls \fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) first then +(by default) the default stream will be a client\-initiated bi\-directional +stream. If a client application calls \fBSSL_read_ex\fR\|(3) or \fBSSL_read\fR\|(3) +first then the first stream initiated by the server will be used as the default +stream (whether it is bi\-directional or uni\-directional). +.PP +This behaviour can be controlled via the default stream mode. See +\&\fBSSL_set_default_stream_mode\fR\|(3) for further details. +.PP +It is recommended that new multi\-stream applications should not use a default +stream at all and instead should use a separate stream \fBSSL\fR object for each +stream that is used. This requires calling \fBSSL_set_default_stream_mode\fR\|(3) +and setting the mode to \fBSSL_DEFAULT_STREAM_MODE_NONE\fR. +.SH "CREATING NEW STREAMS" +.IX Header "CREATING NEW STREAMS" +An endpoint can create a new stream by calling \fBSSL_new_stream\fR\|(3). This +creates a locally initiated stream. In order to do so you must pass the QUIC +connection \fBSSL\fR object as a parameter. You can also specify whether you want a +bi\-directional or a uni\-directional stream. +.PP +The function returns a new QUIC stream \fBSSL\fR object for sending and receiving +data on that stream. +.PP +The peer may also initiate streams. An application can use the function +\&\fBSSL_get_accept_stream_queue_len\fR\|(3) to determine the number of streams that +the peer has initiated that are waiting for the application to handle. An +application can call \fBSSL_accept_stream\fR\|(3) to create a new \fBSSL\fR object for +a remotely initiated stream. If the peer has not initiated any then this call +will block until one is available if the connection object is in blocking mode +(see \fBSSL_set_blocking_mode\fR\|(3)). +.PP +When using a default stream OpenSSL will prevent new streams from being +accepted. To override this behaviour you must call +\&\fBSSL_set_incoming_stream_policy\fR\|(3) to set the policy to +\&\fBSSL_INCOMING_STREAM_POLICY_ACCEPT\fR. See the man page for further details. This +is not relevant if the default stream has been disabled as described in +"THE DEFAULT STREAM" above. +.PP +Any stream may be bi\-directional or uni\-directional. If it is uni\-directional +then the initiator can write to it but not read from it, and vice\-versa for the +peer. You can determine what type of stream an \fBSSL\fR object represents by +calling \fBSSL_get_stream_type\fR\|(3). See the man page for further details. +.SH "USING A STREAM TO SEND AND RECEIVE DATA" +.IX Header "USING A STREAM TO SEND AND RECEIVE DATA" +Once you have a stream \fBSSL\fR object (which includes the connection \fBSSL\fR +object if a default stream is in use) then you can send and receive data over it +using the \fBSSL_write_ex\fR\|(3), \fBSSL_write\fR\|(3), \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_read\fR\|(3) functions. See the man pages for further details. +.PP +In the event of one of these functions not returning a success code then +you should call \fBSSL_get_error\fR\|(3) to find out further details about the error. +In blocking mode this will either be a fatal error (e.g. \fBSSL_ERROR_SYSCALL\fR +or \fBSSL_ERROR_SSL\fR), or it will be \fBSSL_ERROR_ZERO_RETURN\fR which can occur +when attempting to read data from a stream and the peer has indicated that the +stream is concluded (i.e. "FIN" has been signalled on the stream). This means +that the peer will send no more data on that stream. Note that the +interpretation of \fBSSL_ERROR_ZERO_RETURN\fR is slightly different for a QUIC +application compared to a TLS application. In TLS it occurs when the connection +has been shutdown by the peer. In QUIC this only tells you that the current +stream has been concluded by the peer. It tells you nothing about the underlying +connection. If the peer has concluded the stream then no more data will be +received on it, however an application can still send data to the peer until +the send side of the stream has also been concluded. This can happen by the +application calling \fBSSL_stream_conclude\fR\|(3). It is an error to attempt to +send more data on a stream after \fBSSL_stream_conclude\fR\|(3) has been called. +.PP +It is also possible to abandon a stream abnormally by calling +\&\fBSSL_stream_reset\fR\|(3). +.PP +Once a stream object is no longer needed it should be freed via a call to +\&\fBSSL_free\fR\|(3). An application should not call \fBSSL_shutdown\fR\|(3) on it since +this is only meaningful for connection level \fBSSL\fR objects. Freeing the stream +will automatically signal STOP_SENDING to the peer. +.SH "STREAMS AND CONNECTIONS" +.IX Header "STREAMS AND CONNECTIONS" +Given a stream object it is possible to get the \fBSSL\fR object corresponding to +the connection via a call to \fBSSL_get0_connection\fR\|(3). Multi\-threaded +restrictions apply so care should be taken when using the returned connection +object. Specifically, if you are handling each of your stream objects in a +different thread and call \fBSSL_get0_connection\fR\|(3) from within that thread then +you must be careful to not to call any function that uses the connection object +at the same time as one of the other threads is also using that connection +object (with the exception of \fBSSL_accept_stream\fR\|(3) and +\&\fBSSL_get_accept_stream_queue_len\fR\|(3) which are thread\-safe). +.PP +A stream object does not inherit all its settings and values from its parent +\&\fBSSL\fR connection object. Therefore certain function calls that are relevant to +the connection as a whole will not work on a stream. For example the function +\&\fBSSL_get_certificate\fR\|(3) can be used to obtain a handle on the peer certificate +when called with a connection \fBSSL\fR object. When called with a stream \fBSSL\fR +object it will return NULL. +.SH "SIMPLE MULTI\-STREAM QUIC CLIENT EXAMPLE" +.IX Header "SIMPLE MULTI-STREAM QUIC CLIENT EXAMPLE" +This section will present various source code samples demonstrating how to write +a simple multi\-stream QUIC client application which connects to a server, send +some HTTP/1.0 requests to it, and read back the responses. Note that HTTP/1.0 +over QUIC is non\-standard and will not be supported by real world servers. This +is for demonstration purposes only. +.PP +We will build on the example code for the simple blocking QUIC client that is +covered on the \fBossl\-guide\-quic\-client\-block\fR\|(7) page and we assume that you +are familiar with it. We will only describe the differences between the simple +blocking QUIC client and the multi\-stream QUIC client. Although the example code +uses blocking \fBSSL\fR objects, you can equally use nonblocking \fBSSL\fR objects. +See \fBossl\-guide\-quic\-client\-non\-block\fR\|(7) for more information about writing a +nonblocking QUIC client. +.PP +The complete source code for this example multi\-stream QUIC client is available +in the \f(CW\*(C`demos/guide\*(C'\fR directory of the OpenSSL source distribution in the file +\&\f(CW\*(C`quic\-multi\-stream.c\*(C'\fR. It is also available online at +. +.SS "Disabling the default stream" +.IX Subsection "Disabling the default stream" +As discussed above in "THE DEFAULT STREAM" we will follow the recommendation +to disable the default stream for our multi\-stream client. To do this we call +the \fBSSL_set_default_stream_mode\fR\|(3) function and pass in our connection \fBSSL\fR +object and the value \fBSSL_DEFAULT_STREAM_MODE_NONE\fR. +.PP +.Vb 8 +\& /* +\& * We will use multiple streams so we will disable the default stream mode. +\& * This is not a requirement for using multiple streams but is recommended. +\& */ +\& if (!SSL_set_default_stream_mode(ssl, SSL_DEFAULT_STREAM_MODE_NONE)) { +\& printf("Failed to disable the default stream mode\en"); +\& goto end; +\& } +.Ve +.SS "Creating the request streams" +.IX Subsection "Creating the request streams" +For the purposes of this example we will create two different streams to send +two different HTTP requests to the server. For the purposes of demonstration the +first of these will be a bi\-directional stream and the second one will be a +uni\-directional one: +.PP +.Vb 10 +\& /* +\& * We create two new client initiated streams. The first will be +\& * bi\-directional, and the second will be uni\-directional. +\& */ +\& stream1 = SSL_new_stream(ssl, 0); +\& stream2 = SSL_new_stream(ssl, SSL_STREAM_FLAG_UNI); +\& if (stream1 == NULL || stream2 == NULL) { +\& printf("Failed to create streams\en"); +\& goto end; +\& } +.Ve +.SS "Writing data to the streams" +.IX Subsection "Writing data to the streams" +Once the streams are successfully created we can start writing data to them. In +this example we will be sending a different HTTP request on each stream. To +avoid repeating too much code we write a simple helper function to send an HTTP +request to a stream: +.PP +.Vb 5 +\& int write_a_request(SSL *stream, const char *request_start, +\& const char *hostname) +\& { +\& const char *request_end = "\er\en\er\en"; +\& size_t written; +\& +\& if (!SSL_write_ex(stream, request_start, strlen(request_start), &written)) +\& return 0; +\& if (!SSL_write_ex(stream, hostname, strlen(hostname), &written)) +\& return 0; +\& if (!SSL_write_ex(stream, request_end, strlen(request_end), &written)) +\& return 0; +\& +\& return 1; +\& } +.Ve +.PP +We assume the strings \fBrequest1_start\fR and \fBrequest2_start\fR hold the +appropriate HTTP requests. We can then call our helper function above to send +the requests on the two streams. For the sake of simplicity this example does +this sequentially, writing to \fBstream1\fR first and, when this is successful, +writing to \fBstream2\fR second. Remember that our client is blocking so these +calls will only return once they have been successfully completed. A real +application would not need to do these writes sequentially or in any particular +order. For example we could start two threads (one for each stream) and write +the requests to each stream simultaneously. +.PP +.Vb 5 +\& /* Write an HTTP GET request on each of our streams to the peer */ +\& if (!write_a_request(stream1, request1_start, hostname)) { +\& printf("Failed to write HTTP request on stream 1\en"); +\& goto end; +\& } +\& +\& if (!write_a_request(stream2, request2_start, hostname)) { +\& printf("Failed to write HTTP request on stream 2\en"); +\& goto end; +\& } +.Ve +.SS "Reading data from a stream" +.IX Subsection "Reading data from a stream" +In this example \fBstream1\fR is a bi\-directional stream so, once we have sent the +request on it, we can attempt to read the response from the server back. Here +we just repeatedly call \fBSSL_read_ex\fR\|(3) until that function fails (indicating +either that there has been a problem, or that the peer has signalled the stream +as concluded). +.PP +.Vb 10 +\& printf("Stream 1 data:\en"); +\& /* +\& * Get up to sizeof(buf) bytes of the response from stream 1 (which is a +\& * bidirectional stream). We keep reading until the server closes the +\& * connection. +\& */ +\& while (SSL_read_ex(stream1, buf, sizeof(buf), &readbytes)) { +\& /* +\& * OpenSSL does not guarantee that the returned data is a string or +\& * that it is NUL terminated so we use fwrite() to write the exact +\& * number of bytes that we read. The data could be non\-printable or +\& * have NUL characters in the middle of it. For this simple example +\& * we\*(Aqre going to print it to stdout anyway. +\& */ +\& fwrite(buf, 1, readbytes, stdout); +\& } +\& /* In case the response didn\*(Aqt finish with a newline we add one now */ +\& printf("\en"); +.Ve +.PP +In a blocking application like this one calls to \fBSSL_read_ex\fR\|(3) will either +succeed immediately returning data that is already available, or they will block +waiting for more data to become available and return it when it is, or they will +fail with a 0 response code. +.PP +Once we exit the while loop above we know that the last call to +\&\fBSSL_read_ex\fR\|(3) gave a 0 response code so we call the \fBSSL_get_error\fR\|(3) +function to find out more details. Since this is a blocking application this +will either return \fBSSL_ERROR_SYSCALL\fR or \fBSSL_ERROR_SSL\fR indicating a +fundamental problem, or it will return \fBSSL_ERROR_ZERO_RETURN\fR indicating that +the stream is concluded and there will be no more data available to read from +it. Care must be taken to distinguish between an error at the stream level (i.e. +a stream reset) and an error at the connection level (i.e. a connection closed). +The \fBSSL_get_stream_read_state\fR\|(3) function can be used to distinguish between +these different cases. +.PP +.Vb 12 +\& /* +\& * Check whether we finished the while loop above normally or as the +\& * result of an error. The 0 argument to SSL_get_error() is the return +\& * code we received from the SSL_read_ex() call. It must be 0 in order +\& * to get here. Normal completion is indicated by SSL_ERROR_ZERO_RETURN. In +\& * QUIC terms this means that the peer has sent FIN on the stream to +\& * indicate that no further data will be sent. +\& */ +\& switch (SSL_get_error(stream1, 0)) { +\& case SSL_ERROR_ZERO_RETURN: +\& /* Normal completion of the stream */ +\& break; +\& +\& case SSL_ERROR_SSL: +\& /* +\& * Some stream fatal error occurred. This could be because of a stream +\& * reset \- or some failure occurred on the underlying connection. +\& */ +\& switch (SSL_get_stream_read_state(stream1)) { +\& case SSL_STREAM_STATE_RESET_REMOTE: +\& printf("Stream reset occurred\en"); +\& /* The stream has been reset but the connection is still healthy. */ +\& break; +\& +\& case SSL_STREAM_STATE_CONN_CLOSED: +\& printf("Connection closed\en"); +\& /* Connection is already closed. Skip SSL_shutdown() */ +\& goto end; +\& +\& default: +\& printf("Unknown stream failure\en"); +\& break; +\& } +\& break; +\& +\& default: +\& /* Some other unexpected error occurred */ +\& printf ("Failed reading remaining data\en"); +\& break; +\& } +.Ve +.SS "Accepting an incoming stream" +.IX Subsection "Accepting an incoming stream" +Our \fBstream2\fR object that we created above was a uni\-directional stream so it +cannot be used to receive data from the server. In this hypothetical example +we assume that the server initiates a new stream to send us back the data that +we requested. To do that we call \fBSSL_accept_stream\fR\|(3). Since this is a +blocking application this will wait indefinitely until the new stream has +arrived and is available for us to accept. In the event of an error it will +return \fBNULL\fR. +.PP +.Vb 10 +\& /* +\& * In our hypothetical HTTP/1.0 over QUIC protocol that we are using we +\& * assume that the server will respond with a server initiated stream +\& * containing the data requested in our uni\-directional stream. This doesn\*(Aqt +\& * really make sense to do in a real protocol, but its just for +\& * demonstration purposes. +\& * +\& * We\*(Aqre using blocking mode so this will block until a stream becomes +\& * available. We could override this behaviour if we wanted to by setting +\& * the SSL_ACCEPT_STREAM_NO_BLOCK flag in the second argument below. +\& */ +\& stream3 = SSL_accept_stream(ssl, 0); +\& if (stream3 == NULL) { +\& printf("Failed to accept a new stream\en"); +\& goto end; +\& } +.Ve +.PP +We can now read data from the stream in the same way that we did for \fBstream1\fR +above. We won\*(Aqt repeat that here. +.SS "Cleaning up the streams" +.IX Subsection "Cleaning up the streams" +Once we have finished using our streams we can simply free them by calling +\&\fBSSL_free\fR\|(3). Optionally we could call \fBSSL_stream_conclude\fR\|(3) on them if +we want to indicate to the peer that we won\*(Aqt be sending them any more data, but +we don\*(Aqt do that in this example because we assume that the HTTP application +protocol supplies sufficient information for the peer to know when we have +finished sending request data. +.PP +We should not call \fBSSL_shutdown\fR\|(3) or \fBSSL_shutdown_ex\fR\|(3) on the stream +objects since those calls should not be used for streams. +.PP +.Vb 3 +\& SSL_free(stream1); +\& SSL_free(stream2); +\& SSL_free(stream3); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7) \fBossl\-guide\-quic\-introduction\fR\|(7), +\&\fBossl\-guide\-quic\-client\-block\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-quic-server-block.7 b/static/netbsd/man7/ossl-guide-quic-server-block.7 new file mode 100644 index 00000000..9afa83c7 --- /dev/null +++ b/static/netbsd/man7/ossl-guide-quic-server-block.7 @@ -0,0 +1,360 @@ +.\" $NetBSD: ossl-guide-quic-server-block.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-QUIC-SERVER-BLOCK 7" +.TH OSSL-GUIDE-QUIC-SERVER-BLOCK 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-quic\-server\-block +\&\- OpenSSL Guide: Writing a simple blocking QUIC server +.SH "SIMPLE BLOCKING QUIC SERVER EXAMPLE" +.IX Header "SIMPLE BLOCKING QUIC SERVER EXAMPLE" +This page will present various source code samples demonstrating how to write a +simple, non\-concurrent, QUIC "echo" server application which accepts one client +connection at a time, echoing input from the client back to the same client. +Once the current client disconnects, the next client connection is accepted. +.PP +The server only accepts HTTP/1.0 requests, which is non\-standard and will not +be supported by real world servers. This is for demonstration purposes only. +.PP +Both the accepting socket and client connections are "blocking". A more typical +server might use nonblocking sockets with an event loop and callbacks for I/O +events. +.PP +The complete source code for this example blocking QUIC server is available in +the \fBdemos/guide\fR directory of the OpenSSL source distribution in the file +\&\fBquic\-server\-block.c\fR. It is also available online at +. +.PP +We assume that you already have OpenSSL installed on your system; that you +already have some fundamental understanding of OpenSSL concepts and QUIC (see +\&\fBossl\-guide\-libraries\-introduction\fR\|(7) and \fBossl\-guide\-quic\-introduction\fR\|(7)); +and that you know how to write and build C code and link it against the +libcrypto and libssl libraries that are provided by OpenSSL. It also assumes +that you have a basic understanding of UDP/IP and sockets. +.SS "Creating the SSL_CTX and SSL objects" +.IX Subsection "Creating the SSL_CTX and SSL objects" +The first step is to create an \fBSSL_CTX\fR object for our server. We use the +\&\fBSSL_CTX_new\fR\|(3) function for this purpose. We pass as an argument the return +value of the function \fBOSSL_QUIC_server_method\fR\|(3). You should use this method +whenever you are writing a QUIC server. +.PP +.Vb 8 +\& /* +\& * An SSL_CTX holds shared configuration information for multiple +\& * subsequent per\-client SSL connections. We specifically load a QUIC +\& * server method here. +\& */ +\& ctx = SSL_CTX_new(OSSL_QUIC_server_method()); +\& if (ctx == NULL) +\& goto err; +.Ve +.PP +Servers need a private key and certificate. Intermediate issuer CA +certificates are often required, and both the server (end\-entity or EE) +certificate and the issuer ("chain") certificates are most easily configured in +a single "chain file". Below we load such a chain file (the EE certificate +must appear first), and then load the corresponding private key, checking that +it matches the server certificate. No checks are performed to check the +integrity of the chain (CA signatures or certificate expiration dates, for +example), but we do verify the consistency of the private key with the +corresponding certificate. +.PP +.Vb 10 +\& /* +\& * Load the server\*(Aqs certificate *chain* file (PEM format), which includes +\& * not only the leaf (end\-entity) server certificate, but also any +\& * intermediate issuer\-CA certificates. The leaf certificate must be the +\& * first certificate in the file. +\& * +\& * In advanced use\-cases this can be called multiple times, once per public +\& * key algorithm for which the server has a corresponding certificate. +\& * However, the corresponding private key (see below) must be loaded first, +\& * *before* moving on to the next chain file. +\& */ +\& if (SSL_CTX_use_certificate_chain_file(ctx, cert_path) <= 0) { +\& fprintf(stderr, "couldn\*(Aqt load certificate file: %s\en", cert_path); +\& goto err; +\& } +\& +\& /* +\& * Load the corresponding private key, this also checks that the private +\& * key matches the just loaded end\-entity certificate. It does not check +\& * whether the certificate chain is valid, the certificates could be +\& * expired, or may otherwise fail to form a chain that a client can +\& * validate. +\& */ +\& if (SSL_CTX_use_PrivateKey_file(ctx, key_path, SSL_FILETYPE_PEM) <= 0) { +\& fprintf(stderr, "couldn\*(Aqt load key file: %s\en", key_path); +\& goto err; +\& } +.Ve +.PP +Most servers, including this one, do not solicit client certificates. We +therefore do not need a "trust store" and allow the handshake to complete even +when the client does not present a certificate. Note: Even if a client did +present a trusted certificate, for it to be useful, the server application +would still need custom code to use the verified identity to grant nondefault +access to that particular client. Some servers grant access to all clients +with certificates from a private CA, this then requires processing of +certificate revocation lists to deauthorise a client. It is often simpler and +more secure to instead keep a list of authorised public keys. +.PP +Though this is the default setting, we explicitly call the +\&\fBSSL_CTX_set_verify\fR\|(3) function and pass the \fBSSL_VERIFY_NONE\fR value to it. +The final argument to this function is a callback that you can optionally +supply to override the default handling for certificate verification. Most +applications do not need to do this so this can safely be set to NULL to get +the default handling. +.PP +.Vb 12 +\& /* +\& * Clients rarely employ certificate\-based authentication, and so we don\*(Aqt +\& * require "mutual" TLS authentication (indeed there\*(Aqs no way to know +\& * whether or how the client authenticated the server, so the term "mutual" +\& * is potentially misleading). +\& * +\& * Since we\*(Aqre not soliciting or processing client certificates, we don\*(Aqt +\& * need to configure a trusted\-certificate store, so no call to +\& * SSL_CTX_set_default_verify_paths() is needed. The server\*(Aqs own +\& * certificate chain is assumed valid. +\& */ +\& SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, NULL); +.Ve +.PP +QUIC also dictates using Application\-Layer Protocol Negotiation (ALPN) to select +an application protocol. We use \fBSSL_CTX_set_alpn_select_cb\fR\|(3) for this +purpose. We can pass a callback which will be called for each connection to +select an ALPN the server considers acceptable. +.PP +.Vb 2 +\& /* Setup ALPN negotiation callback to decide which ALPN is accepted. */ +\& SSL_CTX_set_alpn_select_cb(ctx, select_alpn, NULL); +.Ve +.PP +In this case, we only accept "http/1.0" and "hq\-interop". +.PP +.Vb 8 +\& /* +\& * ALPN strings for TLS handshake. Only \*(Aqhttp/1.0\*(Aq and \*(Aqhq\-interop\*(Aq +\& * are accepted. +\& */ +\& static const unsigned char alpn_ossltest[] = { +\& 8, \*(Aqh\*(Aq, \*(Aqt\*(Aq, \*(Aqt\*(Aq, \*(Aqp\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq, \*(Aq.\*(Aq, \*(Aq0\*(Aq, +\& 10, \*(Aqh\*(Aq, \*(Aqq\*(Aq, \*(Aq\-\*(Aq, \*(Aqi\*(Aq, \*(Aqn\*(Aq, \*(Aqt\*(Aq, \*(Aqe\*(Aq, \*(Aqr\*(Aq, \*(Aqo\*(Aq, \*(Aqp\*(Aq, +\& }; +\& +\& static int select_alpn(SSL *ssl, const unsigned char **out, +\& unsigned char *out_len, const unsigned char *in, +\& unsigned int in_len, void *arg) +\& { +\& if (SSL_select_next_proto((unsigned char **)out, out_len, alpn_ossltest, +\& sizeof(alpn_ossltest), in, +\& in_len) == OPENSSL_NPN_NEGOTIATED) +\& return SSL_TLSEXT_ERR_OK; +\& return SSL_TLSEXT_ERR_ALERT_FATAL; +\& } +.Ve +.PP +That is all the setup that we need to do for the \fBSSL_CTX\fR. Next, we create a +UDP socket and bind to it on localhost. +.PP +.Vb 5 +\& /* Retrieve the file descriptor for a new UDP socket */ +\& if ((fd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP)) < 0) { +\& fprintf(stderr, "cannot create socket"); +\& goto err; +\& } +\& +\& sa.sin_family = AF_INET; +\& sa.sin_port = htons(port); +\& +\& /* Bind to the new UDP socket on localhost */ +\& if (bind(fd, (const struct sockaddr *)&sa, sizeof(sa)) < 0) { +\& fprintf(stderr, "cannot bind to %u\en", port); +\& BIO_closesocket(fd); +\& goto err; +\& } +.Ve +.PP +To run the QUIC server, we create an \fBSSL_LISTENER\fR to listen for incoming +connections. We provide it with the bound UDP port to then explicitly begin +listening for new connections. +.PP +.Vb 8 +\& /* +\& * Create a new QUIC listener. Listeners, and other QUIC objects, default +\& * to operating in blocking mode. The configured behaviour is inherited by +\& * child objects. +\& */ +\& if ((listener = SSL_new_listener(ctx, 0)) == NULL) { +\& goto err; +\& } +\& +\& /* Provide the listener with our UDP socket. */ +\& if (!SSL_set_fd(listener, fd)) +\& goto err; +\& +\& /* Begin listening. */ +\& if (!SSL_listen(listener)) +\& goto err; +.Ve +.SS "Server loop" +.IX Subsection "Server loop" +The server now enters a "forever" loop, handling one client connection at a +time. Before each connection, we clear the OpenSSL error stack so that any +error reports are related to just the new connection. +.PP +.Vb 2 +\& /* Pristine error stack for each new connection */ +\& ERR_clear_error(); +.Ve +.PP +At this point, the server blocks to accept the next client. +\&\fBSSL_accept_connection\fR\|(3) will return an accepted connection within a fresh +SSL, in which the handshake will have already occurred. +.PP +.Vb 6 +\& /* Block while waiting for a client connection */ +\& conn = SSL_accept_connection(listener, 0); +\& if (conn == NULL) { +\& fprintf(stderr, "error while accepting connection\en"); +\& goto err; +\& } +.Ve +.PP +With the handshake complete, the server echoes client input back to the client +in a loop. +.PP +.Vb 8 +\& while (SSL_read_ex(conn, buf, sizeof(buf), &nread) > 0) { +\& if (SSL_write_ex(conn, buf, nread, &nwritten) > 0 && +\& nwritten == nread) { +\& continue; +\& } +\& fprintf(stderr, "Error echoing client input"); +\& break; +\& } +.Ve +.PP +Once the client closes its connection, we signal the end of the stream by using +\&\fBSSL_stream_conclude\fR\|(3). This will send a final Finished packet to the +client. +.PP +.Vb 6 +\& /* Signal the end of the stream. */ +\& if (SSL_stream_conclude(conn, 0) != 1) { +\& fprintf(stderr, "Unable to conclude stream\en"); +\& SSL_free(conn); +\& goto err; +\& } +.Ve +.PP +We then shut down the connection with \fBSSL_shutdown_ex\fR\|(3), which may need +to be called multiple times to ensure the connection is shutdown completely. +.PP +.Vb 4 +\& while (SSL_shutdown_ex(conn, 0, &shutdown_args, +\& sizeof(SSL_SHUTDOWN_EX_ARGS)) != 1) { +\& fprintf(stderr, "Re\-attempting SSL shutdown\en"); +\& } +.Ve +.PP +Finally, we free the SSL connection, and the server is now ready to accept the +next client connection. +.PP +.Vb 1 +\& SSL_free(conn); +.Ve +.SS "Final clean up" +.IX Subsection "Final clean up" +If the server somehow manages to break out of the infinite loop and +be ready to exit, it would deallocate the constructed \fBSSL\fR. +.PP +.Vb 1 +\& SSL_free(listener); +.Ve +.PP +And in the main function, it would deallocate the constructed \fBSSL_CTX\fR. +.PP +.Vb 4 +\& SSL_CTX_free(ctx); +\& BIO_closesocket(fd); +\& res = EXIT_SUCCESS; +\& return res; +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-quic\-introduction\fR\|(7), +\&\fBossl\-guide\-quic\-client\-non\-block\fR\|(7), \fBossl\-guide\-quic\-client\-block\fR\|(7), +\&\fBossl\-guide\-tls\-server\-block\fR\|(7), \fBossl\-guide\-quic\-server\-non\-block\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-quic-server-non-block.7 b/static/netbsd/man7/ossl-guide-quic-server-non-block.7 new file mode 100644 index 00000000..28364c22 --- /dev/null +++ b/static/netbsd/man7/ossl-guide-quic-server-non-block.7 @@ -0,0 +1,452 @@ +.\" $NetBSD: ossl-guide-quic-server-non-block.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-QUIC-SERVER-NON-BLOCK 7" +.TH OSSL-GUIDE-QUIC-SERVER-NON-BLOCK 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-quic\-server\-non\-block +\&\- OpenSSL Guide: Writing a simple nonblocking QUIC server +.SH "SIMPLE NONBLOCKING QUIC SERVER EXAMPLE" +.IX Header "SIMPLE NONBLOCKING QUIC SERVER EXAMPLE" +This page presents various source code samples demonstrating how to write a +simple, non\-concurrent, QUIC "echo" server application which accepts one client +connection at a time, echoing input from the client back to the same client. +Once the current client disconnects, the next client connection is accepted. +.PP +The server only accepts \f(CW\*(C`http/1.0\*(C'\fR and \f(CW\*(C`hq\-interop\*(C'\fR ALPN\*(Aqs and doesn\*(Aqt actually +implement HTTP but only does a simple echo. This is non\-standard and will not +be supported by real world servers. This is for demonstration purposes only. +.PP +There are various methods to test this server: \fBquic\-client\-block.c\fR and +\&\fBquic\-client\-non\-block.c\fR will send a basic HTTP/1.0 request, which the server +will echo back. You can also test this server by running +\&\f(CW\*(C`openssl s_client \-connect localhost:4443 \-4 \-quic \-alpn http/1.0\*(C'\fR and entering +text that will be echoed back by the server. +.PP +Both the listening socket and connected socket are "nonblocking". However, +we use \fBselect()\fR to make the listening socket block when it cannot read/write. +Rather than stopping and waiting, your application may need to go and do other +tasks whilst the \fBSSL\fR object is unable to read/write. For example: updating a +GUI or performing operations on some other connection or stream. +.PP +The complete source code for this example nonblocking QUIC server is available +in the \fBdemos/guide\fR directory of the OpenSSL source distribution in the file +\&\fBquic\-server\-non\-block.c\fR. It is also available online at +. +.PP +We assume that you already have OpenSSL installed on your system; that you +already have some fundamental understanding of OpenSSL concepts and QUIC (see +\&\fBossl\-guide\-libraries\-introduction\fR\|(7) and \fBossl\-guide\-quic\-introduction\fR\|(7)); +and that you know how to write and build C code and link it against the +libcrypto and libssl libraries that are provided by OpenSSL. It also assumes +that you have a basic understanding of UDP/IP and sockets. +.SS "Creating the SSL_CTX and SSL objects" +.IX Subsection "Creating the SSL_CTX and SSL objects" +The first step is to create an \fBSSL_CTX\fR object for our server. We use the +\&\fBSSL_CTX_new\fR\|(3) function for this purpose. We pass as an argument the return +value of the function \fBOSSL_QUIC_server_method\fR\|(3). You should use this method +whenever you are writing a QUIC server. +.PP +.Vb 8 +\& /* +\& * An SSL_CTX holds shared configuration information for multiple +\& * subsequent per\-client SSL connections. We specifically load a QUIC +\& * server method here. +\& */ +\& ctx = SSL_CTX_new(OSSL_QUIC_server_method()); +\& if (ctx == NULL) +\& goto err; +.Ve +.PP +Servers need a private key and certificate. Intermediate issuer CA +certificates are often required, and both the server (end\-entity or EE) +certificate and the issuer ("chain") certificates are most easily configured in +a single "chain file". Below we load such a chain file (the EE certificate +must appear first), and then load the corresponding private key, checking that +it matches the server certificate. No checks are performed to check the +integrity of the chain (CA signatures or certificate expiration dates, for +example), but we do verify the consistency of the private key with the +corresponding certificate. +.PP +.Vb 10 +\& /* +\& * Load the server\*(Aqs certificate *chain* file (PEM format), which includes +\& * not only the leaf (end\-entity) server certificate, but also any +\& * intermediate issuer\-CA certificates. The leaf certificate must be the +\& * first certificate in the file. +\& * +\& * In advanced use\-cases this can be called multiple times, once per public +\& * key algorithm for which the server has a corresponding certificate. +\& * However, the corresponding private key (see below) must be loaded first, +\& * *before* moving on to the next chain file. +\& */ +\& if (SSL_CTX_use_certificate_chain_file(ctx, cert_path) <= 0) { +\& fprintf(stderr, "couldn\*(Aqt load certificate file: %s\en", cert_path); +\& goto err; +\& } +\& +\& /* +\& * Load the corresponding private key, this also checks that the private +\& * key matches the just loaded end\-entity certificate. It does not check +\& * whether the certificate chain is valid, the certificates could be +\& * expired, or may otherwise fail to form a chain that a client can +\& * validate. +\& */ +\& if (SSL_CTX_use_PrivateKey_file(ctx, key_path, SSL_FILETYPE_PEM) <= 0) { +\& fprintf(stderr, "couldn\*(Aqt load key file: %s\en", key_path); +\& goto err; +\& } +.Ve +.PP +Most servers, including this one, do not solicit client certificates. We +therefore do not need a "trust store" and allow the handshake to complete even +when the client does not present a certificate. Note: Even if a client did +present a trusted certificate, for it to be useful, the server application +would still need custom code to use the verified identity to grant nondefault +access to that particular client. Some servers grant access to all clients +with certificates from a private CA, this then requires processing of +certificate revocation lists to deauthorise a client. It is often simpler and +more secure to instead keep a list of authorised public keys. +.PP +Though this is the default setting, we explicitly call the +\&\fBSSL_CTX_set_verify\fR\|(3) function and pass the \fBSSL_VERIFY_NONE\fR value to it. +The final argument to this function is a callback that you can optionally +supply to override the default handling for certificate verification. Most +applications do not need to do this so this can safely be set to NULL to get +the default handling. +.PP +.Vb 12 +\& /* +\& * Clients rarely employ certificate\-based authentication, and so we don\*(Aqt +\& * require "mutual" TLS authentication (indeed there\*(Aqs no way to know +\& * whether or how the client authenticated the server, so the term "mutual" +\& * is potentially misleading). +\& * +\& * Since we\*(Aqre not soliciting or processing client certificates, we don\*(Aqt +\& * need to configure a trusted\-certificate store, so no call to +\& * SSL_CTX_set_default_verify_paths() is needed. The server\*(Aqs own +\& * certificate chain is assumed valid. +\& */ +\& SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, NULL); +.Ve +.PP +QUIC also dictates using Application\-Layer Protocol Negotiation (ALPN) to select +an application protocol. We use \fBSSL_CTX_set_alpn_select_cb\fR\|(3) for this +purpose. We can pass a callback which will be called for each connection to +select an ALPN the server considers acceptable. +.PP +.Vb 2 +\& /* Setup ALPN negotiation callback to decide which ALPN is accepted. */ +\& SSL_CTX_set_alpn_select_cb(ctx, select_alpn, NULL); +.Ve +.PP +In this case, we only accept "http/1.0" and "hq\-interop". +.PP +.Vb 8 +\& /* +\& * ALPN strings for TLS handshake. Only \*(Aqhttp/1.0\*(Aq and \*(Aqhq\-interop\*(Aq +\& * are accepted. +\& */ +\& static const unsigned char alpn_ossltest[] = { +\& 8, \*(Aqh\*(Aq, \*(Aqt\*(Aq, \*(Aqt\*(Aq, \*(Aqp\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq, \*(Aq.\*(Aq, \*(Aq0\*(Aq, +\& 10, \*(Aqh\*(Aq, \*(Aqq\*(Aq, \*(Aq\-\*(Aq, \*(Aqi\*(Aq, \*(Aqn\*(Aq, \*(Aqt\*(Aq, \*(Aqe\*(Aq, \*(Aqr\*(Aq, \*(Aqo\*(Aq, \*(Aqp\*(Aq, +\& }; +\& +\& static int select_alpn(SSL *ssl, const unsigned char **out, +\& unsigned char *out_len, const unsigned char *in, +\& unsigned int in_len, void *arg) +\& { +\& if (SSL_select_next_proto((unsigned char **)out, out_len, alpn_ossltest, +\& sizeof(alpn_ossltest), in, +\& in_len) == OPENSSL_NPN_NEGOTIATED) +\& return SSL_TLSEXT_ERR_OK; +\& return SSL_TLSEXT_ERR_ALERT_FATAL; +\& } +.Ve +.PP +That is all the setup that we need to do for the \fBSSL_CTX\fR. Next, we create a +UDP socket and bind to it on localhost. +.PP +.Vb 5 +\& /* Retrieve the file descriptor for a new UDP socket */ +\& if ((fd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP)) < 0) { +\& fprintf(stderr, "cannot create socket"); +\& return \-1; +\& } +\& +\& sa.sin_family = AF_INET; +\& sa.sin_port = htons(port); +\& +\& /* Bind to the new UDP socket on localhost */ +\& if (bind(fd, (const struct sockaddr *)&sa, sizeof(sa)) < 0) { +\& fprintf(stderr, "cannot bind to %u\en", port); +\& BIO_closesocket(fd); +\& return \-1; +\& } +\& +\& /* Set port to nonblocking mode */ +\& if (BIO_socket_nbio(fd, 1) <= 0) { +\& fprintf(stderr, "Unable to set port to nonblocking mode"); +\& BIO_closesocket(fd); +\& return \-1; +\& } +.Ve +.PP +To run the QUIC server, we create an \fBSSL_LISTENER\fR to listen for incoming +connections. We provide it with the bound UDP port to then explicitly begin +listening for new connections. +.PP +.Vb 3 +\& /* Create a new QUIC listener */ +\& if ((listener = SSL_new_listener(ctx, 0)) == NULL) +\& goto err; +\& +\& /* Provide the listener with our UDP socket. */ +\& if (!SSL_set_fd(listener, fd)) +\& goto err; +\& +\& /* Set the listener mode to nonblocking, which is inherited by +\& * child objects. +\& */ +\& if (!SSL_set_blocking_mode(listener, 0)) +\& goto err; +\& +\& /* +\& * Begin listening. Note that is not usually needed as SSL_accept_connection +\& * will implicitly start listening. It is only needed if a server wishes to +\& * ensure it has started to accept incoming connections but does not wish to +\& * actually call SSL_accept_connection yet. +\& */ +\& if (!SSL_listen(listener)) +\& goto err; +.Ve +.SS "Server loop" +.IX Subsection "Server loop" +The server now enters a "forever" loop, handling one client connection at a +time. Before each connection, we clear the OpenSSL error stack so that any +error reports are related to just the new connection. +.PP +.Vb 2 +\& /* Pristine error stack for each new connection */ +\& ERR_clear_error(); +.Ve +.PP +We then wait until a connection is ready for reading. +It uses the select function to wait until the socket is either readable +or writable, depending on what the SSL connection requires. +.PP +We then accept a new connection in which the handshake will have already +occurred. However, since we are in nonblocking mode, \fBSSL_accept_connection\fR\|(3) +will return immediately. Therefore, we use a helper function to essentially +block until a connection is established. +.PP +.Vb 5 +\& printf("Waiting for connection\en"); +\& while ((conn = SSL_accept_connection(listener, 0)) == NULL) { +\& wait_for_activity(listener); +\& } +\& printf("Accepted new connection\en"); +.Ve +.PP +The helper function wait_for_activity uses \fBselect()\fR to block until the file +descriptor belonging to the passed SSL object is readable. As mentioned earlier, +a more real\-world application would likely use this time to perform other tasks. +.PP +.Vb 3 +\& /* Initialize the fd_set structure */ +\& FD_ZERO(&read_fd); +\& FD_ZERO(&write_fd); +\& +\& /* +\& * Determine if we would like to write to the socket, read from it, or both. +\& */ +\& if (SSL_net_write_desired(ssl)) +\& FD_SET(sock, &write_fd); +\& if (SSL_net_read_desired(ssl)) +\& FD_SET(sock, &read_fd); +\& +\& /* +\& * Find out when OpenSSL would next like to be called, regardless of +\& * whether the state of the underlying socket has changed or not. +\& */ +\& if (SSL_get_event_timeout(ssl, &tv, &isinfinite) && !isinfinite) +\& tvp = &tv; +\& +\& /* +\& * Wait until the socket is writeable or readable. We use select here +\& * for the sake of simplicity and portability, but you could equally use +\& * poll/epoll or similar functions +\& * +\& * NOTE: For the purposes of this demonstration code this effectively +\& * makes this demo block until it has something more useful to do. In a +\& * real application you probably want to go and do other work here (e.g. +\& * update a GUI, or service other connections). +\& * +\& * Let\*(Aqs say for example that you want to update the progress counter on +\& * a GUI every 100ms. One way to do that would be to use the timeout in +\& * the last parameter to "select" below. If the tvp value is greater +\& * than 100ms then use 100ms instead. Then, when select returns, you +\& * check if it did so because of activity on the file descriptors or +\& * because of the timeout. If the 100ms GUI timeout has expired but the +\& * tvp timeout has not then go and update the GUI and then restart the +\& * "select" (with updated timeouts). +\& */ +\& +\& select(sock + 1, &read_fd, &write_fd, NULL, tvp); +.Ve +.PP +With the handshake complete, the server reads all the client input. +.PP +.Vb 10 +\& /* Read from client until the client sends a end of stream packet */ +\& while (!eof) { +\& ret = SSL_read_ex(conn, buf + total_read, sizeof(buf) \- total_read, +\& &nread); +\& total_read += nread; +\& if (total_read >= 8192) { +\& fprintf(stderr, "Could not fit all data into buffer\en"); +\& goto err; +\& } +\& switch (handle_io_failure(conn, ret)) { +\& case 1: +\& continue; /* Retry */ +\& case 0: +\& /* Reached end of stream */ +\& if (!SSL_has_pending(conn)) +\& eof = 1; +\& break; +\& default: +\& fprintf(stderr, "Failed reading remaining data\en"); +\& goto err; +\& } +\& } +.Ve +.PP +Finally, we echo the received data back to the client. We can use +\&\fBSSL_write_ex2\fR\|(3) to pass in a special flag SSL_WRITE_FLAG_CONCLUDE that will +send a FIN packet once the write has successfully finished writing all the data +to the peer. +.PP +.Vb 9 +\& /* Echo client input */ +\& while (!SSL_write_ex2(conn, buf, +\& total_read, +\& SSL_WRITE_FLAG_CONCLUDE, &total_written)) { +\& if (handle_io_failure(conn, 0) == 1) +\& continue; +\& fprintf(stderr, "Failed to write data\en"); +\& goto err; +\& } +.Ve +.PP +We then shut down the connection with \fBSSL_shutdown\fR\|(3), which may need +to be called multiple times to ensure the connection is shutdown completely. +.PP +.Vb 8 +\& /* +\& * Shut down the connection. We may need to call this multiple times +\& * to ensure the connection is shutdown completely. +\& */ +\& while ((ret = SSL_shutdown(conn)) != 1) { +\& if (ret < 0 && handle_io_failure(conn, ret) == 1) +\& continue; /* Retry */ +\& } +.Ve +.PP +Finally, we free the SSL connection, and the server is now ready to accept the +next client connection. +.PP +.Vb 1 +\& SSL_free(conn); +.Ve +.SS "Final clean up" +.IX Subsection "Final clean up" +If the server somehow manages to break out of the infinite loop and +be ready to exit, it would deallocate the constructed \fBSSL\fR. +.PP +.Vb 1 +\& SSL_free(listener); +.Ve +.PP +And in the main function, it would deallocate the constructed \fBSSL_CTX\fR. +.PP +.Vb 2 +\& SSL_CTX_free(ctx); +\& BIO_closesocket(fd); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-quic\-introduction\fR\|(7), +\&\fBossl\-guide\-quic\-client\-non\-block\fR\|(7), \fBossl\-guide\-quic\-client\-block\fR\|(7), +\&\fBossl\-guide\-tls\-server\-block\fR\|(7), \fBossl\-guide\-quic\-server\-block\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-tls-client-block.7 b/static/netbsd/man7/ossl-guide-tls-client-block.7 new file mode 100644 index 00000000..41108362 --- /dev/null +++ b/static/netbsd/man7/ossl-guide-tls-client-block.7 @@ -0,0 +1,657 @@ +.\" $NetBSD: ossl-guide-tls-client-block.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-TLS-CLIENT-BLOCK 7" +.TH OSSL-GUIDE-TLS-CLIENT-BLOCK 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-tls\-client\-block +\&\- OpenSSL Guide: Writing a simple blocking TLS client +.SH "SIMPLE BLOCKING TLS CLIENT EXAMPLE" +.IX Header "SIMPLE BLOCKING TLS CLIENT EXAMPLE" +This page will present various source code samples demonstrating how to write +a simple TLS client application which connects to a server, sends an HTTP/1.0 +request to it, and reads back the response. +.PP +We use a blocking socket for the purposes of this example. This means that +attempting to read data from a socket that has no data available on it to read +will block (and the function will not return), until data becomes available. +For example, this can happen if we have sent our request, but we are still +waiting for the server\*(Aqs response. Similarly any attempts to write to a socket +that is not able to write at the moment will block until writing is possible. +.PP +This blocking behaviour simplifies the implementation of a client because you do +not have to worry about what happens if data is not yet available. The +application will simply wait until it is available. +.PP +The complete source code for this example blocking TLS client is available in +the \fBdemos/guide\fR directory of the OpenSSL source distribution in the file +\&\fBtls\-client\-block.c\fR. It is also available online at +. +.PP +We assume that you already have OpenSSL installed on your system; that you +already have some fundamental understanding of OpenSSL concepts and TLS (see +\&\fBossl\-guide\-libraries\-introduction\fR\|(7) and \fBossl\-guide\-tls\-introduction\fR\|(7)); +and that you know how to write and build C code and link it against the +libcrypto and libssl libraries that are provided by OpenSSL. It also assumes +that you have a basic understanding of TCP/IP and sockets. +.SS "Creating the SSL_CTX and SSL objects" +.IX Subsection "Creating the SSL_CTX and SSL objects" +The first step is to create an \fBSSL_CTX\fR object for our client. We use the +\&\fBSSL_CTX_new\fR\|(3) function for this purpose. We could alternatively use +\&\fBSSL_CTX_new_ex\fR\|(3) if we want to associate the \fBSSL_CTX\fR with a particular +\&\fBOSSL_LIB_CTX\fR (see \fBossl\-guide\-libraries\-introduction\fR\|(7) to learn about +\&\fBOSSL_LIB_CTX\fR). We pass as an argument the return value of the function +\&\fBTLS_client_method\fR\|(3). You should use this method whenever you are writing a +TLS client. This method will automatically use TLS version negotiation to select +the highest version of the protocol that is mutually supported by both the +client and the server. +.PP +.Vb 10 +\& /* +\& * Create an SSL_CTX which we can use to create SSL objects from. We +\& * want an SSL_CTX for creating clients so we use TLS_client_method() +\& * here. +\& */ +\& ctx = SSL_CTX_new(TLS_client_method()); +\& if (ctx == NULL) { +\& printf("Failed to create the SSL_CTX\en"); +\& goto end; +\& } +.Ve +.PP +Since we are writing a client we must ensure that we verify the server\*(Aqs +certificate. We do this by calling the \fBSSL_CTX_set_verify\fR\|(3) function and +pass the \fBSSL_VERIFY_PEER\fR value to it. The final argument to this function +is a callback that you can optionally supply to override the default handling +for certificate verification. Most applications do not need to do this so this +can safely be set to NULL to get the default handling. +.PP +.Vb 6 +\& /* +\& * Configure the client to abort the handshake if certificate +\& * verification fails. Virtually all clients should do this unless you +\& * really know what you are doing. +\& */ +\& SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, NULL); +.Ve +.PP +In order for certificate verification to be successful you must have configured +where the trusted certificate store to be used is located (see +\&\fBossl\-guide\-tls\-introduction\fR\|(7)). In most cases you just want to use the +default store so we call \fBSSL_CTX_set_default_verify_paths\fR\|(3). +.PP +.Vb 5 +\& /* Use the default trusted certificate store */ +\& if (!SSL_CTX_set_default_verify_paths(ctx)) { +\& printf("Failed to set the default trusted certificate store\en"); +\& goto end; +\& } +.Ve +.PP +We would also like to restrict the TLS versions that we are willing to accept to +TLSv1.2 or above. TLS protocol versions earlier than that are generally to be +avoided where possible. We can do that using +\&\fBSSL_CTX_set_min_proto_version\fR\|(3): +.PP +.Vb 8 +\& /* +\& * TLSv1.1 or earlier are deprecated by IETF and are generally to be +\& * avoided if possible. We require a minimum TLS version of TLSv1.2. +\& */ +\& if (!SSL_CTX_set_min_proto_version(ctx, TLS1_2_VERSION)) { +\& printf("Failed to set the minimum TLS protocol version\en"); +\& goto end; +\& } +.Ve +.PP +That is all the setup that we need to do for the \fBSSL_CTX\fR, so next we need to +create an \fBSSL\fR object to represent the TLS connection. In a real application +we might expect to be creating more than one TLS connection over time. In that +case we would expect to reuse the \fBSSL_CTX\fR that we already created each time. +There is no need to repeat those steps. In fact it is best not to since certain +internal resources are cached in the \fBSSL_CTX\fR. You will get better performance +by reusing an existing \fBSSL_CTX\fR instead of creating a new one each time. +.PP +Creating the \fBSSL\fR object is a simple matter of calling the \fBSSL_new\|(3)\fR +function and passing the \fBSSL_CTX\fR we created as an argument. +.PP +.Vb 6 +\& /* Create an SSL object to represent the TLS connection */ +\& ssl = SSL_new(ctx); +\& if (ssl == NULL) { +\& printf("Failed to create the SSL object\en"); +\& goto end; +\& } +.Ve +.SS "Creating the socket and BIO" +.IX Subsection "Creating the socket and BIO" +TLS data is transmitted over an underlying transport layer. Normally a TCP +socket. It is the application\*(Aqs responsibility for ensuring that the socket is +created and associated with an SSL object (via a BIO). +.PP +Socket creation for use by a client is typically a 2 step process, i.e. +constructing the socket; and connecting the socket. +.PP +How to construct a socket is platform specific \- but most platforms (including +Windows) provide a POSIX compatible interface via the \fIsocket\fR function, e.g. +to create an IPv4 TCP socket: +.PP +.Vb 1 +\& int sock; +\& +\& sock = socket(AF_INET, SOCK_STREAM, 0); +\& if (sock == \-1) +\& return NULL; +.Ve +.PP +Once the socket is constructed it must be connected to the remote server. Again +the details are platform specific but most platforms (including Windows) +provide the POSIX compatible \fIconnect\fR function. For example: +.PP +.Vb 2 +\& struct sockaddr_in serveraddr; +\& struct hostent *server; +\& +\& server = gethostbyname("www.openssl.org"); +\& if (server == NULL) { +\& close(sock); +\& return NULL; +\& } +\& +\& memset(&serveraddr, 0, sizeof(serveraddr)); +\& serveraddr.sin_family = server\->h_addrtype; +\& serveraddr.sin_port = htons(443); +\& memcpy(&serveraddr.sin_addr.s_addr, server\->h_addr, server\->h_length); +\& +\& if (connect(sock, (struct sockaddr *)&serveraddr, +\& sizeof(serveraddr)) == \-1) { +\& close(sock); +\& return NULL; +\& } +.Ve +.PP +OpenSSL provides portable helper functions to do these tasks which also +integrate into the OpenSSL error system to log error data, e.g. +.PP +.Vb 3 +\& int sock = \-1; +\& BIO_ADDRINFO *res; +\& const BIO_ADDRINFO *ai = NULL; +\& +\& /* +\& * Lookup IP address info for the server. +\& */ +\& if (!BIO_lookup_ex(hostname, port, BIO_LOOKUP_CLIENT, family, SOCK_STREAM, 0, +\& &res)) +\& return NULL; +\& +\& /* +\& * Loop through all the possible addresses for the server and find one +\& * we can connect to. +\& */ +\& for (ai = res; ai != NULL; ai = BIO_ADDRINFO_next(ai)) { +\& /* +\& * Create a TCP socket. We could equally use non\-OpenSSL calls such +\& * as "socket" here for this and the subsequent connect and close +\& * functions. But for portability reasons and also so that we get +\& * errors on the OpenSSL stack in the event of a failure we use +\& * OpenSSL\*(Aqs versions of these functions. +\& */ +\& sock = BIO_socket(BIO_ADDRINFO_family(ai), SOCK_STREAM, 0, 0); +\& if (sock == \-1) +\& continue; +\& +\& /* Connect the socket to the server\*(Aqs address */ +\& if (!BIO_connect(sock, BIO_ADDRINFO_address(ai), BIO_SOCK_NODELAY)) { +\& BIO_closesocket(sock); +\& sock = \-1; +\& continue; +\& } +\& +\& /* We have a connected socket so break out of the loop */ +\& break; +\& } +\& +\& /* Free the address information resources we allocated earlier */ +\& BIO_ADDRINFO_free(res); +.Ve +.PP +See \fBBIO_lookup_ex\fR\|(3), \fBBIO_socket\fR\|(3), \fBBIO_connect\fR\|(3), +\&\fBBIO_closesocket\fR\|(3), \fBBIO_ADDRINFO_next\fR\|(3), \fBBIO_ADDRINFO_address\fR\|(3) and +\&\fBBIO_ADDRINFO_free\fR\|(3) for further information on the functions used here. In +the above example code the \fBhostname\fR and \fBport\fR variables are strings, e.g. +"www.example.com" and "443". Note also the use of the family variable, which +can take the values of AF_INET or AF_INET6 based on the command line \-6 option, +to allow specific connections to an ipv4 or ipv6 enabled host. +.PP +Sockets created using the methods described above will automatically be blocking +sockets \- which is exactly what we want for this example. +.PP +Once the socket has been created and connected we need to associate it with a +BIO object: +.PP +.Vb 1 +\& BIO *bio; +\& +\& /* Create a BIO to wrap the socket */ +\& bio = BIO_new(BIO_s_socket()); +\& if (bio == NULL) { +\& BIO_closesocket(sock); +\& return NULL; +\& } +\& +\& /* +\& * Associate the newly created BIO with the underlying socket. By +\& * passing BIO_CLOSE here the socket will be automatically closed when +\& * the BIO is freed. Alternatively you can use BIO_NOCLOSE, in which +\& * case you must close the socket explicitly when it is no longer +\& * needed. +\& */ +\& BIO_set_fd(bio, sock, BIO_CLOSE); +.Ve +.PP +See \fBBIO_new\fR\|(3), \fBBIO_s_socket\fR\|(3) and \fBBIO_set_fd\fR\|(3) for further +information on these functions. +.PP +Finally we associate the \fBSSL\fR object we created earlier with the \fBBIO\fR using +the \fBSSL_set_bio\fR\|(3) function. Note that this passes ownership of the \fBBIO\fR +object to the \fBSSL\fR object. Once ownership is passed the SSL object is +responsible for its management and will free it automatically when the \fBSSL\fR is +freed. So, once \fBSSL_set_bio\fR\|(3) has been been called, you should not call +\&\fBBIO_free\fR\|(3) on the \fBBIO\fR. +.PP +.Vb 1 +\& SSL_set_bio(ssl, bio, bio); +.Ve +.SS "Setting the server\*(Aqs hostname" +.IX Subsection "Setting the server's hostname" +We have already connected our underlying socket to the server, but the client +still needs to know the server\*(Aqs hostname. It uses this information for 2 key +purposes and we need to set the hostname for each one. +.PP +Firstly, the server\*(Aqs hostname is included in the initial ClientHello message +sent by the client. This is known as the Server Name Indication (SNI). This is +important because it is common for multiple hostnames to be fronted by a single +server that handles requests for all of them. In other words a single server may +have multiple hostnames associated with it and it is important to indicate which +one we want to connect to. Without this information we may get a handshake +failure, or we may get connected to the "default" server which may not be the +one we were expecting. +.PP +To set the SNI hostname data we call the \fBSSL_set_tlsext_host_name\fR\|(3) function +like this: +.PP +.Vb 8 +\& /* +\& * Tell the server during the handshake which hostname we are attempting +\& * to connect to in case the server supports multiple hosts. +\& */ +\& if (!SSL_set_tlsext_host_name(ssl, hostname)) { +\& printf("Failed to set the SNI hostname\en"); +\& goto end; +\& } +.Ve +.PP +Here the \f(CW\*(C`hostname\*(C'\fR argument is a string representing the hostname of the +server, e.g. "www.example.com". +.PP +Secondly, we need to tell OpenSSL what hostname we expect to see in the +certificate coming back from the server. This is almost always the same one that +we asked for in the original request. This is important because, without this, +we do not verify that the hostname in the certificate is what we expect it to be +and any certificate is acceptable unless your application explicitly checks this +itself. We do this via the \fBSSL_set1_host\fR\|(3) function: +.PP +.Vb 10 +\& /* +\& * Ensure we check during certificate verification that the server has +\& * supplied a certificate for the hostname that we were expecting. +\& * Virtually all clients should do this unless you really know what you +\& * are doing. +\& */ +\& if (!SSL_set1_host(ssl, hostname)) { +\& printf("Failed to set the certificate verification hostname"); +\& goto end; +\& } +.Ve +.PP +All of the above steps must happen before we attempt to perform the handshake +otherwise they will have no effect. +.SS "Performing the handshake" +.IX Subsection "Performing the handshake" +Before we can start sending or receiving application data over a TLS connection +the TLS handshake must be performed. We can do this explicitly via the +\&\fBSSL_connect\fR\|(3) function. +.PP +.Vb 12 +\& /* Do the handshake with the server */ +\& if (SSL_connect(ssl) < 1) { +\& printf("Failed to connect to the server\en"); +\& /* +\& * If the failure is due to a verification error we can get more +\& * information about it from SSL_get_verify_result(). +\& */ +\& if (SSL_get_verify_result(ssl) != X509_V_OK) +\& printf("Verify error: %s\en", +\& X509_verify_cert_error_string(SSL_get_verify_result(ssl))); +\& goto end; +\& } +.Ve +.PP +The \fBSSL_connect\fR\|(3) function can return 1, 0 or less than 0. Only a return +value of 1 is considered a success. For a simple blocking client we only need +to concern ourselves with whether the call was successful or not. Anything else +indicates that we have failed to connect to the server. +.PP +A common cause of failures at this stage is due to a problem verifying the +server\*(Aqs certificate. For example if the certificate has expired, or it is not +signed by a CA in our trusted certificate store. We can use the +\&\fBSSL_get_verify_result\fR\|(3) function to find out more information about the +verification failure. A return value of \fBX509_V_OK\fR indicates that the +verification was successful (so the connection error must be due to some other +cause). Otherwise we use the \fBX509_verify_cert_error_string\fR\|(3) function to get +a human readable error message. +.SS "Sending and receiving data" +.IX Subsection "Sending and receiving data" +Once the handshake is complete we are able to send and receive application data. +Exactly what data is sent and in what order is usually controlled by some +application level protocol. In this example we are using HTTP 1.0 which is a +very simple request and response protocol. The client sends a request to the +server. The server sends the response data and then immediately closes down the +connection. +.PP +To send data to the server we use the \fBSSL_write_ex\fR\|(3) function and to receive +data from the server we use the \fBSSL_read_ex\fR\|(3) function. In HTTP 1.0 the +client always writes data first. Our HTTP request will include the hostname that +we are connecting to. For simplicity, we write the HTTP request in three +chunks. First we write the start of the request. Secondly we write the hostname +we are sending the request to. Finally we send the end of the request. +.PP +.Vb 3 +\& size_t written; +\& const char *request_start = "GET / HTTP/1.0\er\enConnection: close\er\enHost: "; +\& const char *request_end = "\er\en\er\en"; +\& +\& /* Write an HTTP GET request to the peer */ +\& if (!SSL_write_ex(ssl, request_start, strlen(request_start), &written)) { +\& printf("Failed to write start of HTTP request\en"); +\& goto end; +\& } +\& if (!SSL_write_ex(ssl, hostname, strlen(hostname), &written)) { +\& printf("Failed to write hostname in HTTP request\en"); +\& goto end; +\& } +\& if (!SSL_write_ex(ssl, request_end, strlen(request_end), &written)) { +\& printf("Failed to write end of HTTP request\en"); +\& goto end; +\& } +.Ve +.PP +The \fBSSL_write_ex\fR\|(3) function returns 0 if it fails and 1 if it is successful. +If it is successful then we can proceed to waiting for a response from the +server. +.PP +.Vb 2 +\& size_t readbytes; +\& char buf[160]; +\& +\& /* +\& * Get up to sizeof(buf) bytes of the response. We keep reading until the +\& * server closes the connection. +\& */ +\& while (SSL_read_ex(ssl, buf, sizeof(buf), &readbytes)) { +\& /* +\& * OpenSSL does not guarantee that the returned data is a string or +\& * that it is NUL terminated so we use fwrite() to write the exact +\& * number of bytes that we read. The data could be non\-printable or +\& * have NUL characters in the middle of it. For this simple example +\& * we\*(Aqre going to print it to stdout anyway. +\& */ +\& fwrite(buf, 1, readbytes, stdout); +\& } +\& /* In case the response didn\*(Aqt finish with a newline we add one now */ +\& printf("\en"); +.Ve +.PP +We use the \fBSSL_read_ex\fR\|(3) function to read the response. We don\*(Aqt know +exactly how much data we are going to receive back so we enter a loop reading +blocks of data from the server and printing each block that we receive to the +screen. The loop ends as soon as \fBSSL_read_ex\fR\|(3) returns 0 \- meaning that it +failed to read any data. +.PP +A failure to read data could mean that there has been some error, or it could +simply mean that server has sent all the data that it wants to send and has +indicated that it has finished by sending a "close_notify" alert. This alert is +a TLS protocol level message indicating that the endpoint has finished sending +all of its data and it will not send any more. Both of these conditions result +in a 0 return value from \fBSSL_read_ex\fR\|(3) and we need to use the function +\&\fBSSL_get_error\fR\|(3) to determine the cause of the 0 return value. +.PP +.Vb 10 +\& /* +\& * Check whether we finished the while loop above normally or as the +\& * result of an error. The 0 argument to SSL_get_error() is the return +\& * code we received from the SSL_read_ex() call. It must be 0 in order +\& * to get here. Normal completion is indicated by SSL_ERROR_ZERO_RETURN. +\& */ +\& if (SSL_get_error(ssl, 0) != SSL_ERROR_ZERO_RETURN) { +\& /* +\& * Some error occurred other than a graceful close down by the +\& * peer +\& */ +\& printf ("Failed reading remaining data\en"); +\& goto end; +\& } +.Ve +.PP +If \fBSSL_get_error\fR\|(3) returns \fBSSL_ERROR_ZERO_RETURN\fR then we know that the +server has finished sending its data. Otherwise an error has occurred. +.SS "Shutting down the connection" +.IX Subsection "Shutting down the connection" +Once we have finished reading data from the server then we are ready to close +the connection down. We do this via the \fBSSL_shutdown\fR\|(3) function which has +the effect of sending a TLS protocol level message (a "close_notify" alert) to +the server saying that we have finished writing data: +.PP +.Vb 10 +\& /* +\& * The peer already shutdown gracefully (we know this because of the +\& * SSL_ERROR_ZERO_RETURN above). We should do the same back. +\& */ +\& ret = SSL_shutdown(ssl); +\& if (ret < 1) { +\& /* +\& * ret < 0 indicates an error. ret == 0 would be unexpected here +\& * because that means "we\*(Aqve sent a close_notify and we\*(Aqre waiting +\& * for one back". But we already know we got one from the peer +\& * because of the SSL_ERROR_ZERO_RETURN above. +\& */ +\& printf("Error shutting down\en"); +\& goto end; +\& } +.Ve +.PP +The \fBSSL_shutdown\fR\|(3) function will either return 1, 0, or less than 0. A +return value of 1 is a success, and a return value less than 0 is an error. More +precisely a return value of 1 means that we have sent a "close_notify" alert to +the server, and that we have also received one back. A return value of 0 means +that we have sent a "close_notify" alert to the server, but we have not yet +received one back. Usually in this scenario you would call \fBSSL_shutdown\fR\|(3) +again which (with a blocking socket) would block until the "close_notify" is +received. However in this case we already know that the server has sent us a +"close_notify" because of the SSL_ERROR_ZERO_RETURN that we received from the +call to \fBSSL_read_ex\fR\|(3). So this scenario should never happen in practice. We +just treat it as an error in this example. +.SS "Final clean up" +.IX Subsection "Final clean up" +Before the application exits we have to clean up some memory that we allocated. +If we are exiting due to an error we might also want to display further +information about that error if it is available to the user: +.PP +.Vb 10 +\& /* Success! */ +\& res = EXIT_SUCCESS; +\& end: +\& /* +\& * If something bad happened then we will dump the contents of the +\& * OpenSSL error stack to stderr. There might be some useful diagnostic +\& * information there. +\& */ +\& if (res == EXIT_FAILURE) +\& ERR_print_errors_fp(stderr); +\& +\& /* +\& * Free the resources we allocated. We do not free the BIO object here +\& * because ownership of it was immediately transferred to the SSL object +\& * via SSL_set_bio(). The BIO will be freed when we free the SSL object. +\& */ +\& SSL_free(ssl); +\& SSL_CTX_free(ctx); +\& return res; +.Ve +.PP +To display errors we make use of the \fBERR_print_errors_fp\fR\|(3) function which +simply dumps out the contents of any errors on the OpenSSL error stack to the +specified location (in this case \fIstderr\fR). +.PP +We need to free up the \fBSSL\fR object that we created for the connection via the +\&\fBSSL_free\fR\|(3) function. Also, since we are not going to be creating any more +TLS connections we must also free up the \fBSSL_CTX\fR via a call to +\&\fBSSL_CTX_free\fR\|(3). +.SH TROUBLESHOOTING +.IX Header "TROUBLESHOOTING" +There are a number of things that might go wrong when running the demo +application. This section describes some common things you might encounter. +.SS "Failure to connect the underlying socket" +.IX Subsection "Failure to connect the underlying socket" +This could occur for numerous reasons. For example if there is a problem in the +network route between the client and the server; or a firewall is blocking the +communication; or the server is not in DNS. Check the network configuration. +.SS "Verification failure of the server certificate" +.IX Subsection "Verification failure of the server certificate" +A verification failure of the server certificate would result in a failure when +running the \fBSSL_connect\fR\|(3) function. \fBERR_print_errors_fp\fR\|(3) would display +an error which would look something like this: +.PP +.Vb 2 +\& Verify error: unable to get local issuer certificate +\& 40E74AF1F47F0000:error:0A000086:SSL routines:tls_post_process_server_certificate:certificate verify failed:ssl/statem/statem_clnt.c:2069: +.Ve +.PP +A server certificate verification failure could be caused for a number of +reasons. For example +.IP "Failure to correctly setup the trusted certificate store" 4 +.IX Item "Failure to correctly setup the trusted certificate store" +See the page \fBossl\-guide\-tls\-introduction\fR\|(7) and check that your trusted +certificate store is correctly configured +.IP "Unrecognised CA" 4 +.IX Item "Unrecognised CA" +If the CA used by the server\*(Aqs certificate is not in the trusted certificate +store for the client then this will cause a verification failure during +connection. Often this can occur if the server is using a self\-signed +certificate (i.e. a test certificate that has not been signed by a CA at all). +.IP "Missing intermediate CAs" 4 +.IX Item "Missing intermediate CAs" +This is a server misconfiguration where the client has the relevant root CA in +its trust store, but the server has not supplied all of the intermediate CA +certificates between that root CA and the server\*(Aqs own certificate. Therefore +a trust chain cannot be established. +.IP "Mismatched hostname" 4 +.IX Item "Mismatched hostname" +If for some reason the hostname of the server that the client is expecting does +not match the hostname in the certificate then this will cause verification to +fail. +.IP "Expired certificate" 4 +.IX Item "Expired certificate" +The date that the server\*(Aqs certificate is valid to has passed. +.PP +The "unable to get local issuer certificate" we saw in the example above means +that we have been unable to find the issuer of the server\*(Aqs certificate (or one +of its intermediate CA certificates) in our trusted certificate store (e.g. +because the trusted certificate store is misconfigured, or there are missing +intermediate CAs, or the issuer is simply unrecognised). +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-tls\-client\-non\-block\fR\|(7) to read a tutorial on how to modify +the client developed on this page to support a nonblocking socket. +.PP +See \fBossl\-guide\-tls\-server\-block\fR\|(7) for a tutorial on how to implement a +simple TLS server handling one client at a time over a blocking socket. +.PP +See \fBossl\-guide\-quic\-client\-block\fR\|(7) to read a tutorial on how to modify the +client developed on this page to support QUIC instead of TLS. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7), +\&\fBossl\-guide\-tls\-client\-non\-block\fR\|(7), \fBossl\-guide\-quic\-client\-block\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-tls-client-non-block.7 b/static/netbsd/man7/ossl-guide-tls-client-non-block.7 new file mode 100644 index 00000000..158315b9 --- /dev/null +++ b/static/netbsd/man7/ossl-guide-tls-client-non-block.7 @@ -0,0 +1,440 @@ +.\" $NetBSD: ossl-guide-tls-client-non-block.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-TLS-CLIENT-NON-BLOCK 7" +.TH OSSL-GUIDE-TLS-CLIENT-NON-BLOCK 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-tls\-client\-non\-block +\&\- OpenSSL Guide: Writing a simple nonblocking TLS client +.SH "SIMPLE NONBLOCKING TLS CLIENT EXAMPLE" +.IX Header "SIMPLE NONBLOCKING TLS CLIENT EXAMPLE" +This page will build on the example developed on the +\&\fBossl\-guide\-tls\-client\-block\fR\|(7) page which demonstrates how to write a simple +blocking TLS client. On this page we will amend that demo code so that it +supports a nonblocking socket. +.PP +The complete source code for this example nonblocking TLS client is available +in the \fBdemos/guide\fR directory of the OpenSSL source distribution in the file +\&\fBtls\-client\-non\-block.c\fR. It is also available online at +. +.PP +As we saw in the previous example a blocking socket is one which waits (blocks) +until data is available to read if you attempt to read from it when there is no +data yet. Similarly it waits when writing if the socket is currently unable to +write at the moment. This can simplify the development of code because you do +not have to worry about what to do in these cases. The execution of the code +will simply stop until it is able to continue. However in many cases you do not +want this behaviour. Rather than stopping and waiting your application may need +to go and do other tasks whilst the socket is unable to read/write, for example +updating a GUI or performing operations on some other socket. +.PP +With a nonblocking socket attempting to read or write to a socket that is +currently unable to read or write will return immediately with a non\-fatal +error. Although OpenSSL does the reading/writing to the socket this nonblocking +behaviour is propagated up to the application so that OpenSSL I/O functions such +as \fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(3) will not block. +.PP +Since this page is building on the example developed on the +\&\fBossl\-guide\-tls\-client\-block\fR\|(7) page we assume that you are familiar with it +and we only explain how this example differs. +.SS "Setting the socket to be nonblocking" +.IX Subsection "Setting the socket to be nonblocking" +The first step in writing an application that supports nonblocking is to set +the socket into nonblocking mode. A socket will be default be blocking. The +exact details on how to do this can differ from one platform to another. +Fortunately OpenSSL offers a portable function that will do this for you: +.PP +.Vb 5 +\& /* Set to nonblocking mode */ +\& if (!BIO_socket_nbio(sock, 1)) { +\& sock = \-1; +\& continue; +\& } +.Ve +.PP +You do not have to use OpenSSL\*(Aqs function for this. You can of course directly +call whatever functions that your Operating System provides for this purpose on +your platform. +.SS "Performing work while waiting for the socket" +.IX Subsection "Performing work while waiting for the socket" +In a nonblocking application you will need work to perform in the event that +we want to read or write to the socket, but we are currently unable to. In fact +this is the whole point of using a nonblocking socket, i.e. to give the +application the opportunity to do something else. Whatever it is that the +application has to do, it must also be prepared to come back and retry the +operation that it previously attempted periodically to see if it can now +complete. Ideally it would only do this in the event that the state of the +underlying socket has actually changed (e.g. become readable where it wasn\*(Aqt +before), but this does not have to be the case. It can retry at any time. +.PP +Note that it is important that you retry exactly the same operation that you +tried last time. You cannot start something new. For example if you were +attempting to write the text "Hello World" and the operation failed because the +socket is currently unable to write, then you cannot then attempt to write +some other text when you retry the operation. +.PP +In this demo application we will create a helper function which simulates doing +other work. In fact, for the sake of simplicity, it will do nothing except wait +for the state of the socket to change. +.PP +We call our function \f(CWwait_for_activity()\fR because all it does is wait until +the underlying socket has become readable or writeable when it wasn\*(Aqt before. +.PP +.Vb 4 +\& static void wait_for_activity(SSL *ssl, int write) +\& { +\& fd_set fds; +\& int width, sock; +\& +\& /* Get hold of the underlying file descriptor for the socket */ +\& sock = SSL_get_fd(ssl); +\& +\& FD_ZERO(&fds); +\& FD_SET(sock, &fds); +\& width = sock + 1; +\& +\& /* +\& * Wait until the socket is writeable or readable. We use select here +\& * for the sake of simplicity and portability, but you could equally use +\& * poll/epoll or similar functions +\& * +\& * NOTE: For the purposes of this demonstration code this effectively +\& * makes this demo block until it has something more useful to do. In a +\& * real application you probably want to go and do other work here (e.g. +\& * update a GUI, or service other connections). +\& * +\& * Let\*(Aqs say for example that you want to update the progress counter on +\& * a GUI every 100ms. One way to do that would be to add a 100ms timeout +\& * in the last parameter to "select" below. Then, when select returns, +\& * you check if it did so because of activity on the file descriptors or +\& * because of the timeout. If it is due to the timeout then update the +\& * GUI and then restart the "select". +\& */ +\& if (write) +\& select(width, NULL, &fds, NULL, NULL); +\& else +\& select(width, &fds, NULL, NULL, NULL); +\& } +.Ve +.PP +In this example we are using the \f(CW\*(C`select\*(C'\fR function because it is very simple +to use and is available on most Operating Systems. However you could use any +other similar function to do the same thing. \f(CW\*(C`select\*(C'\fR waits for the state of +the underlying socket(s) to become readable/writeable before returning. It also +supports a "timeout" (as do most other similar functions) so in your own +applications you can make use of this to periodically wake up and perform work +while waiting for the socket state to change. But we don\*(Aqt use that timeout +capability in this example for the sake of simplicity. +.SS "Handling errors from OpenSSL I/O functions" +.IX Subsection "Handling errors from OpenSSL I/O functions" +An application that uses a nonblocking socket will need to be prepared to +handle errors returned from OpenSSL I/O functions such as \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_write_ex\fR\|(3). Errors may be fatal (for example because the underlying +connection has failed), or non\-fatal (for example because we are trying to read +from the underlying socket but the data has not yet arrived from the peer). +.PP +\&\fBSSL_read_ex\fR\|(3) and \fBSSL_write_ex\fR\|(3) will return 0 to indicate an error and +\&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) will return 0 or a negative value to indicate +an error. \fBSSL_shutdown\fR\|(3) will return a negative value to incidate an error. +.PP +In the event of an error an application should call \fBSSL_get_error\fR\|(3) to find +out what type of error has occurred. If the error is non\-fatal and can be +retried then \fBSSL_get_error\fR\|(3) will return \fBSSL_ERROR_WANT_READ\fR or +\&\fBSSL_ERROR_WANT_WRITE\fR depending on whether OpenSSL wanted to read to or write +from the socket but was unable to. Note that a call to \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_read\fR\|(3) can still generate \fBSSL_ERROR_WANT_WRITE\fR because OpenSSL +may need to write protocol messages (such as to update cryptographic keys) even +if the application is only trying to read data. Similarly calls to +\&\fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) might generate \fBSSL_ERROR_WANT_READ\fR. +.PP +Another type of non\-fatal error that may occur is \fBSSL_ERROR_ZERO_RETURN\fR. This +indicates an EOF (End\-Of\-File) which can occur if you attempt to read data from +an \fBSSL\fR object but the peer has indicated that it will not send any more data +on it. In this case you may still want to write data to the connection but you +will not receive any more data. +.PP +Fatal errors that may occur are \fBSSL_ERROR_SYSCALL\fR and \fBSSL_ERROR_SSL\fR. These +indicate that the underlying connection has failed. You should not attempt to +shut it down with \fBSSL_shutdown\fR\|(3). \fBSSL_ERROR_SYSCALL\fR indicates that +OpenSSL attempted to make a syscall that failed. You can consult \fBerrno\fR for +further details. \fBSSL_ERROR_SSL\fR indicates that some OpenSSL error occurred. You +can consult the OpenSSL error stack for further details (for example by calling +\&\fBERR_print_errors\fR\|(3) to print out details of errors that have occurred). +.PP +In our demo application we will write a function to handle these errors from +OpenSSL I/O functions: +.PP +.Vb 7 +\& static int handle_io_failure(SSL *ssl, int res) +\& { +\& switch (SSL_get_error(ssl, res)) { +\& case SSL_ERROR_WANT_READ: +\& /* Temporary failure. Wait until we can read and try again */ +\& wait_for_activity(ssl, 0); +\& return 1; +\& +\& case SSL_ERROR_WANT_WRITE: +\& /* Temporary failure. Wait until we can write and try again */ +\& wait_for_activity(ssl, 1); +\& return 1; +\& +\& case SSL_ERROR_ZERO_RETURN: +\& /* EOF */ +\& return 0; +\& +\& case SSL_ERROR_SYSCALL: +\& return \-1; +\& +\& case SSL_ERROR_SSL: +\& /* +\& * If the failure is due to a verification error we can get more +\& * information about it from SSL_get_verify_result(). +\& */ +\& if (SSL_get_verify_result(ssl) != X509_V_OK) +\& printf("Verify error: %s\en", +\& X509_verify_cert_error_string(SSL_get_verify_result(ssl))); +\& return \-1; +\& +\& default: +\& return \-1; +\& } +\& } +.Ve +.PP +This function takes as arguments the \fBSSL\fR object that represents the +connection, as well as the return code from the I/O function that failed. In +the event of a non\-fatal failure, it waits until a retry of the I/O operation +might succeed (by using the \f(CWwait_for_activity()\fR function that we developed +in the previous section). It returns 1 in the event of a non\-fatal error +(except EOF), 0 in the event of EOF, or \-1 if a fatal error occurred. +.SS "Creating the SSL_CTX and SSL objects" +.IX Subsection "Creating the SSL_CTX and SSL objects" +In order to connect to a server we must create \fBSSL_CTX\fR and \fBSSL\fR objects for +this. The steps do this are the same as for a blocking client and are explained +on the \fBossl\-guide\-tls\-client\-block\fR\|(7) page. We won\*(Aqt repeat that information +here. +.SS "Performing the handshake" +.IX Subsection "Performing the handshake" +As in the demo for a blocking TLS client we use the \fBSSL_connect\fR\|(3) function +to perform the TLS handshake with the server. Since we are using a nonblocking +socket it is very likely that calls to this function will fail with a non\-fatal +error while we are waiting for the server to respond to our handshake messages. +In such a case we must retry the same \fBSSL_connect\fR\|(3) call at a later time. +In this demo we this in a loop: +.PP +.Vb 7 +\& /* Do the handshake with the server */ +\& while ((ret = SSL_connect(ssl)) != 1) { +\& if (handle_io_failure(ssl, ret) == 1) +\& continue; /* Retry */ +\& printf("Failed to connect to server\en"); +\& goto end; /* Cannot retry: error */ +\& } +.Ve +.PP +We continually call \fBSSL_connect\fR\|(3) until it gives us a success response. +Otherwise we use the \f(CWhandle_io_failure()\fR function that we created earlier to +work out what we should do next. Note that we do not expect an EOF to occur at +this stage, so such a response is treated in the same way as a fatal error. +.SS "Sending and receiving data" +.IX Subsection "Sending and receiving data" +As with the blocking TLS client demo we use the \fBSSL_write_ex\fR\|(3) function to +send data to the server. As with \fBSSL_connect\fR\|(3) above, because we are using +a nonblocking socket, this call could fail with a non\-fatal error. In that case +we should retry exactly the same \fBSSL_write_ex\fR\|(3) call again. Note that the +parameters must be \fIexactly\fR the same, i.e. the same pointer to the buffer to +write with the same length. You must not attempt to send different data on a +retry. An optional mode does exist (\fBSSL_MODE_ACCEPT_MOVING_WRITE_BUFFER\fR) +which will configure OpenSSL to allow the buffer being written to change from +one retry to the next. However, in this case, you must still retry exactly the +same data \- even though the buffer that contains that data may change location. +See \fBSSL_CTX_set_mode\fR\|(3) for further details. As in the TLS client +blocking tutorial (\fBossl\-guide\-tls\-client\-block\fR\|(7)) we write the request +in three chunks. +.PP +.Vb 10 +\& /* Write an HTTP GET request to the peer */ +\& while (!SSL_write_ex(ssl, request_start, strlen(request_start), &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write start of HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& while (!SSL_write_ex(ssl, hostname, strlen(hostname), &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write hostname in HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& while (!SSL_write_ex(ssl, request_end, strlen(request_end), &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write end of HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +.Ve +.PP +On a write we do not expect to see an EOF response so we treat that case in the +same way as a fatal error. +.PP +Reading a response back from the server is similar: +.PP +.Vb 10 +\& do { +\& /* +\& * Get up to sizeof(buf) bytes of the response. We keep reading until +\& * the server closes the connection. +\& */ +\& while (!eof && !SSL_read_ex(ssl, buf, sizeof(buf), &readbytes)) { +\& switch (handle_io_failure(ssl, 0)) { +\& case 1: +\& continue; /* Retry */ +\& case 0: +\& eof = 1; +\& continue; +\& case \-1: +\& default: +\& printf("Failed reading remaining data\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& } +\& /* +\& * OpenSSL does not guarantee that the returned data is a string or +\& * that it is NUL terminated so we use fwrite() to write the exact +\& * number of bytes that we read. The data could be non\-printable or +\& * have NUL characters in the middle of it. For this simple example +\& * we\*(Aqre going to print it to stdout anyway. +\& */ +\& if (!eof) +\& fwrite(buf, 1, readbytes, stdout); +\& } while (!eof); +\& /* In case the response didn\*(Aqt finish with a newline we add one now */ +\& printf("\en"); +.Ve +.PP +The main difference this time is that it is valid for us to receive an EOF +response when trying to read data from the server. This will occur when the +server closes down the connection after sending all the data in its response. +.PP +In this demo we just print out all the data we\*(Aqve received back in the response +from the server. We continue going around the loop until we either encounter a +fatal error, or we receive an EOF (indicating a graceful finish). +.SS "Shutting down the connection" +.IX Subsection "Shutting down the connection" +As in the TLS blocking example we must shutdown the connection when we are +finished with it. +.PP +If our application was initiating the shutdown then we would expect to see +\&\fBSSL_shutdown\fR\|(3) give a return value of 0, and then we would continue to call +it until we received a return value of 1 (meaning we have successfully completed +the shutdown). In this particular example we don\*(Aqt expect \fBSSL_shutdown()\fR to +return 0 because we have already received EOF from the server indicating that it +has shutdown already. So we just keep calling it until \fBSSL_shutdown()\fR returns 1. +Since we are using a nonblocking socket we might expect to have to retry this +operation several times. If \fBSSL_shutdown\fR\|(3) returns a negative result then we +must call \fBSSL_get_error\fR\|(3) to work out what to do next. We use our +\&\fBhandle_io_failure()\fR function that we developed earlier for this: +.PP +.Vb 10 +\& /* +\& * The peer already shutdown gracefully (we know this because of the +\& * SSL_ERROR_ZERO_RETURN (i.e. EOF) above). We should do the same back. +\& */ +\& while ((ret = SSL_shutdown(ssl)) != 1) { +\& if (ret < 0 && handle_io_failure(ssl, ret) == 1) +\& continue; /* Retry */ +\& /* +\& * ret == 0 is unexpected here because that means "we\*(Aqve sent a +\& * close_notify and we\*(Aqre waiting for one back". But we already know +\& * we got one from the peer because of the SSL_ERROR_ZERO_RETURN +\& * (i.e. EOF) above. +\& */ +\& printf("Error shutting down\en"); +\& goto end; /* Cannot retry: error */ +\& } +.Ve +.SS "Final clean up" +.IX Subsection "Final clean up" +As with the blocking TLS client example, once our connection is finished with we +must free it. The steps to do this for this example are the same as for the +blocking example, so we won\*(Aqt repeat it here. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-tls\-client\-block\fR\|(7) to read a tutorial on how to write a +blocking TLS client. See \fBossl\-guide\-quic\-client\-block\fR\|(7) to see how to do the +same thing for a QUIC client. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7), +\&\fBossl\-guide\-tls\-client\-block\fR\|(7), \fBossl\-guide\-quic\-client\-block\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-tls-introduction.7 b/static/netbsd/man7/ossl-guide-tls-introduction.7 new file mode 100644 index 00000000..eb4922c1 --- /dev/null +++ b/static/netbsd/man7/ossl-guide-tls-introduction.7 @@ -0,0 +1,381 @@ +.\" $NetBSD: ossl-guide-tls-introduction.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-TLS-INTRODUCTION 7" +.TH OSSL-GUIDE-TLS-INTRODUCTION 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-tls\-introduction +\&\- OpenSSL Guide: An introduction to SSL/TLS in OpenSSL +.SH INTRODUCTION +.IX Header "INTRODUCTION" +This page will provide an introduction to some basic SSL/TLS concepts and +background and how it is used within OpenSSL. It assumes that you have a basic +understanding of TCP/IP and sockets. +.SH "WHAT IS TLS?" +.IX Header "WHAT IS TLS?" +TLS stands for Transport Layer Security. TLS allows applications to securely +communicate with each other across a network such that the confidentiality of +the information exchanged is protected (i.e. it prevents eavesdroppers from +listening in to the communication). Additionally it protects the integrity of +the information exchanged to prevent an attacker from changing it. Finally it +provides authentication so that one or both parties can be sure that they are +talking to who they think they are talking to and not some imposter. +.PP +Sometimes TLS is referred to by its predecessor\*(Aqs name SSL (Secure Sockets +Layer). OpenSSL dates from a time when the SSL name was still in common use and +hence many of the functions and names used by OpenSSL contain the "SSL" +abbreviation. Nonetheless OpenSSL contains a fully fledged TLS implementation. +.PP +TLS is based on a client/server model. The application that initiates a +communication is known as the client. The application that responds to a +remotely initiated communication is the server. The term "endpoint" refers to +either of the client or the server in a communication. The term "peer" refers to +the endpoint at the other side of the communication that we are currently +referring to. So if we are currently talking about the client then the peer +would be the server. +.PP +TLS is a standardised protocol and there are numerous different implementations +of it. Due to the standards an OpenSSL client or server is able to communicate +seamlessly with an application using some different implementation of TLS. TLS +(and its predecessor SSL) have been around for a significant period of time and +the protocol has undergone various changes over the years. Consequently there +are different versions of the protocol available. TLS includes the ability to +perform version negotiation so that the highest protocol version that the client +and server share in common is used. +.PP +TLS acts as a security layer over some lower level transport protocol. Typically +the transport layer will be TCP. +.SH "SSL AND TLS VERSIONS" +.IX Header "SSL AND TLS VERSIONS" +SSL was initially developed by Netscape Communications and its first publicly +released version was SSLv2 in 1995. Note that SSLv1 was never publicly released. +SSLv3 came along quickly afterwards in 1996. Subsequently development of the +protocol moved to the IETF which released the first version of TLS (TLSv1.0) in +1999 as RFC2246. TLSv1.1 was released in 2006 as RFC4346 and TLSv1.2 came along +in 2008 as RFC5246. The most recent version of the standard is TLSv1.3 which +was released in 2018 as RFC8446. +.PP +Today TLSv1.3 and TLSv1.2 are the most commonly deployed versions of the +protocol. The IETF have formally deprecated TLSv1.1 and TLSv1.0, so anything +below TLSv1.2 should be avoided since the older protocol versions are +susceptible to security problems. +.PP +OpenSSL does not support SSLv2 (it was removed in OpenSSL 1.1.0). Support for +SSLv3 is available as a compile time option \- but it is not built by default. +Support for TLSv1.0, TLSv1.1, TLSv1.2 and TLSv1.3 are all available by default +in a standard build of OpenSSL. However special run\-time configuration is +required in order to make TLSv1.0 and TLSv1.1 work successfully. +.PP +OpenSSL will always try to negotiate the highest protocol version that it has +been configured to support. In most cases this will mean either TLSv1.3 or +TLSv1.2 is chosen. +.SH CERTIFICATES +.IX Header "CERTIFICATES" +In order for a client to establish a connection to a server it must authenticate +the identity of that server, i.e. it needs to confirm that the server is really +the server that it claims to be and not some imposter. In order to do this the +server will send to the client a digital certificate (also commonly referred to +as an X.509 certificate). The certificate contains various information about the +server including its full DNS hostname. Also within the certificate is the +server\*(Aqs public key. The server operator will have a private key which is +linked to the public key and must not be published. +.PP +Along with the certificate the server will also send to the client proof that it +knows the private key associated with the public key in the certificate. It does +this by digitally signing a message to the client using that private key. The +client can verify the signature using the public key from the certificate. If +the signature verifies successfully then the client knows that the server is in +possession of the correct private key. +.PP +The certificate that the server sends will also be signed by a Certificate +Authority. The Certificate Authority (commonly known as a CA) is a third party +organisation that is responsible for verifying the information in the server\*(Aqs +certificate (including its DNS hostname). The CA should only sign the +certificate if it has been able to confirm that the server operator does indeed +have control of the server associated with its DNS hostname and that the server +operator has control of the private key. +.PP +In this way, if the client trusts the CA that has signed the server\*(Aqs +certificate and it can verify that the server has the right private key then it +can trust that the server truly does represent the DNS hostname given in the +certificate. The client must also verify that the hostname given in the +certificate matches the hostname that it originally sent the request to. +.PP +Once all of these checks have been done the client has successfully verified the +identify of the server. OpenSSL can perform all of these checks automatically +but it must be provided with certain information in order to do so, i.e. the set +of CAs that the client trusts as well as the DNS hostname for the server that +this client is trying to connect to. +.PP +Note that it is common for certificates to be built up into a chain. For example +a server\*(Aqs certificate may be signed by a key owned by a an intermediate CA. +That intermediate CA also has a certificate containing its public key which is +in turn signed by a key owned by a root CA. The client may only trust the root +CA, but if the server sends both its own certificate and the certificate for the +intermediate CA then the client can still successfully verify the identity of +the server. There is a chain of trust between the root CA and the server. +.PP +By default it is only the client that authenticates the server using this +method. However it is also possible to set things up such that the server +additionally authenticates the client. This is known as "client authentication". +In this approach the client will still authenticate the server in the same way, +but the server will request a certificate from the client. The client sends the +server its certificate and the server authenticates it in the same way that the +client does. +.SH "TRUSTED CERTIFICATE STORE" +.IX Header "TRUSTED CERTIFICATE STORE" +The system described above only works if a chain of trust can be built between +the set of CAs that the endpoint trusts and the certificate that the peer is +using. The endpoint must therefore have a set of certificates for CAs that it +trusts before any communication can take place. OpenSSL itself does not provide +such a set of certificates. Therefore you will need to make sure you have them +before you start if you are going to be verifying certificates (i.e. always if +the endpoint is a client, and only if client authentication is in use for a +server). +.PP +Fortunately other organisations do maintain such a set of certificates. If you +have obtained your copy of OpenSSL from an Operating System (OS) vendor (e.g. a +Linux distribution) then normally the set of CA certificates will also be +distributed with that copy. +.PP +You can check this by running the OpenSSL command line application like this: +.PP +.Vb 1 +\& openssl version \-d +.Ve +.PP +This will display a value for \fBOPENSSLDIR\fR. Look in the \fBcerts\fR sub directory +of \fBOPENSSLDIR\fR and check its contents. For example if \fBOPENSSLDIR\fR is +"/usr/local/ssl", then check the contents of the "/usr/local/ssl/certs" +directory. +.PP +You are expecting to see a list of files, typically with the suffix ".pem" or +".0". If they exist then you already have a suitable trusted certificate store. +.PP +If you are running your version of OpenSSL on Windows then OpenSSL (from version +3.2 onwards) will use the default Windows set of trusted CAs. +.PP +If you have built your version of OpenSSL from source, or obtained it from some +other location and it does not have a set of trusted CA certificates then you +will have to obtain them yourself. One such source is the Curl project. See the +page where you can download trusted +certificates in a single file. Rename the file to "cert.pem" and store it +directly in \fBOPENSSLDIR\fR. For example if \fBOPENSSLDIR\fR is "/usr/local/ssl", +then save it as "/usr/local/ssl/cert.pem". +.PP +You can also use environment variables to override the default location that +OpenSSL will look for its trusted certificate store. Set the \fBSSL_CERT_DIR\fR +environment variable to give the directory where OpenSSL should looks for its +certificates or the \fBSSL_CERT_FILE\fR environment variable to give the name of +a single file containing all of the certificates. See \fBopenssl\-env\fR\|(7) for +further details about OpenSSL environment variables. For example you could use +this capability to have multiple versions of OpenSSL all installed on the same +system using different values for \fBOPENSSLDIR\fR but all using the same +trusted certificate store. +.PP +You can test that your trusted certificate store is setup correctly by using it +via the OpenSSL command line. Use the following command to connect to a TLS +server: +.PP +.Vb 1 +\& openssl s_client www.openssl.org:443 +.Ve +.PP +Once the command has connected type the letter "Q" followed by "" to exit +the session. This will print a lot of information on the screen about the +connection. Look for a block of text like this: +.PP +.Vb 2 +\& SSL handshake has read 4584 bytes and written 403 bytes +\& Verification: OK +.Ve +.PP +Hopefully if everything has worked then the "Verification" line will say "OK". +If its not working as expected then you might see output like this instead: +.PP +.Vb 2 +\& SSL handshake has read 4584 bytes and written 403 bytes +\& Verification error: unable to get local issuer certificate +.Ve +.PP +The "unable to get local issuer certificate" error means that OpenSSL has been +unable to find a trusted CA for the chain of certificates provided by the server +in its trusted certificate store. Check your trusted certificate store +configuration again. +.PP +Note that s_client is a testing tool and will still allow you to connect to the +TLS server regardless of the verification error. Most applications should not do +this and should abort the connection in the event of a verification error. +.SH "IMPORTANT OBJECTS FOR AN OPENSSL TLS APPLICATION" +.IX Header "IMPORTANT OBJECTS FOR AN OPENSSL TLS APPLICATION" +A TLS connection is represented by the \fBSSL\fR object in an OpenSSL based +application. Once a connection with a remote peer has been established an +endpoint can "write" data to the \fBSSL\fR object to send data to the peer, or +"read" data from it to receive data from the server. +.PP +A new \fBSSL\fR object is created from an \fBSSL_CTX\fR object. Think of an \fBSSL_CTX\fR +as a "factory" for creating \fBSSL\fR objects. You can create a single \fBSSL_CTX\fR +object and then create multiple connections (i.e. \fBSSL\fR objects) from it. +Typically you can set up common configuration options on the \fBSSL_CTX\fR so that +all the \fBSSL\fR object created from it inherit the same configuration options. +.PP +Note that internally to OpenSSL various items that are shared between multiple +\&\fBSSL\fR objects are cached in the \fBSSL_CTX\fR for performance reasons. Therefore +it is considered best practice to create one \fBSSL_CTX\fR for use by multiple +\&\fBSSL\fR objects instead of having one \fBSSL_CTX\fR for each \fBSSL\fR object that you +create. +.PP +Each \fBSSL\fR object is also associated with two \fBBIO\fR objects. A \fBBIO\fR object +is used for sending or receiving data from the underlying transport layer. For +example you might create a \fBBIO\fR to represent a TCP socket. The \fBSSL\fR object +uses one \fBBIO\fR for reading data and one \fBBIO\fR for writing data. In most cases +you would use the same \fBBIO\fR for each direction but there could be some +circumstances where you want them to be different. +.PP +It is up to the application programmer to create the \fBBIO\fR objects that are +needed and supply them to the \fBSSL\fR object. See +\&\fBossl\-guide\-tls\-client\-block\fR\|(7) and \fBossl\-guide\-tls\-server\-block\fR\|(7) for +usage examples. +.PP +Finally, an endpoint can establish a "session" with its peer. The session holds +various TLS parameters about the connection between the client and the server. +The session details can then be reused in a subsequent connection attempt to +speed up the process of connecting. This is known as "resumption". Sessions are +represented in OpenSSL by the \fBSSL_SESSION\fR object. In TLSv1.2 there is always +exactly one session per connection. In TLSv1.3 there can be any number per +connection including none. +.SH "PHASES OF A TLS CONNECTION" +.IX Header "PHASES OF A TLS CONNECTION" +A TLS connection starts with an initial "set up" phase. The endpoint creates the +\&\fBSSL_CTX\fR (if one has not already been created) and configures it. +.PP +A client then creates an \fBSSL\fR object to represent the new TLS connection. Any +connection specific configuration parameters are then applied and the underlying +socket is created and associated with the \fBSSL\fR via \fBBIO\fR objects. +.PP +A server will create a socket for listening for incoming connection attempts +from clients. Once a connection attempt is made the server will create an \fBSSL\fR +object in the same way as for a client and associate it with a \fBBIO\fR for the +newly created incoming socket. +.PP +After set up is complete the TLS "handshake" phase begins. A TLS handshake +consists of the client and server exchanging a series of TLS handshake messages +to establish the connection. The client starts by sending a "ClientHello" +handshake message and the server responds with a "ServerHello". The handshake is +complete once an endpoint has sent its last message (known as the "Finished" +message) and received a Finished message from its peer. Note that this might +occur at slightly different times for each peer. For example in TLSv1.3 the +server always sends its Finished message before the client. The client later +responds with its Finished message. At this point the client has completed the +handshake because it has both sent and received a Finished message. The server +has sent its Finished message but the Finished message from the client may still +be in\-flight, so the server is still in the handshake phase. It is even possible +that the server will fail to complete the handshake (if it considers there is +some problem with the messages sent from the client), even though the client may +have already progressed to sending application data. In TLSv1.2 this can happen +the other way around, i.e. the server finishes first and the client finishes +second. +.PP +Once the handshake is complete the application data transfer phase begins. +Strictly speaking there are some situations where the client can start sending +application data even earlier (using the TLSv1.3 "early data" capability) \- but +we\*(Aqre going to skip over that for this basic introduction. +.PP +During application data transfer the client and server can read and write data +to the connection freely. The details of this are typically left to some higher +level application protocol (for example HTTP). Not all information exchanged +during this phase is application data. Some protocol level messages may still +be exchanged \- so it is not necessarily the case that, just because the +underlying socket is "readable", that application data will be available to read. +.PP +When the connection is no longer required then it should be shutdown. A shutdown +may be initiated by either the client or the server via a message known as a +"close_notify" alert. The client or server that receives a close_notify may +respond with one and then the connection is fully closed and application data +can no longer be sent or received. +.PP +Once shutdown is complete a TLS application must clean up by freeing the SSL +object. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-tls\-client\-block\fR\|(7) for an example of how to apply these +concepts in order to write a simple TLS client based on a blocking socket. +See \fBossl\-guide\-tls\-server\-block\fR\|(7) for an example of how to apply these +concepts in order to write a simple TLS server handling one client at a time +over a blocking socket. +See \fBossl\-guide\-quic\-introduction\fR\|(7) for an introduction to QUIC in OpenSSL. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-client\-block\fR\|(7), +\&\fBossl\-guide\-tls\-server\-block\fR\|(7), \fBossl\-guide\-quic\-introduction\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl-guide-tls-server-block.7 b/static/netbsd/man7/ossl-guide-tls-server-block.7 new file mode 100644 index 00000000..bcf825f3 --- /dev/null +++ b/static/netbsd/man7/ossl-guide-tls-server-block.7 @@ -0,0 +1,410 @@ +.\" $NetBSD: ossl-guide-tls-server-block.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-TLS-SERVER-BLOCK 7" +.TH OSSL-GUIDE-TLS-SERVER-BLOCK 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-tls\-server\-block +\&\- OpenSSL Guide: Writing a simple blocking TLS server +.SH "SIMPLE BLOCKING TLS SERVER EXAMPLE" +.IX Header "SIMPLE BLOCKING TLS SERVER EXAMPLE" +This page will present various source code samples demonstrating how to write a +simple, non\-concurrent, TLS "echo" server application which accepts one client +connection at a time, echoing input from the client back to the same client. +Once the current client disconnects, the next client connection is accepted. +.PP +Both the acceptor socket and client connections are "blocking". A more typical +server might use nonblocking sockets with an event loop and callbacks for I/O +events. +.PP +The complete source code for this example blocking TLS server is available in +the \fBdemos/guide\fR directory of the OpenSSL source distribution in the file +\&\fBtls\-server\-block.c\fR. It is also available online at +. +.PP +We assume that you already have OpenSSL installed on your system; that you +already have some fundamental understanding of OpenSSL concepts and TLS (see +\&\fBossl\-guide\-libraries\-introduction\fR\|(7) and \fBossl\-guide\-tls\-introduction\fR\|(7)); +and that you know how to write and build C code and link it against the +libcrypto and libssl libraries that are provided by OpenSSL. It also assumes +that you have a basic understanding of TCP/IP and sockets. +.SS "Creating the SSL_CTX and SSL objects" +.IX Subsection "Creating the SSL_CTX and SSL objects" +The first step is to create an \fBSSL_CTX\fR object for our server. We use the +\&\fBSSL_CTX_new\fR\|(3) function for this purpose. We could alternatively use +\&\fBSSL_CTX_new_ex\fR\|(3) if we want to associate the \fBSSL_CTX\fR with a particular +\&\fBOSSL_LIB_CTX\fR (see \fBossl\-guide\-libraries\-introduction\fR\|(7) to learn about +\&\fBOSSL_LIB_CTX\fR). We pass as an argument the return value of the function +\&\fBTLS_server_method\fR\|(3). You should use this method whenever you are writing a +TLS server. This method will automatically use TLS version negotiation to select +the highest version of the protocol that is mutually supported by both the +server and the client. +.PP +.Vb 9 +\& /* +\& * An SSL_CTX holds shared configuration information for multiple +\& * subsequent per\-client SSL connections. +\& */ +\& ctx = SSL_CTX_new(TLS_server_method()); +\& if (ctx == NULL) { +\& ERR_print_errors_fp(stderr); +\& errx(res, "Failed to create server SSL_CTX"); +\& } +.Ve +.PP +We would also like to restrict the TLS versions that we are willing to accept to +TLSv1.2 or above. TLS protocol versions earlier than that are generally to be +avoided where possible. We can do that using +\&\fBSSL_CTX_set_min_proto_version\fR\|(3): +.PP +.Vb 9 +\& /* +\& * TLS versions older than TLS 1.2 are deprecated by IETF and SHOULD +\& * be avoided if possible. +\& */ +\& if (!SSL_CTX_set_min_proto_version(ctx, TLS1_2_VERSION)) { +\& SSL_CTX_free(ctx); +\& ERR_print_errors_fp(stderr); +\& errx(res, "Failed to set the minimum TLS protocol version"); +\& } +.Ve +.PP +Next we configure some option flags, see \fBSSL_CTX_set_options\fR\|(3) for details: +.PP +.Vb 6 +\& /* +\& * Tolerate clients hanging up without a TLS "shutdown". Appropriate in all +\& * application protocols which perform their own message "framing", and +\& * don\*(Aqt rely on TLS to defend against "truncation" attacks. +\& */ +\& opts = SSL_OP_IGNORE_UNEXPECTED_EOF; +\& +\& /* +\& * Block potential CPU\-exhaustion attacks by clients that request frequent +\& * renegotiation. This is of course only effective if there are existing +\& * limits on initial full TLS handshake or connection rates. +\& */ +\& opts |= SSL_OP_NO_RENEGOTIATION; +\& +\& /* +\& * Most servers elect to use their own cipher preference rather than that of +\& * the client. +\& */ +\& opts |= SSL_OP_CIPHER_SERVER_PREFERENCE; +\& +\& /* Apply the selection options */ +\& SSL_CTX_set_options(ctx, opts); +.Ve +.PP +Servers need a private key and certificate. Though anonymous ciphers (no +server certificate) are possible in TLS 1.2, they are rarely applicable, and +are not currently defined for TLS 1.3. Additional intermediate issuer CA +certificates are often also required, and both the server (end\-entity or EE) +certificate and the issuer ("chain") certificates are most easily configured in +a single "chain file". Below we load such a chain file (the EE certificate +must appear first), and then load the corresponding private key, checking that +it matches the server certificate. No checks are performed to check the +integrity of the chain (CA signatures or certificate expiration dates, for +example). +.PP +.Vb 10 +\& /* +\& * Load the server\*(Aqs certificate *chain* file (PEM format), which includes +\& * not only the leaf (end\-entity) server certificate, but also any +\& * intermediate issuer\-CA certificates. The leaf certificate must be the +\& * first certificate in the file. +\& * +\& * In advanced use\-cases this can be called multiple times, once per public +\& * key algorithm for which the server has a corresponding certificate. +\& * However, the corresponding private key (see below) must be loaded first, +\& * *before* moving on to the next chain file. +\& */ +\& if (SSL_CTX_use_certificate_chain_file(ctx, "chain.pem") <= 0) { +\& SSL_CTX_free(ctx); +\& ERR_print_errors_fp(stderr); +\& errx(res, "Failed to load the server certificate chain file"); +\& } +\& +\& /* +\& * Load the corresponding private key, this also checks that the private +\& * key matches the just loaded end\-entity certificate. It does not check +\& * whether the certificate chain is valid, the certificates could be +\& * expired, or may otherwise fail to form a chain that a client can validate. +\& */ +\& if (SSL_CTX_use_PrivateKey_file(ctx, "pkey.pem", SSL_FILETYPE_PEM) <= 0) { +\& SSL_CTX_free(ctx); +\& ERR_print_errors_fp(stderr); +\& errx(res, "Error loading the server private key file, " +\& "possible key/cert mismatch???"); +\& } +.Ve +.PP +Next we enable session caching, which makes it possible for clients to more +efficiently make additional TLS connections after completing an initial full +TLS handshake. With TLS 1.3, session resumption typically still performs a fresh +key agreement, but the certificate exchange is avoided. +.PP +.Vb 7 +\& /* +\& * Servers that want to enable session resumption must specify a cache id +\& * byte array, that identifies the server application, and reduces the +\& * chance of inappropriate cache sharing. +\& */ +\& SSL_CTX_set_session_id_context(ctx, (void *)cache_id, sizeof(cache_id)); +\& SSL_CTX_set_session_cache_mode(ctx, SSL_SESS_CACHE_SERVER); +\& +\& /* +\& * How many client TLS sessions to cache. The default is +\& * SSL_SESSION_CACHE_MAX_SIZE_DEFAULT (20k in recent OpenSSL versions), +\& * which may be too small or too large. +\& */ +\& SSL_CTX_sess_set_cache_size(ctx, 1024); +\& +\& /* +\& * Sessions older than this are considered a cache miss even if still in +\& * the cache. The default is two hours. Busy servers whose clients make +\& * many connections in a short burst may want a shorter timeout, on lightly +\& * loaded servers with sporadic connections from any given client, a longer +\& * time may be appropriate. +\& */ +\& SSL_CTX_set_timeout(ctx, 3600); +.Ve +.PP +Most servers, including this one, do not solicit client certificates. We +therefore do not need a "trust store" and allow the handshake to complete even +when the client does not present a certificate. Note: Even if a client did +present a trusted ceritificate, for it to be useful, the server application +would still need custom code to use the verified identity to grant nondefault +access to that particular client. Some servers grant access to all clients +with certificates from a private CA, this then requires processing of +certificate revocation lists to deauthorise a client. It is often simpler and +more secure to instead keep a list of authorised public keys. +.PP +Though this is the default setting, we explicitly call the +\&\fBSSL_CTX_set_verify\fR\|(3) function and pass the \fBSSL_VERIFY_NONE\fR value to it. +The final argument to this function is a callback that you can optionally +supply to override the default handling for certificate verification. Most +applications do not need to do this so this can safely be set to NULL to get +the default handling. +.PP +.Vb 12 +\& /* +\& * Clients rarely employ certificate\-based authentication, and so we don\*(Aqt +\& * require "mutual" TLS authentication (indeed there\*(Aqs no way to know +\& * whether or how the client authenticated the server, so the term "mutual" +\& * is potentially misleading). +\& * +\& * Since we\*(Aqre not soliciting or processing client certificates, we don\*(Aqt +\& * need to configure a trusted\-certificate store, so no call to +\& * SSL_CTX_set_default_verify_paths() is needed. The server\*(Aqs own +\& * certificate chain is assumed valid. +\& */ +\& SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, NULL); +.Ve +.PP +That is all the setup that we need to do for the \fBSSL_CTX\fR. Next we create an +acceptor BIO on which to accept client connections. This just records the +intended port (and optional "host:" prefix), without actually creating the +socket. This delayed processing allows the programmer to specify additional +behaviours before the listening socket is actually created. +.PP +.Vb 10 +\& /* +\& * Create a listener socket wrapped in a BIO. +\& * The first call to BIO_do_accept() initialises the socket +\& */ +\& acceptor_bio = BIO_new_accept(hostport); +\& if (acceptor_bio == NULL) { +\& SSL_CTX_free(ctx); +\& ERR_print_errors_fp(stderr); +\& errx(res, "Error creating acceptor bio"); +\& } +.Ve +.PP +Servers almost always want to use the "SO_REUSEADDR" option to avoid startup +failures if there are still lingering client connections, so we do that before +making the \fBfirst\fR call to \fBBIO_do_accept\fR\|(3) which creates the listening +socket, without accepting a client connection. Subsequent calls to the same +function will accept new connections. +.PP +.Vb 6 +\& BIO_set_bind_mode(acceptor_bio, BIO_BIND_REUSEADDR); +\& if (BIO_do_accept(acceptor_bio) <= 0) { +\& SSL_CTX_free(ctx); +\& ERR_print_errors_fp(stderr); +\& errx(res, "Error setting up acceptor socket"); +\& } +.Ve +.SS "Server loop" +.IX Subsection "Server loop" +The server now enters a "forever" loop handling one client connection at a +time. Before each connection we clear the OpenSSL error stack, so that any +error reports are related to just the new connection. +.PP +.Vb 2 +\& /* Pristine error stack for each new connection */ +\& ERR_clear_error(); +.Ve +.PP +At this point the server blocks to accept the next client: +.PP +.Vb 5 +\& /* Wait for the next client to connect */ +\& if (BIO_do_accept(acceptor_bio) <= 0) { +\& /* Client went away before we accepted the connection */ +\& continue; +\& } +.Ve +.PP +On success the accepted client connection has been wrapped in a fresh BIO and +pushed onto the end of the acceptor BIO chain. We pop it off returning the +acceptor BIO to its initial state. +.PP +.Vb 3 +\& /* Pop the client connection from the BIO chain */ +\& client_bio = BIO_pop(acceptor_bio); +\& fprintf(stderr, "New client connection accepted\en"); +.Ve +.PP +Next, we create an \fBSSL\fR object by calling the \fBSSL_new\|(3)\fR function and +passing the \fBSSL_CTX\fR we created as an argument. The client connection BIO is +configured as the I/O conduit for this SSL handle. SSL_set_bio transfers +ownership of the BIO or BIOs involved (our \fBclient_bio\fR) to the SSL handle. +.PP +.Vb 8 +\& /* Associate a new SSL handle with the new connection */ +\& if ((ssl = SSL_new(ctx)) == NULL) { +\& ERR_print_errors_fp(stderr); +\& warnx("Error creating SSL handle for new connection"); +\& BIO_free(client_bio); +\& continue; +\& } +\& SSL_set_bio(ssl, client_bio, client_bio); +.Ve +.PP +And now we\*(Aqre ready to attempt the SSL handshake. With a blocking socket +OpenSSL will perform all the read and write operations required to complete the +handshake (or detect and report a failure) before returning. +.PP +.Vb 7 +\& /* Attempt an SSL handshake with the client */ +\& if (SSL_accept(ssl) <= 0) { +\& ERR_print_errors_fp(stderr); +\& warnx("Error performing SSL handshake with client"); +\& SSL_free(ssl); +\& continue; +\& } +.Ve +.PP +With the handshake complete, the server loops echoing client input back to the +client: +.PP +.Vb 9 +\& while (SSL_read_ex(ssl, buf, sizeof(buf), &nread) > 0) { +\& if (SSL_write_ex(ssl, buf, nread, &nwritten) > 0 && +\& nwritten == nread) { +\& total += nwritten; +\& continue; +\& } +\& warnx("Error echoing client input"); +\& break; +\& } +.Ve +.PP +Once the client closes its connection, we report the number of bytes sent to +\&\fBstderr\fR and free the SSL handle, which also frees the \fBclient_bio\fR and +closes the underlying socket. +.PP +.Vb 2 +\& fprintf(stderr, "Client connection closed, %zu bytes sent\en", total); +\& SSL_free(ssl); +.Ve +.PP +The server is now ready to accept the next client connection. +.SS "Final clean up" +.IX Subsection "Final clean up" +If the server could somehow manage to break out of the infinite loop, and +be ready to exit, it would first deallocate the constructed \fBSSL_CTX\fR. +.PP +.Vb 5 +\& /* +\& * Unreachable placeholder cleanup code, the above loop runs forever. +\& */ +\& SSL_CTX_free(ctx); +\& return EXIT_SUCCESS; +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7), +\&\fBossl\-guide\-tls\-client\-non\-block\fR\|(7), \fBossl\-guide\-quic\-client\-block\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl_store-file.7 b/static/netbsd/man7/ossl_store-file.7 new file mode 100644 index 00000000..2bbd3487 --- /dev/null +++ b/static/netbsd/man7/ossl_store-file.7 @@ -0,0 +1,118 @@ +.\" $NetBSD: ossl_store-file.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_STORE-FILE 7" +.TH OSSL_STORE-FILE 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl_store\-file \- The store \*(Aqfile\*(Aq scheme loader +.SH SYNOPSIS +.IX Header "SYNOPSIS" +#include +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for the \*(Aqfile\*(Aq scheme is built into \f(CW\*(C`libcrypto\*(C'\fR. +Since files come in all kinds of formats and content types, the \*(Aqfile\*(Aq +scheme has its own layer of functionality called "file handlers", +which are used to try to decode diverse types of file contents. +.PP +In case a file is formatted as PEM, each called file handler receives +the PEM name (everything following any \*(Aq\f(CW\*(C`\-\-\-\-\-BEGIN \*(C'\fR\*(Aq) as well as +possible PEM headers, together with the decoded PEM body. Since PEM +formatted files can contain more than one object, the file handlers +are called upon for each such object. +.PP +If the file isn\*(Aqt determined to be formatted as PEM, the content is +loaded in raw form in its entirety and passed to the available file +handlers as is, with no PEM name or headers. +.PP +Each file handler is expected to handle PEM and non\-PEM content as +appropriate. Some may refuse non\-PEM content for the sake of +determinism (for example, there are keys out in the wild that are +represented as an ASN.1 OCTET STRING. In raw form, it\*(Aqs not easily +possible to distinguish those from any other data coming as an ASN.1 +OCTET STRING, so such keys would naturally be accepted as PEM files +only). +.SH NOTES +.IX Header "NOTES" +When needed, the \*(Aqfile\*(Aq scheme loader will require a pass phrase by +using the \fBUI_METHOD\fR that was passed via \fBOSSL_STORE_open()\fR. +This pass phrase is expected to be UTF\-8 encoded, anything else will +give an undefined result. +The files made accessible through this loader are expected to be +standard compliant with regards to pass phrase encoding. +Files that aren\*(Aqt should be re\-generated with a correctly encoded pass +phrase. +See \fBpassphrase\-encoding\fR\|(7) for more information. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl_store\fR\|(7), \fBpassphrase\-encoding\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/ossl_store.7 b/static/netbsd/man7/ossl_store.7 new file mode 100644 index 00000000..1b19077b --- /dev/null +++ b/static/netbsd/man7/ossl_store.7 @@ -0,0 +1,147 @@ +.\" $NetBSD: ossl_store.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_STORE 7" +.TH OSSL_STORE 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl_store \- Store retrieval functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +#include +.SH DESCRIPTION +.IX Header "DESCRIPTION" +.SS General +.IX Subsection "General" +A STORE is a layer of functionality to retrieve a number of supported +objects from a repository of any kind, addressable as a filename or +as a URI. +.PP +The functionality supports the pattern "open a channel to the +repository", "loop and retrieve one object at a time", and "finish up +by closing the channel". +.PP +The retrieved objects are returned as a wrapper type \fBOSSL_STORE_INFO\fR, +from which an OpenSSL type can be retrieved. +.SS "URI schemes and loaders" +.IX Subsection "URI schemes and loaders" +Support for a URI scheme is called a STORE "loader", and can be added +dynamically from the calling application or from a loadable engine. +.PP +Support for the \*(Aqfile\*(Aq scheme is built into \f(CW\*(C`libcrypto\*(C'\fR. +See \fBossl_store\-file\fR\|(7) for more information. +.SS "UI_METHOD and pass phrases" +.IX Subsection "UI_METHOD and pass phrases" +The \fBOSS_STORE\fR API does nothing to enforce any specific format or +encoding on the pass phrase that the \fBUI_METHOD\fR provides. However, +the pass phrase is expected to be UTF\-8 encoded. The result of any +other encoding is undefined. +.SH EXAMPLES +.IX Header "EXAMPLES" +.SS "A generic call" +.IX Subsection "A generic call" +.Vb 2 +\& #include /* for UI_get_default_method */ +\& #include +\& +\& OSSL_STORE_CTX *ctx = OSSL_STORE_open("file:/foo/bar/data.pem", +\& UI_get_default_method(), NULL, NULL, NULL); +\& +\& /* +\& * OSSL_STORE_eof() simulates file semantics for any repository to signal +\& * that no more data can be expected +\& */ +\& while (!OSSL_STORE_eof(ctx)) { +\& OSSL_STORE_INFO *info = OSSL_STORE_load(ctx); +\& +\& /* +\& * Do whatever is necessary with the OSSL_STORE_INFO, +\& * here just one example +\& */ +\& switch (OSSL_STORE_INFO_get_type(info)) { +\& case OSSL_STORE_INFO_CERT: +\& /* Print the X.509 certificate text */ +\& X509_print_fp(stdout, OSSL_STORE_INFO_get0_CERT(info)); +\& /* Print the X.509 certificate PEM output */ +\& PEM_write_X509(stdout, OSSL_STORE_INFO_get0_CERT(info)); +\& break; +\& } +\& OSSL_STORE_INFO_free(info); +\& } +\& +\& OSSL_STORE_close(ctx); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_STORE_INFO\fR\|(3), \fBOSSL_STORE_LOADER\fR\|(3), +\&\fBOSSL_STORE_open\fR\|(3), \fBOSSL_STORE_expect\fR\|(3), +\&\fBOSSL_STORE_SEARCH\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/p.7 b/static/netbsd/man7/p.7 new file mode 100644 index 00000000..287c873d --- /dev/null +++ b/static/netbsd/man7/p.7 @@ -0,0 +1 @@ +$3 > 100 diff --git a/static/netbsd/man7/passphrase-encoding.7 b/static/netbsd/man7/passphrase-encoding.7 new file mode 100644 index 00000000..e2456d2b --- /dev/null +++ b/static/netbsd/man7/passphrase-encoding.7 @@ -0,0 +1,215 @@ +.\" $NetBSD: passphrase-encoding.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PASSPHRASE-ENCODING 7" +.TH PASSPHRASE-ENCODING 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +passphrase\-encoding +\&\- How diverse parts of OpenSSL treat pass phrases character encoding +.SH DESCRIPTION +.IX Header "DESCRIPTION" +In a modern world with all sorts of character encodings, the treatment of pass +phrases has become increasingly complex. +This manual page attempts to give an overview over how this problem is +currently addressed in different parts of the OpenSSL library. +.SS "The general case" +.IX Subsection "The general case" +The OpenSSL library doesn\*(Aqt treat pass phrases in any special way as a general +rule, and trusts the application or user to choose a suitable character set +and stick to that throughout the lifetime of affected objects. +This means that for an object that was encrypted using a pass phrase encoded in +ISO\-8859\-1, that object needs to be decrypted using a pass phrase encoded in +ISO\-8859\-1. +Using the wrong encoding is expected to cause a decryption failure. +.SS PKCS#12 +.IX Subsection "PKCS#12" +PKCS#12 is a bit different regarding pass phrase encoding. +The standard stipulates that the pass phrase shall be encoded as an ASN.1 +BMPString, which consists of the code points of the basic multilingual plane, +encoded in big endian (UCS\-2 BE). +.PP +OpenSSL tries to adapt to this requirements in one of the following manners: +.IP 1. 4 +Treats the received pass phrase as UTF\-8 encoded and tries to re\-encode it to +UTF\-16 (which is the same as UCS\-2 for characters U+0000 to U+D7FF and U+E000 +to U+FFFF, but becomes an expansion for any other character), or failing that, +proceeds with step 2. +.IP 2. 4 +Assumes that the pass phrase is encoded in ASCII or ISO\-8859\-1 and +opportunistically prepends each byte with a zero byte to obtain the UCS\-2 +encoding of the characters, which it stores as a BMPString. +.Sp +Note that since there is no check of your locale, this may produce UCS\-2 / +UTF\-16 characters that do not correspond to the original pass phrase characters +for other character sets, such as any ISO\-8859\-X encoding other than +ISO\-8859\-1 (or for Windows, CP 1252 with exception for the extra "graphical" +characters in the 0x80\-0x9F range). +.PP +OpenSSL versions older than 1.1.0 do variant 2 only, and that is the reason why +OpenSSL still does this, to be able to read files produced with older versions. +.PP +It should be noted that this approach isn\*(Aqt entirely fault free. +.PP +A pass phrase encoded in ISO\-8859\-2 could very well have a sequence such as +0xC3 0xAF (which is the two characters "LATIN CAPITAL LETTER A WITH BREVE" +and "LATIN CAPITAL LETTER Z WITH DOT ABOVE" in ISO\-8859\-2 encoding), but would +be misinterpreted as the perfectly valid UTF\-8 encoded code point U+00EF (LATIN +SMALL LETTER I WITH DIAERESIS) \fIif the pass phrase doesn\*(Aqt contain anything that +would be invalid UTF\-8\fR. +A pass phrase that contains this kind of byte sequence will give a different +outcome in OpenSSL 1.1.0 and newer than in OpenSSL older than 1.1.0. +.PP +.Vb 2 +\& 0x00 0xC3 0x00 0xAF # OpenSSL older than 1.1.0 +\& 0x00 0xEF # OpenSSL 1.1.0 and newer +.Ve +.PP +On the same accord, anything encoded in UTF\-8 that was given to OpenSSL older +than 1.1.0 was misinterpreted as ISO\-8859\-1 sequences. +.SS OSSL_STORE +.IX Subsection "OSSL_STORE" +\&\fBossl_store\fR\|(7) acts as a general interface to access all kinds of objects, +potentially protected with a pass phrase, a PIN or something else. +This API stipulates that pass phrases should be UTF\-8 encoded, and that any +other pass phrase encoding may give undefined results. +This API relies on the application to ensure UTF\-8 encoding, and doesn\*(Aqt check +that this is the case, so what it gets, it will also pass to the underlying +loader. +.SH RECOMMENDATIONS +.IX Header "RECOMMENDATIONS" +This section assumes that you know what pass phrase was used for encryption, +but that it may have been encoded in a different character encoding than the +one used by your current input method. +For example, the pass phrase may have been used at a time when your default +encoding was ISO\-8859\-1 (i.e. "naïve" resulting in the byte sequence 0x6E 0x61 +0xEF 0x76 0x65), and you\*(Aqre now in an environment where your default encoding +is UTF\-8 (i.e. "naïve" resulting in the byte sequence 0x6E 0x61 0xC3 0xAF 0x76 +0x65). +Whenever it\*(Aqs mentioned that you should use a certain character encoding, it +should be understood that you either change the input method to use the +mentioned encoding when you type in your pass phrase, or use some suitable tool +to convert your pass phrase from your default encoding to the target encoding. +.PP +Also note that the sub\-sections below discuss human readable pass phrases. +This is particularly relevant for PKCS#12 objects, where human readable pass +phrases are assumed. +For other objects, it\*(Aqs as legitimate to use any byte sequence (such as a +sequence of bytes from \fI/dev/urandom\fR that\*(Aqs been saved away), which makes any +character encoding discussion irrelevant; in such cases, simply use the same +byte sequence as it is. +.SS "Creating new objects" +.IX Subsection "Creating new objects" +For creating new pass phrase protected objects, make sure the pass phrase is +encoded using UTF\-8. +This is default on most modern Unixes, but may involve an effort on other +platforms. +Specifically for Windows, setting the environment variable +\&\fBOPENSSL_WIN32_UTF8\fR will have anything entered on [Windows] console prompt +converted to UTF\-8 (command line and separately prompted pass phrases alike). +.SS "Opening existing objects" +.IX Subsection "Opening existing objects" +For opening pass phrase protected objects where you know what character +encoding was used for the encryption pass phrase, make sure to use the same +encoding again. +.PP +For opening pass phrase protected objects where the character encoding that was +used is unknown, or where the producing application is unknown, try one of the +following: +.IP 1. 4 +Try the pass phrase that you have as it is in the character encoding of your +environment. +It\*(Aqs possible that its byte sequence is exactly right. +.IP 2. 4 +Convert the pass phrase to UTF\-8 and try with the result. +Specifically with PKCS#12, this should open up any object that was created +according to the specification. +.IP 3. 4 +Do a naïve (i.e. purely mathematical) ISO\-8859\-1 to UTF\-8 conversion and try +with the result. +This differs from the previous attempt because ISO\-8859\-1 maps directly to +U+0000 to U+00FF, which other non\-UTF\-8 character sets do not. +.Sp +This also takes care of the case when a UTF\-8 encoded string was used with +OpenSSL older than 1.1.0. +(for example, \f(CW\*(C`ï\*(C'\fR, which is 0xC3 0xAF when encoded in UTF\-8, would become 0xC3 +0x83 0xC2 0xAF when re\-encoded in the naïve manner. +The conversion to BMPString would then yield 0x00 0xC3 0x00 0xA4 0x00 0x00, the +erroneous/non\-compliant encoding used by OpenSSL older than 1.1.0) +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBossl_store\fR\|(7), +\&\fBEVP_BytesToKey\fR\|(3), \fBEVP_DecryptInit\fR\|(3), +\&\fBPEM_do_header\fR\|(3), +\&\fBPKCS12_parse\fR\|(3), \fBPKCS12_newpass\fR\|(3), +\&\fBd2i_PKCS8PrivateKey_bio\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/property.7 b/static/netbsd/man7/property.7 new file mode 100644 index 00000000..04da3fee --- /dev/null +++ b/static/netbsd/man7/property.7 @@ -0,0 +1,241 @@ +.\" $NetBSD: property.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROPERTY 7" +.TH PROPERTY 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +property \- Properties, a selection mechanism for algorithm implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +As of OpenSSL 3.0, a new method has been introduced to decide which of +multiple implementations of an algorithm will be used. +The method is centered around the concept of properties. +Each implementation defines a number of properties and when an algorithm +is being selected, filters based on these properties can be used to +choose the most appropriate implementation of the algorithm. +.PP +Properties are like variables, they are referenced by name and have a value +assigned. +.SS "Property Names" +.IX Subsection "Property Names" +Property names fall into two categories: those reserved by the OpenSSL +project and user defined names. +A \fIreserved\fR property name consists of a single C\-style identifier +(except for leading underscores not being permitted), which begins +with a letter and can be followed by any number of letters, numbers +and underscores. +Property names are case\-insensitive, but OpenSSL will only use lowercase +letters. +.PP +A \fIuser defined\fR property name is similar, but it \fBmust\fR consist of +two or more C\-style identifiers, separated by periods. +The last identifier in the name can be considered the \*(Aqtrue\*(Aq property +name, which is prefixed by some sort of \*(Aqnamespace\*(Aq. +Providers for example could include their name in the prefix and use +property names like +.PP +.Vb 2 +\& . +\& .. +.Ve +.SS Properties +.IX Subsection "Properties" +A \fIproperty\fR is a \fIname=value\fR pair. +A \fIproperty definition\fR is a sequence of comma separated properties. +There can be any number of properties in a definition, however each name must +be unique. +For example: "" defines an empty property definition (i.e., no restriction); +"my.foo=bar" defines a property named \fImy.foo\fR which has a string value \fIbar\fR +and "iteration.count=3" defines a property named \fIiteration.count\fR which +has a numeric value of \fI3\fR. +The full syntax for property definitions appears below. +.SS Implementations +.IX Subsection "Implementations" +Each implementation of an algorithm can define any number of +properties. +For example, the default provider defines the property \fIprovider=default\fR +for all of its algorithms. +Likewise, OpenSSL\*(Aqs FIPS provider defines \fIprovider=fips\fR and the legacy +provider defines \fIprovider=legacy\fR for all of their algorithms. +.SS Queries +.IX Subsection "Queries" +A \fIproperty query clause\fR is a single conditional test. +For example, "fips=yes", "provider!=default" or "?iteration.count=3". +The first two represent mandatory clauses, such clauses \fBmust\fR match +for any algorithm to even be under consideration. +The third clause represents an optional clause. +Matching such clauses is not a requirement, but any additional optional +match counts in favor of the algorithm. +More details about that in the \fBLookups\fR section. +A \fIproperty query\fR is a sequence of comma separated property query clauses. +It is an error if a property name appears in more than one query clause. +The full syntax for property queries appears below, but the available syntactic +features are: +.IP \(bu 4 +\&\fB=\fR is an infix operator providing an equality test. +.IP \(bu 4 +\&\fB!=\fR is an infix operator providing an inequality test. +.IP \(bu 4 +\&\fB?\fR is a prefix operator that means that the following clause is optional +but preferred. +.IP \(bu 4 +\&\fB\-\fR is a prefix operator that means any global query clause involving the +following property name should be ignored. +.IP \(bu 4 +\&\fB"..."\fR is a quoted string. +The quotes are not included in the body of the string. +.IP \(bu 4 +\&\fB\*(Aq...\*(Aq\fR is a quoted string. +The quotes are not included in the body of the string. +.SS Lookups +.IX Subsection "Lookups" +When an algorithm is looked up, a property query is used to determine +the best matching algorithm. +All mandatory query clauses \fBmust\fR be present and the implementation +that additionally has the largest number of matching optional query +clauses will be used. +If there is more than one such optimal candidate, the result will be +chosen from amongst those in an indeterminate way. +Ordering of optional clauses is not significant. +.SS Shortcut +.IX Subsection "Shortcut" +In order to permit a more concise expression of boolean properties, there +is one short cut: a property name alone (e.g. "my.property") is +exactly equivalent to "my.property=yes" in both definitions and queries. +.SS "Global and Local" +.IX Subsection "Global and Local" +Two levels of property query are supported. +A context based property query that applies to all fetch operations and a local +property query. +Where both the context and local queries include a clause with the same name, +the local clause overrides the context clause. +.PP +It is possible for a local property query to remove a clause in the context +property query by preceding the property name with a \*(Aq\-\*(Aq. +For example, a context property query that contains "fips=yes" would normally +result in implementations that have "fips=yes". +.PP +However, if the setting of the "fips" property is irrelevant to the +operations being performed, the local property query can include the +clause "\-fips". +Note that the local property query could not use "fips=no" because that would +disallow any implementations with "fips=yes" rather than not caring about the +setting. +.SH "PREDEFINED NAMES" +.IX Header "PREDEFINED NAMES" +Currently known predefined names are: +.ie n .IP """provider""" 4 +.el .IP \f(CWprovider\fR 4 +.IX Item "provider" +The conventional property value is the provider\*(Aqs name. This may be different from the name returned by \fBOSSL_PROVIDER_get0_name\fR\|(3). +.Sp +It is a convention among OpenSSL provider implementations to define a property with this name. It is not mandatory to do this. +.ie n .IP """version""" 4 +.el .IP \f(CWversion\fR 4 +.IX Item "version" +The conventional property value is the provider\*(Aqs version. +.Sp +OpenSSL provider implementations do not define a property with this name. +.ie n .IP """fips""" 4 +.el .IP \f(CWfips\fR 4 +.IX Item "fips" +The conventional property value is boolean (\f(CW"yes"\fR or \f(CW"no"\fR), indication whether the implementation conforms to FIPS standards or not. +.Sp +It is a convention among OpenSSL provider implementations to define a property with this name where applicable. It is not mandatory to do this, but is strongly recommended. +.ie n .IP """output"", ""input"", ""structure""" 4 +.el .IP "\f(CWoutput\fR, \f(CWinput\fR, \f(CWstructure\fR" 4 +.IX Item "output, input, structure" +Properties with these names are used by encoders (see \fBprovider\-encoder\fR\|(7)) and decoders (see \fBprovider\-decoder\fR\|(7)). +.SH SYNTAX +.IX Header "SYNTAX" +The lexical syntax in EBNF is given by: +.PP +.Vb 11 +\& Definition ::= PropertyName ( \*(Aq=\*(Aq Value )? +\& ( \*(Aq,\*(Aq PropertyName ( \*(Aq=\*(Aq Value )? )* +\& Query ::= PropertyQuery ( \*(Aq,\*(Aq PropertyQuery )* +\& PropertyQuery ::= \*(Aq\-\*(Aq PropertyName +\& | \*(Aq?\*(Aq? ( PropertyName (( \*(Aq=\*(Aq | \*(Aq!=\*(Aq ) Value)?) +\& Value ::= NumberLiteral | StringLiteral +\& StringLiteral ::= QuotedString | UnquotedString +\& QuotedString ::= \*(Aq"\*(Aq [^"]* \*(Aq"\*(Aq | "\*(Aq" [^\*(Aq]* "\*(Aq" +\& UnquotedString ::= [A\-Za\-z] [^{space},]+ +\& NumberLiteral ::= \*(Aq0\*(Aq ( [0\-7]* | \*(Aqx\*(Aq [0\-9A\-Fa\-f]+ ) | \*(Aq\-\*(Aq? [1\-9] [0\-9]+ +\& PropertyName ::= [A\-Za\-z] [A\-Za\-z0\-9_]* ( \*(Aq.\*(Aq [A\-Za\-z] [A\-Za\-z0\-9_]* )* +.Ve +.PP +The flavour of EBNF being used is defined by: +. +.SH HISTORY +.IX Header "HISTORY" +Properties were added in OpenSSL 3.0 +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-asym_cipher.7 b/static/netbsd/man7/provider-asym_cipher.7 new file mode 100644 index 00000000..ff6fedc6 --- /dev/null +++ b/static/netbsd/man7/provider-asym_cipher.7 @@ -0,0 +1,335 @@ +.\" $NetBSD: provider-asym_cipher.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-ASYM_CIPHER 7" +.TH PROVIDER-ASYM_CIPHER 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-asym_cipher \- The asym_cipher library <\-> provider functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_asym_cipher_newctx(void *provctx); +\& void OSSL_FUNC_asym_cipher_freectx(void *ctx); +\& void *OSSL_FUNC_asym_cipher_dupctx(void *ctx); +\& +\& /* Encryption */ +\& int OSSL_FUNC_asym_cipher_encrypt_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_asym_cipher_encrypt(void *ctx, unsigned char *out, size_t *outlen, +\& size_t outsize, const unsigned char *in, +\& size_t inlen); +\& +\& /* Decryption */ +\& int OSSL_FUNC_asym_cipher_decrypt_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_asym_cipher_decrypt(void *ctx, unsigned char *out, size_t *outlen, +\& size_t outsize, const unsigned char *in, +\& size_t inlen); +\& +\& /* Asymmetric Cipher parameters */ +\& int OSSL_FUNC_asym_cipher_get_ctx_params(void *ctx, OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_asym_cipher_gettable_ctx_params(void *provctx); +\& int OSSL_FUNC_asym_cipher_set_ctx_params(void *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_asym_cipher_settable_ctx_params(void *provctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The asymmetric cipher (OSSL_OP_ASYM_CIPHER) operation enables providers to +implement asymmetric cipher algorithms and make them available to applications +via the API functions \fBEVP_PKEY_encrypt\fR\|(3), +\&\fBEVP_PKEY_decrypt\fR\|(3) and +other related functions). +.PP +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via +\&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider\*(Aqs +\&\fBprovider_query_operation()\fR function +(see "Provider Functions" in \fBprovider\-base\fR\|(7)). +.PP +All these "functions" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the "function" \fBOSSL_FUNC_asym_cipher_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_asym_cipher_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_asym_cipher_newctx_fn +\& OSSL_FUNC_asym_cipher_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_asym_cipher_newctx OSSL_FUNC_ASYM_CIPHER_NEWCTX +\& OSSL_FUNC_asym_cipher_freectx OSSL_FUNC_ASYM_CIPHER_FREECTX +\& OSSL_FUNC_asym_cipher_dupctx OSSL_FUNC_ASYM_CIPHER_DUPCTX +\& +\& OSSL_FUNC_asym_cipher_encrypt_init OSSL_FUNC_ASYM_CIPHER_ENCRYPT_INIT +\& OSSL_FUNC_asym_cipher_encrypt OSSL_FUNC_ASYM_CIPHER_ENCRYPT +\& +\& OSSL_FUNC_asym_cipher_decrypt_init OSSL_FUNC_ASYM_CIPHER_DECRYPT_INIT +\& OSSL_FUNC_asym_cipher_decrypt OSSL_FUNC_ASYM_CIPHER_DECRYPT +\& +\& OSSL_FUNC_asym_cipher_get_ctx_params OSSL_FUNC_ASYM_CIPHER_GET_CTX_PARAMS +\& OSSL_FUNC_asym_cipher_gettable_ctx_params OSSL_FUNC_ASYM_CIPHER_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_asym_cipher_set_ctx_params OSSL_FUNC_ASYM_CIPHER_SET_CTX_PARAMS +\& OSSL_FUNC_asym_cipher_settable_ctx_params OSSL_FUNC_ASYM_CIPHER_SETTABLE_CTX_PARAMS +.Ve +.PP +An asymmetric cipher algorithm implementation may not implement all of these +functions. +In order to be a consistent set of functions a provider must implement +OSSL_FUNC_asym_cipher_newctx and OSSL_FUNC_asym_cipher_freectx. +It must also implement both of OSSL_FUNC_asym_cipher_encrypt_init and +OSSL_FUNC_asym_cipher_encrypt, or both of OSSL_FUNC_asym_cipher_decrypt_init and +OSSL_FUNC_asym_cipher_decrypt. +OSSL_FUNC_asym_cipher_get_ctx_params is optional but if it is present then so must +OSSL_FUNC_asym_cipher_gettable_ctx_params. +Similarly, OSSL_FUNC_asym_cipher_set_ctx_params is optional but if it is present then +so must OSSL_FUNC_asym_cipher_settable_ctx_params. +.PP +An asymmetric cipher algorithm must also implement some mechanism for generating, +loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation. +See \fBprovider\-keymgmt\fR\|(7) for further details. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_asym_cipher_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during an asymmetric cipher operation. +A pointer to this context will be passed back in a number of the other +asymmetric cipher operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +.PP +\&\fBOSSL_FUNC_asym_cipher_freectx()\fR is passed a pointer to the provider side asymmetric +cipher context in the \fIctx\fR parameter. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_asym_cipher_dupctx()\fR should duplicate the provider side asymmetric cipher +context in the \fIctx\fR parameter and return the duplicate copy. +.SS "Encryption Functions" +.IX Subsection "Encryption Functions" +\&\fBOSSL_FUNC_asym_cipher_encrypt_init()\fR initialises a context for an asymmetric encryption +given a provider side asymmetric cipher context in the \fIctx\fR parameter, and a +pointer to a provider key object in the \fIprovkey\fR parameter. +The \fIparams\fR, if not NULL, should be set on the context in a manner similar to +using \fBOSSL_FUNC_asym_cipher_set_ctx_params()\fR. +The key object should have been previously generated, loaded or imported into +the provider using the key management (OSSL_OP_KEYMGMT) operation (see \fBprovider\-keymgmt\fR\|(7)). +\&\fBOSSL_FUNC_asym_cipher_encrypt()\fR performs the actual encryption itself. +A previously initialised asymmetric cipher context is passed in the \fIctx\fR +parameter. +The data to be encrypted is pointed to by the \fIin\fR parameter which is \fIinlen\fR +bytes long. +Unless \fIout\fR is NULL, the encrypted data should be written to the location +pointed to by the \fIout\fR parameter and it should not exceed \fIoutsize\fR bytes in +length. +The length of the encrypted data should be written to \fI*outlen\fR. +If \fIout\fR is NULL then the maximum length of the encrypted data should be +written to \fI*outlen\fR. +.SS "Decryption Functions" +.IX Subsection "Decryption Functions" +\&\fBOSSL_FUNC_asym_cipher_decrypt_init()\fR initialises a context for an asymmetric decryption +given a provider side asymmetric cipher context in the \fIctx\fR parameter, and a +pointer to a provider key object in the \fIprovkey\fR parameter. +The \fIparams\fR, if not NULL, should be set on the context in a manner similar to +using \fBOSSL_FUNC_asym_cipher_set_ctx_params()\fR. +The key object should have been previously generated, loaded or imported into +the provider using the key management (OSSL_OP_KEYMGMT) operation (see +\&\fBprovider\-keymgmt\fR\|(7)). +.PP +\&\fBOSSL_FUNC_asym_cipher_decrypt()\fR performs the actual decryption itself. +A previously initialised asymmetric cipher context is passed in the \fIctx\fR +parameter. +The data to be decrypted is pointed to by the \fIin\fR parameter which is \fIinlen\fR +bytes long. +Unless \fIout\fR is NULL, the decrypted data should be written to the location +pointed to by the \fIout\fR parameter and it should not exceed \fIoutsize\fR bytes in +length. +The length of the decrypted data should be written to \fI*outlen\fR. +If \fIout\fR is NULL then the maximum length of the decrypted data should be +written to \fI*outlen\fR. +.SS "Asymmetric Cipher Parameters" +.IX Subsection "Asymmetric Cipher Parameters" +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by +the \fBOSSL_FUNC_asym_cipher_get_ctx_params()\fR and \fBOSSL_FUNC_asym_cipher_set_ctx_params()\fR +functions. +.PP +\&\fBOSSL_FUNC_asym_cipher_get_ctx_params()\fR gets asymmetric cipher parameters associated +with the given provider side asymmetric cipher context \fIctx\fR and stores them in +\&\fIparams\fR. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_asym_cipher_set_ctx_params()\fR sets the asymmetric cipher parameters associated +with the given provider side asymmetric cipher context \fIctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing NULL for \fIparams\fR should return true. +.PP +Parameters currently recognised by built\-in asymmetric cipher algorithms are as +follows. +Not all parameters are relevant to, or are understood by all asymmetric cipher +algorithms: +.IP """pad\-mode"" (\fBOSSL_ASYM_CIPHER_PARAM_PAD_MODE\fR) OR " 4 +.IX Item """pad-mode"" (OSSL_ASYM_CIPHER_PARAM_PAD_MODE) OR " +The type of padding to be used. The interpretation of this value will depend +on the algorithm in use. +.IP """digest"" (\fBOSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST) " +Gets or sets the name of the OAEP digest algorithm used when OAEP padding is in +use. +.IP """digest"" (\fBOSSL_ASYM_CIPHER_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_ASYM_CIPHER_PARAM_DIGEST) " +Gets or sets the name of the digest algorithm used by the algorithm (where +applicable). +.IP """digest\-props"" (\fBOSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS\fR) " 4 +.IX Item """digest-props"" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS) " +Gets or sets the properties to use when fetching the OAEP digest algorithm. +.IP """digest\-props"" (\fBOSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS\fR) " 4 +.IX Item """digest-props"" (OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS) " +Gets or sets the properties to use when fetching the cipher digest algorithm. +.IP """mgf1\-digest"" (\fBOSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST\fR) " 4 +.IX Item """mgf1-digest"" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST) " +Gets or sets the name of the MGF1 digest algorithm used when OAEP or PSS padding +is in use. +.IP """mgf1\-digest\-props"" (\fBOSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS\fR) " 4 +.IX Item """mgf1-digest-props"" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS) " +Gets or sets the properties to use when fetching the MGF1 digest algorithm. +.IP """oaep\-label"" (\fBOSSL_ASYM_CIPHER_PARAM_OAEP_LABEL\fR) " 4 +.IX Item """oaep-label"" (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) " +Gets the OAEP label used when OAEP padding is in use. +.IP """oaep\-label"" (\fBOSSL_ASYM_CIPHER_PARAM_OAEP_LABEL\fR) " 4 +.IX Item """oaep-label"" (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) " +Sets the OAEP label used when OAEP padding is in use. +.IP """tls\-client\-version"" (\fBOSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION\fR) " 4 +.IX Item """tls-client-version"" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) " +The TLS protocol version first requested by the client. +.IP """tls\-negotiated\-version"" (\fBOSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION\fR) " 4 +.IX Item """tls-negotiated-version"" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) " +The negotiated TLS protocol version. +.IP """implicit\-rejection"" (\fBOSSL_ASYM_CIPHER_PARAM_IMPLICIT_REJECTION\fR) " 4 +.IX Item """implicit-rejection"" (OSSL_ASYM_CIPHER_PARAM_IMPLICIT_REJECTION) " +Gets or sets the use of the implicit rejection mechanism for RSA PKCS#1 v1.5 +decryption. When set (non zero value), the decryption API will return +a deterministically random value if the PKCS#1 v1.5 padding check fails. +This makes exploitation of the Bleichenbacher significantly harder, even +if the code using the RSA decryption API is not implemented in side\-channel +free manner. Set by default in OpenSSL providers. +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_ASYM_CIPHER_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_ASYM_CIPHER_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling either \fBOSSL_FUNC_asym_cipher_encrypt()\fR or +\&\fBOSSL_FUNC_asym_cipher_decrypt()\fR. It may return 0 if "key\-check" is set to 0. +.IP """key\-check"" (\fBOSSL_ASYM_CIPHER_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_ASYM_CIPHER_PARAM_FIPS_KEY_CHECK) " +If required this parameter should be set using either +\&\fBOSSL_FUNC_asym_cipher_encrypt_init()\fR or \fBOSSL_FUNC_asym_cipher_decrypt_init()\fR. +The default value of 1 causes an error during the init if the key is not FIPS +approved (e.g. The key has a security strength of less than 112 bits). Setting +this to 0 will ignore the error and set the approved "fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.PP +\&\fBOSSL_FUNC_asym_cipher_gettable_ctx_params()\fR and \fBOSSL_FUNC_asym_cipher_settable_ctx_params()\fR +get a constant \fBOSSL_PARAM\fR\|(3) array that describes the gettable and settable +parameters, i.e. parameters that can be used with \fBOSSL_FUNC_asym_cipherget_ctx_params()\fR +and \fBOSSL_FUNC_asym_cipher_set_ctx_params()\fR respectively. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_asym_cipher_newctx()\fR and \fBOSSL_FUNC_asym_cipher_dupctx()\fR should return the newly +created provider side asymmetric cipher context, or NULL on failure. +.PP +All other functions should return 1 for success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The provider ASYM_CIPHER interface was introduced in OpenSSL 3.0. +The Asymmetric Cipher Parameters "fips\-indicator" and "key\-check" +were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-base.7 b/static/netbsd/man7/provider-base.7 new file mode 100644 index 00000000..63bab8f1 --- /dev/null +++ b/static/netbsd/man7/provider-base.7 @@ -0,0 +1,1035 @@ +.\" $NetBSD: provider-base.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-BASE 7" +.TH PROVIDER-BASE 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-base +\&\- The basic OpenSSL library <\-> provider functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Functions offered by libcrypto to the providers */ +\& const OSSL_ITEM *core_gettable_params(const OSSL_CORE_HANDLE *handle); +\& int core_get_params(const OSSL_CORE_HANDLE *handle, OSSL_PARAM params[]); +\& +\& typedef void (*OSSL_thread_stop_handler_fn)(void *arg); +\& int core_thread_start(const OSSL_CORE_HANDLE *handle, +\& OSSL_thread_stop_handler_fn handfn, +\& void *arg); +\& +\& OPENSSL_CORE_CTX *core_get_libctx(const OSSL_CORE_HANDLE *handle); +\& void core_new_error(const OSSL_CORE_HANDLE *handle); +\& void core_set_error_debug(const OSSL_CORE_HANDLE *handle, +\& const char *file, int line, const char *func); +\& void core_vset_error(const OSSL_CORE_HANDLE *handle, +\& uint32_t reason, const char *fmt, va_list args); +\& +\& int core_obj_add_sigid(const OSSL_CORE_HANDLE *prov, const char *sign_name, +\& const char *digest_name, const char *pkey_name); +\& int core_obj_create(const OSSL_CORE_HANDLE *handle, const char *oid, +\& const char *sn, const char *ln); +\& +\& /* +\& * Some OpenSSL functionality is directly offered to providers via +\& * dispatch +\& */ +\& void *CRYPTO_malloc(size_t num, const char *file, int line); +\& void *CRYPTO_zalloc(size_t num, const char *file, int line); +\& void CRYPTO_free(void *ptr, const char *file, int line); +\& void CRYPTO_clear_free(void *ptr, size_t num, +\& const char *file, int line); +\& void *CRYPTO_realloc(void *addr, size_t num, +\& const char *file, int line); +\& void *CRYPTO_clear_realloc(void *addr, size_t old_num, size_t num, +\& const char *file, int line); +\& void *CRYPTO_secure_malloc(size_t num, const char *file, int line); +\& void *CRYPTO_secure_zalloc(size_t num, const char *file, int line); +\& void CRYPTO_secure_free(void *ptr, const char *file, int line); +\& void CRYPTO_secure_clear_free(void *ptr, size_t num, +\& const char *file, int line); +\& int CRYPTO_secure_allocated(const void *ptr); +\& void OPENSSL_cleanse(void *ptr, size_t len); +\& +\& unsigned char *OPENSSL_hexstr2buf(const char *str, long *buflen); +\& +\& OSSL_CORE_BIO *BIO_new_file(const char *filename, const char *mode); +\& OSSL_CORE_BIO *BIO_new_membuf(const void *buf, int len); +\& int BIO_read_ex(OSSL_CORE_BIO *bio, void *data, size_t data_len, +\& size_t *bytes_read); +\& int BIO_write_ex(OSSL_CORE_BIO *bio, const void *data, size_t data_len, +\& size_t *written); +\& int BIO_up_ref(OSSL_CORE_BIO *bio); +\& int BIO_free(OSSL_CORE_BIO *bio); +\& int BIO_vprintf(OSSL_CORE_BIO *bio, const char *format, va_list args); +\& int BIO_vsnprintf(char *buf, size_t n, const char *fmt, va_list args); +\& +\& void OSSL_SELF_TEST_set_callback(OSSL_LIB_CTX *libctx, OSSL_CALLBACK *cb, +\& void *cbarg); +\& +\& size_t get_entropy(const OSSL_CORE_HANDLE *handle, +\& unsigned char **pout, int entropy, +\& size_t min_len, size_t max_len); +\& size_t get_user_entropy(const OSSL_CORE_HANDLE *handle, +\& unsigned char **pout, int entropy, +\& size_t min_len, size_t max_len); +\& void cleanup_entropy(const OSSL_CORE_HANDLE *handle, +\& unsigned char *buf, size_t len); +\& void cleanup_user_entropy(const OSSL_CORE_HANDLE *handle, +\& unsigned char *buf, size_t len); +\& size_t get_nonce(const OSSL_CORE_HANDLE *handle, +\& unsigned char **pout, size_t min_len, size_t max_len, +\& const void *salt, size_t salt_len); +\& size_t get_user_nonce(const OSSL_CORE_HANDLE *handle, +\& unsigned char **pout, size_t min_len, size_t max_len, +\& const void *salt, size_t salt_len); +\& void cleanup_nonce(const OSSL_CORE_HANDLE *handle, +\& unsigned char *buf, size_t len); +\& void cleanup_user_nonce(const OSSL_CORE_HANDLE *handle, +\& unsigned char *buf, size_t len); +\& +\& /* Functions for querying the providers in the application library context */ +\& int provider_register_child_cb(const OSSL_CORE_HANDLE *handle, +\& int (*create_cb)(const OSSL_CORE_HANDLE *provider, +\& void *cbdata), +\& int (*remove_cb)(const OSSL_CORE_HANDLE *provider, +\& void *cbdata), +\& int (*global_props_cb)(const char *props, void *cbdata), +\& void *cbdata); +\& void provider_deregister_child_cb(const OSSL_CORE_HANDLE *handle); +\& const char *provider_name(const OSSL_CORE_HANDLE *prov); +\& void *provider_get0_provider_ctx(const OSSL_CORE_HANDLE *prov); +\& const OSSL_DISPATCH *provider_get0_dispatch(const OSSL_CORE_HANDLE *prov); +\& int provider_up_ref(const OSSL_CORE_HANDLE *prov, int activate); +\& int provider_free(const OSSL_CORE_HANDLE *prov, int deactivate); +\& +\& /* Functions offered by the provider to libcrypto */ +\& void provider_teardown(void *provctx); +\& const OSSL_ITEM *provider_gettable_params(void *provctx); +\& int provider_get_params(void *provctx, OSSL_PARAM params[]); +\& const OSSL_ALGORITHM *provider_query_operation(void *provctx, +\& int operation_id, +\& const int *no_store); +\& void provider_unquery_operation(void *provctx, int operation_id, +\& const OSSL_ALGORITHM *algs); +\& const OSSL_ITEM *provider_get_reason_strings(void *provctx); +\& int provider_get_capabilities(void *provctx, const char *capability, +\& OSSL_CALLBACK *cb, void *arg); +\& int provider_self_test(void *provctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays, in the call +of the provider initialization function. See "Provider" in \fBprovider\fR\|(7) +for a description of the initialization function. They are known as "upcalls". +.PP +All these "functions" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from a \fBOSSL_DISPATCH\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the "function" \fBcore_gettable_params()\fR has these: +.PP +.Vb 4 +\& typedef OSSL_PARAM * +\& (OSSL_FUNC_core_gettable_params_fn)(const OSSL_CORE_HANDLE *handle); +\& static ossl_inline OSSL_NAME_core_gettable_params_fn +\& OSSL_FUNC_core_gettable_params(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\fBOSSL_DISPATCH\fR\|(3) array entries contain a \fIfunction_id\fR field that +identifies the function. The \fIfunction_id\fR numbers are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +For \fIin\fR (the \fBOSSL_DISPATCH\fR\|(3) array passed from \fIlibcrypto\fR to the +provider): +.PP +.Vb 10 +\& core_gettable_params OSSL_FUNC_CORE_GETTABLE_PARAMS +\& core_get_params OSSL_FUNC_CORE_GET_PARAMS +\& core_thread_start OSSL_FUNC_CORE_THREAD_START +\& core_get_libctx OSSL_FUNC_CORE_GET_LIBCTX +\& core_new_error OSSL_FUNC_CORE_NEW_ERROR +\& core_set_error_debug OSSL_FUNC_CORE_SET_ERROR_DEBUG +\& core_vset_error OSSL_FUNC_CORE_VSET_ERROR +\& core_set_error_mark OSSL_FUNC_CORE_SET_ERROR_MARK +\& core_clear_last_error_mark OSSL_FUNC_CORE_CLEAR_LAST_ERROR_MARK +\& core_pop_error_to_mark OSSL_FUNC_CORE_POP_ERROR_TO_MARK +\& core_count_to_mark OSSL_FUNC_CORE_COUNT_TO_MARK +\& core_obj_add_sigid OSSL_FUNC_CORE_OBJ_ADD_SIGID +\& core_obj_create OSSL_FUNC_CORE_OBJ_CREATE +\& CRYPTO_malloc OSSL_FUNC_CRYPTO_MALLOC +\& CRYPTO_zalloc OSSL_FUNC_CRYPTO_ZALLOC +\& CRYPTO_free OSSL_FUNC_CRYPTO_FREE +\& CRYPTO_clear_free OSSL_FUNC_CRYPTO_CLEAR_FREE +\& CRYPTO_realloc OSSL_FUNC_CRYPTO_REALLOC +\& CRYPTO_clear_realloc OSSL_FUNC_CRYPTO_CLEAR_REALLOC +\& CRYPTO_secure_malloc OSSL_FUNC_CRYPTO_SECURE_MALLOC +\& CRYPTO_secure_zalloc OSSL_FUNC_CRYPTO_SECURE_ZALLOC +\& CRYPTO_secure_free OSSL_FUNC_CRYPTO_SECURE_FREE +\& CRYPTO_secure_clear_free OSSL_FUNC_CRYPTO_SECURE_CLEAR_FREE +\& CRYPTO_secure_allocated OSSL_FUNC_CRYPTO_SECURE_ALLOCATED +\& BIO_new_file OSSL_FUNC_BIO_NEW_FILE +\& BIO_new_mem_buf OSSL_FUNC_BIO_NEW_MEMBUF +\& BIO_read_ex OSSL_FUNC_BIO_READ_EX +\& BIO_write_ex OSSL_FUNC_BIO_WRITE_EX +\& BIO_up_ref OSSL_FUNC_BIO_UP_REF +\& BIO_free OSSL_FUNC_BIO_FREE +\& BIO_vprintf OSSL_FUNC_BIO_VPRINTF +\& BIO_vsnprintf OSSL_FUNC_BIO_VSNPRINTF +\& BIO_puts OSSL_FUNC_BIO_PUTS +\& BIO_gets OSSL_FUNC_BIO_GETS +\& BIO_ctrl OSSL_FUNC_BIO_CTRL +\& OPENSSL_cleanse OSSL_FUNC_OPENSSL_CLEANSE +\& OSSL_SELF_TEST_set_callback OSSL_FUNC_SELF_TEST_CB +\& ossl_rand_get_entropy OSSL_FUNC_GET_ENTROPY +\& ossl_rand_get_user_entropy OSSL_FUNC_GET_USER_ENTROPY +\& ossl_rand_cleanup_entropy OSSL_FUNC_CLEANUP_ENTROPY +\& ossl_rand_cleanup_user_entropy OSSL_FUNC_CLEANUP_USER_ENTROPY +\& ossl_rand_get_nonce OSSL_FUNC_GET_NONCE +\& ossl_rand_get_user_nonce OSSL_FUNC_GET_USER_NONCE +\& ossl_rand_cleanup_nonce OSSL_FUNC_CLEANUP_NONCE +\& ossl_rand_cleanup_user_nonce OSSL_FUNC_CLEANUP_USER_NONCE +\& provider_register_child_cb OSSL_FUNC_PROVIDER_REGISTER_CHILD_CB +\& provider_deregister_child_cb OSSL_FUNC_PROVIDER_DEREGISTER_CHILD_CB +\& provider_name OSSL_FUNC_PROVIDER_NAME +\& provider_get0_provider_ctx OSSL_FUNC_PROVIDER_GET0_PROVIDER_CTX +\& provider_get0_dispatch OSSL_FUNC_PROVIDER_GET0_DISPATCH +\& provider_up_ref OSSL_FUNC_PROVIDER_UP_REF +\& provider_free OSSL_FUNC_PROVIDER_FREE +.Ve +.PP +For \fI*out\fR (the \fBOSSL_DISPATCH\fR\|(3) array passed from the provider to +\&\fIlibcrypto\fR): +.PP +.Vb 8 +\& provider_teardown OSSL_FUNC_PROVIDER_TEARDOWN +\& provider_gettable_params OSSL_FUNC_PROVIDER_GETTABLE_PARAMS +\& provider_get_params OSSL_FUNC_PROVIDER_GET_PARAMS +\& provider_query_operation OSSL_FUNC_PROVIDER_QUERY_OPERATION +\& provider_unquery_operation OSSL_FUNC_PROVIDER_UNQUERY_OPERATION +\& provider_get_reason_strings OSSL_FUNC_PROVIDER_GET_REASON_STRINGS +\& provider_get_capabilities OSSL_FUNC_PROVIDER_GET_CAPABILITIES +\& provider_self_test OSSL_FUNC_PROVIDER_SELF_TEST +.Ve +.SS "Core functions" +.IX Subsection "Core functions" +\&\fBcore_gettable_params()\fR returns a constant array of descriptor +\&\fBOSSL_PARAM\fR\|(3), for parameters that \fBcore_get_params()\fR can handle. +.PP +\&\fBcore_get_params()\fR retrieves parameters from the core for the given \fIhandle\fR. +See "Core parameters" below for a description of currently known +parameters. +.PP +The \fBcore_thread_start()\fR function informs the core that the provider has stated +an interest in the current thread. The core will inform the provider when the +thread eventually stops. It must be passed the \fIhandle\fR for this provider, as +well as a callback \fIhandfn\fR which will be called when the thread stops. The +callback will subsequently be called, with the supplied argument \fIarg\fR, from +the thread that is stopping and gets passed the provider context as an +argument. This may be useful to perform thread specific clean up such as +freeing thread local variables. +.PP +\&\fBcore_get_libctx()\fR retrieves the core context in which the library +object for the current provider is stored, accessible through the \fIhandle\fR. +This function is useful only for built\-in providers such as the default +provider. Never cast this to OSSL_LIB_CTX in a provider that is not +built\-in as the OSSL_LIB_CTX of the library loading the provider might be +a completely different structure than the OSSL_LIB_CTX of the library the +provider is linked to. Use \fBOSSL_LIB_CTX_new_child\fR\|(3) instead to obtain +a proper library context that is linked to the application library context. +.PP +\&\fBcore_new_error()\fR, \fBcore_set_error_debug()\fR and \fBcore_vset_error()\fR are +building blocks for reporting an error back to the core, with +reference to the \fIhandle\fR. +.IP \fBcore_new_error()\fR 4 +.IX Item "core_new_error()" +allocates a new thread specific error record. +.Sp +This corresponds to the OpenSSL function \fBERR_new\fR\|(3). +.IP \fBcore_set_error_debug()\fR 4 +.IX Item "core_set_error_debug()" +sets debugging information in the current thread specific error +record. +The debugging information includes the name of the file \fIfile\fR, the +line \fIline\fR and the function name \fIfunc\fR where the error occurred. +.Sp +This corresponds to the OpenSSL function \fBERR_set_debug\fR\|(3). +.IP \fBcore_vset_error()\fR 4 +.IX Item "core_vset_error()" +sets the \fIreason\fR for the error, along with any addition data. +The \fIreason\fR is a number defined by the provider and used to index +the reason strings table that\*(Aqs returned by +\&\fBprovider_get_reason_strings()\fR. +The additional data is given as a format string \fIfmt\fR and a set of +arguments \fIargs\fR, which are treated in the same manner as with +\&\fBBIO_vsnprintf()\fR. +\&\fIfile\fR and \fIline\fR may also be passed to indicate exactly where the +error occurred or was reported. +.Sp +This corresponds to the OpenSSL function \fBERR_vset_error\fR\|(3). +.IP \fBcore_set_error_mark()\fR 4 +.IX Item "core_set_error_mark()" +sets a mark on the current topmost error record if there is one. +.Sp +This corresponds to the OpenSSL function \fBERR_set_mark\fR\|(3). +.IP \fBcore_clear_last_error_mark()\fR 4 +.IX Item "core_clear_last_error_mark()" +removes the last mark added if there is one. +.Sp +This corresponds to the OpenSSL function \fBERR_clear_last_mark\fR\|(3). +.IP \fBcore_pop_error_to_mark()\fR 4 +.IX Item "core_pop_error_to_mark()" +pops the top of the error stack until a mark is found. The mark is then removed. +If there is no mark, the whole stack is removed. +.Sp +This corresponds to the OpenSSL function \fBERR_pop_to_mark\fR\|(3). +.IP \fBcore_count_to_mark()\fR 4 +.IX Item "core_count_to_mark()" +returns the number of entries on the error stack above the most recently +marked entry, not including that entry. If there is no mark in the error stack, +the number of entries in the error stack is returned. +.Sp +This corresponds to the OpenSSL function \fBERR_count_to_mark\fR\|(3). +.PP +The \fBcore_obj_create()\fR function registers a new OID and associated short name +\&\fIsn\fR and long name \fIln\fR for the given \fIhandle\fR. It is similar to the OpenSSL +function \fBOBJ_create\fR\|(3) except that it returns 1 on success or 0 on failure. +It will treat as success the case where the OID already exists (even if the +short name \fIsn\fR or long name \fIln\fR provided as arguments differ from those +associated with the existing OID, in which case the new names are not +associated). +.PP +The \fBcore_obj_add_sigid()\fR function registers a new composite signature algorithm +(\fIsign_name\fR) consisting of an underlying signature algorithm (\fIpkey_name\fR) +and digest algorithm (\fIdigest_name\fR) for the given \fIhandle\fR. It assumes that +the OIDs for the composite signature algorithm as well as for the underlying +signature and digest algorithms are either already known to OpenSSL or have been +registered via a call to \fBcore_obj_create()\fR. It corresponds to the OpenSSL +function \fBOBJ_add_sigid\fR\|(3), except that the objects are identified by name +rather than a numeric NID. Any name (OID, short name or long name) can be used +to identify the object. It will treat as success the case where the composite +signature algorithm already exists (even if registered against a different +underlying signature or digest algorithm). For \fIdigest_name\fR, NULL or an +empty string is permissible for signature algorithms that do not need a digest +to operate correctly. The function returns 1 on success or 0 on failure. +.PP +\&\fBCRYPTO_malloc()\fR, \fBCRYPTO_zalloc()\fR, \fBCRYPTO_free()\fR, \fBCRYPTO_clear_free()\fR, +\&\fBCRYPTO_realloc()\fR, \fBCRYPTO_clear_realloc()\fR, \fBCRYPTO_secure_malloc()\fR, +\&\fBCRYPTO_secure_zalloc()\fR, \fBCRYPTO_secure_free()\fR, +\&\fBCRYPTO_secure_clear_free()\fR, \fBCRYPTO_secure_allocated()\fR, +\&\fBBIO_new_file()\fR, \fBBIO_new_mem_buf()\fR, \fBBIO_read_ex()\fR, \fBBIO_write_ex()\fR, \fBBIO_up_ref()\fR, +\&\fBBIO_free()\fR, \fBBIO_vprintf()\fR, \fBBIO_vsnprintf()\fR, \fBBIO_gets()\fR, \fBBIO_puts()\fR, +\&\fBBIO_ctrl()\fR, \fBOPENSSL_cleanse()\fR and +\&\fBOPENSSL_hexstr2buf()\fR correspond exactly to the public functions with +the same name. As a matter of fact, the pointers in the \fBOSSL_DISPATCH\fR\|(3) +array are typically direct pointers to those public functions. Note that the BIO +functions take an \fBOSSL_CORE_BIO\fR type rather than the standard \fBBIO\fR +type. This is to ensure that a provider does not mix BIOs from the core +with BIOs used on the provider side (the two are not compatible). +\&\fBOSSL_SELF_TEST_set_callback()\fR is used to set an optional callback that can be +passed into a provider. This may be ignored by a provider. +.PP +\&\fBget_entropy()\fR retrieves seeding material from the operating system. +The seeding material will have at least \fIentropy\fR bytes of randomness and the +output will have at least \fImin_len\fR and at most \fImax_len\fR bytes. +The buffer address is stored in \fI*pout\fR and the buffer length is +returned to the caller. On error, zero is returned. +.PP +\&\fBget_user_entropy()\fR is the same as \fBget_entropy()\fR except that it will +attempt to gather seed material via the seed source specified by a call to +\&\fBRAND_set_seed_source_type\fR\|(3) or via "Random Configuration" in \fBconfig\fR\|(5). +.PP +\&\fBcleanup_entropy()\fR is used to clean up and free the buffer returned by +\&\fBget_entropy()\fR. The entropy pointer returned by \fBget_entropy()\fR +is passed in \fBbuf\fR and its length in \fBlen\fR. +.PP +\&\fBcleanup_user_entropy()\fR is used to clean up and free the buffer returned by +\&\fBget_user_entropy()\fR. The entropy pointer returned by \fBget_user_entropy()\fR +is passed in \fBbuf\fR and its length in \fBlen\fR. +.PP +\&\fBget_nonce()\fR retrieves a nonce using the passed \fIsalt\fR parameter +of length \fIsalt_len\fR and operating system specific information. +The \fIsalt\fR should contain uniquely identifying information and this is +included, in an unspecified manner, as part of the output. +The output is stored in a buffer which contains at least \fImin_len\fR and at +most \fImax_len\fR bytes. The buffer address is stored in \fI*pout\fR and the +buffer length returned to the caller. On error, zero is returned. +.PP +\&\fBget_user_nonce()\fR is the same as \fBget_nonce()\fR except that it will attempt +to gather seed material via the seed source specified by a call to +\&\fBRAND_set_seed_source_type\fR\|(3) or via "Random Configuration" in \fBconfig\fR\|(5). +.PP +\&\fBcleanup_nonce()\fR is used to clean up and free the buffer returned by +\&\fBget_nonce()\fR. The nonce pointer returned by \fBget_nonce()\fR +is passed in \fBbuf\fR and its length in \fBlen\fR. +.PP +\&\fBcleanup_user_nonce()\fR is used to clean up and free the buffer returned by +\&\fBget_user_nonce()\fR. The nonce pointer returned by \fBget_user_nonce()\fR +is passed in \fBbuf\fR and its length in \fBlen\fR. +.PP +\&\fBprovider_register_child_cb()\fR registers callbacks for being informed about the +loading and unloading of providers in the application\*(Aqs library context. +\&\fIhandle\fR is this provider\*(Aqs handle and \fIcbdata\fR is this provider\*(Aqs data +that will be passed back to the callbacks. It returns 1 on success or 0 +otherwise. These callbacks may be called while holding locks in libcrypto. In +order to avoid deadlocks the callback implementation must not be long running +and must not call other OpenSSL API functions or upcalls. +.PP +\&\fIcreate_cb\fR is a callback that will be called when a new provider is loaded +into the application\*(Aqs library context. It is also called for any providers that +are already loaded at the point that this callback is registered. The callback +is passed the handle being used for the new provider being loadded and this +provider\*(Aqs data in \fIcbdata\fR. It should return 1 on success or 0 on failure. +.PP +\&\fIremove_cb\fR is a callback that will be called when a new provider is unloaded +from the application\*(Aqs library context. It is passed the handle being used for +the provider being unloaded and this provider\*(Aqs data in \fIcbdata\fR. It should +return 1 on success or 0 on failure. +.PP +\&\fIglobal_props_cb\fR is a callback that will be called when the global properties +from the parent library context are changed. It should return 1 on success +or 0 on failure. +.PP +\&\fBprovider_deregister_child_cb()\fR unregisters callbacks previously registered via +\&\fBprovider_register_child_cb()\fR. If \fBprovider_register_child_cb()\fR has been called +then \fBprovider_deregister_child_cb()\fR should be called at or before the point that +this provider\*(Aqs teardown function is called. +.PP +\&\fBprovider_name()\fR returns a string giving the name of the provider identified by +\&\fIhandle\fR. +.PP +\&\fBprovider_get0_provider_ctx()\fR returns the provider context that is associated +with the provider identified by \fIprov\fR. +.PP +\&\fBprovider_get0_dispatch()\fR gets the dispatch table registered by the provider +identified by \fIprov\fR when it initialised. +.PP +\&\fBprovider_up_ref()\fR increments the reference count on the provider \fIprov\fR. If +\&\fIactivate\fR is nonzero then the provider is also loaded if it is not already +loaded. It returns 1 on success or 0 on failure. +.PP +\&\fBprovider_free()\fR decrements the reference count on the provider \fIprov\fR. If +\&\fIdeactivate\fR is nonzero then the provider is also unloaded if it is not +already loaded. It returns 1 on success or 0 on failure. +.SS "Provider functions" +.IX Subsection "Provider functions" +\&\fBprovider_teardown()\fR is called when a provider is shut down and removed +from the core\*(Aqs provider store. +It must free the passed \fIprovctx\fR. +.PP +\&\fBprovider_gettable_params()\fR should return a constant array of +descriptor \fBOSSL_PARAM\fR\|(3), for parameters that \fBprovider_get_params()\fR +can handle. +.PP +\&\fBprovider_get_params()\fR should process the \fBOSSL_PARAM\fR\|(3) array +\&\fIparams\fR, setting the values of the parameters it understands. +.PP +\&\fBprovider_query_operation()\fR should return a constant \fBOSSL_ALGORITHM\fR\|(3) +that corresponds to the given \fIoperation_id\fR. +It should indicate if the core may store a reference to this array by +setting \fI*no_store\fR to 0 (core may store a reference) or 1 (core may +not store a reference). +.PP +\&\fBprovider_unquery_operation()\fR informs the provider that the result of a +\&\fBprovider_query_operation()\fR is no longer directly required and that the function +pointers have been copied. The \fIoperation_id\fR should match that passed to +\&\fBprovider_query_operation()\fR and \fIalgs\fR should be its return value. +.PP +\&\fBprovider_get_reason_strings()\fR should return a constant \fBOSSL_ITEM\fR\|(3) +array that provides reason strings for reason codes the provider may +use when reporting errors using \fBcore_put_error()\fR. +.PP +The \fBprovider_get_capabilities()\fR function should call the callback \fIcb\fR passing +it a set of \fBOSSL_PARAM\fR\|(3)s and the caller supplied argument \fIarg\fR. The +\&\fBOSSL_PARAM\fR\|(3)s should provide details about the capability with the name given +in the \fIcapability\fR argument relevant for the provider context \fIprovctx\fR. If a +provider supports multiple capabilities with the given name then it may call the +callback multiple times (one for each capability). Capabilities can be useful for +describing the services that a provider can offer. For further details see the +"CAPABILITIES" section below. It should return 1 on success or 0 on error. +.PP +The \fBprovider_self_test()\fR function should perform known answer tests on a subset +of the algorithms that it uses, and may also verify the integrity of the +provider module. It should return 1 on success or 0 on error. It will return 1 +if this function is not used. +.PP +None of these functions are mandatory, but a provider is fairly +useless without at least \fBprovider_query_operation()\fR, and +\&\fBprovider_gettable_params()\fR is fairly useless if not accompanied by +\&\fBprovider_get_params()\fR. +.SS "Provider parameters" +.IX Subsection "Provider parameters" +\&\fBprovider_get_params()\fR can return the following provider parameters to the core: +.IP """name"" (\fBOSSL_PROV_PARAM_NAME\fR) " 4 +.IX Item """name"" (OSSL_PROV_PARAM_NAME) " +This points to a string that should give a unique name for the provider. +.IP """version"" (\fBOSSL_PROV_PARAM_VERSION\fR) " 4 +.IX Item """version"" (OSSL_PROV_PARAM_VERSION) " +This points to a string that is a version number associated with this provider. +OpenSSL in\-built providers use OPENSSL_VERSION_STR, but this may be different +for any third party provider. This string is for informational purposes only. +.IP """buildinfo"" (\fBOSSL_PROV_PARAM_BUILDINFO\fR) " 4 +.IX Item """buildinfo"" (OSSL_PROV_PARAM_BUILDINFO) " +This points to a string that is a build information associated with this provider. +OpenSSL in\-built providers use OPENSSL_FULL_VERSION_STR, but this may be +different for any third party provider. +.IP """status"" (\fBOSSL_PROV_PARAM_STATUS\fR) " 4 +.IX Item """status"" (OSSL_PROV_PARAM_STATUS) " +This returns 0 if the provider has entered an error state, otherwise it returns +1. +.PP +\&\fBprovider_gettable_params()\fR should return the above parameters. +.SS "Core parameters" +.IX Subsection "Core parameters" +\&\fBcore_get_params()\fR can retrieve the following core parameters for each provider: +.IP """openssl\-version"" (\fBOSSL_PROV_PARAM_CORE_VERSION\fR) " 4 +.IX Item """openssl-version"" (OSSL_PROV_PARAM_CORE_VERSION) " +This points to the OpenSSL libraries\*(Aq full version string, i.e. the string +expanded from the macro \fBOPENSSL_VERSION_STR\fR. +.IP """provider\-name"" (\fBOSSL_PROV_PARAM_CORE_PROV_NAME\fR) " 4 +.IX Item """provider-name"" (OSSL_PROV_PARAM_CORE_PROV_NAME) " +This points to the OpenSSL libraries\*(Aq idea of what the calling provider is named. +.IP """module\-filename"" (\fBOSSL_PROV_PARAM_CORE_MODULE_FILENAME\fR) " 4 +.IX Item """module-filename"" (OSSL_PROV_PARAM_CORE_MODULE_FILENAME) " +This points to a string containing the full filename of the providers +module file. +.PP +Additionally, provider specific configuration parameters from the +config file are available, in dotted name form. +The dotted name form is a concatenation of section names and final +config command name separated by periods. +.PP +For example, let\*(Aqs say we have the following config example: +.PP +.Vb 2 +\& config_diagnostics = 1 +\& openssl_conf = openssl_init +\& +\& [openssl_init] +\& providers = providers_sect +\& +\& [providers_sect] +\& foo = foo_sect +\& +\& [foo_sect] +\& activate = 1 +\& data1 = 2 +\& data2 = str +\& more = foo_more +\& +\& [foo_more] +\& data3 = foo,bar +.Ve +.PP +The provider will have these additional parameters available: +.IP """activate""" 4 +.IX Item """activate""" +pointing at the string "1" +.IP """data1""" 4 +.IX Item """data1""" +pointing at the string "2" +.IP """data2""" 4 +.IX Item """data2""" +pointing at the string "str" +.IP """more.data3""" 4 +.IX Item """more.data3""" +pointing at the string "foo,bar" +.PP +For more information on handling parameters, see \fBOSSL_PARAM\fR\|(3) as +\&\fBOSSL_PARAM_int\fR\|(3). +.SH CAPABILITIES +.IX Header "CAPABILITIES" +Capabilities describe some of the services that a provider can offer. +Applications can query the capabilities to discover those services. +.PP +\fI"TLS\-GROUP" Capability\fR +.IX Subsection """TLS-GROUP"" Capability" +.PP +The "TLS\-GROUP" capability can be queried by libssl to discover the list of +TLS groups that a provider can support. Each group supported can be used for +\&\fIkey exchange\fR (KEX) or \fIkey encapsulation method\fR (KEM) during a TLS +handshake. +TLS clients can advertise the list of TLS groups they support in the +supported_groups extension, and TLS servers can select a group from the offered +list that they also support. In this way a provider can add to the list of +groups that libssl already supports with additional ones. +.PP +Each TLS group that a provider supports should be described via the callback +passed in through the provider_get_capabilities function. Each group should have +the following details supplied (all are mandatory, except +\&\fBOSSL_CAPABILITY_TLS_GROUP_IS_KEM\fR): +.IP """tls\-group\-name"" (\fBOSSL_CAPABILITY_TLS_GROUP_NAME\fR) " 4 +.IX Item """tls-group-name"" (OSSL_CAPABILITY_TLS_GROUP_NAME) " +The name of the group as given in the IANA TLS Supported Groups registry +. +.IP """tls\-group\-name\-internal"" (\fBOSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL\fR) " 4 +.IX Item """tls-group-name-internal"" (OSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL) " +The name of the group as known by the provider. This could be the same as the +"tls\-group\-name", but does not have to be. +.IP """tls\-group\-id"" (\fBOSSL_CAPABILITY_TLS_GROUP_ID\fR) " 4 +.IX Item """tls-group-id"" (OSSL_CAPABILITY_TLS_GROUP_ID) " +The TLS group id value as given in the IANA TLS Supported Groups registry. +.Sp +It is possible to register the same group id from within different +providers. Users should note that if no property query is specified, or +more than one implementation matches the property query then it is +unspecified which implementation for a particular group id will be used. +.IP """tls\-group\-alg"" (\fBOSSL_CAPABILITY_TLS_GROUP_ALG\fR) " 4 +.IX Item """tls-group-alg"" (OSSL_CAPABILITY_TLS_GROUP_ALG) " +The name of a Key Management algorithm that the provider offers and that should +be used with this group. Keys created should be able to support \fIkey exchange\fR +or \fIkey encapsulation method\fR (KEM), as implied by the optional +\&\fBOSSL_CAPABILITY_TLS_GROUP_IS_KEM\fR flag. +The algorithm must support key and parameter generation as well as the +key/parameter generation parameter, \fBOSSL_PKEY_PARAM_GROUP_NAME\fR. The group +name given via "tls\-group\-name\-internal" above will be passed via +\&\fBOSSL_PKEY_PARAM_GROUP_NAME\fR when libssl wishes to generate keys/parameters. +.IP """tls\-group\-sec\-bits"" (\fBOSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS\fR) " 4 +.IX Item """tls-group-sec-bits"" (OSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS) " +The number of bits of security offered by keys in this group. The number of bits +should be comparable with the ones given in table 2 and 3 of the NIST SP800\-57 +document. +.IP """tls\-group\-is\-kem"" (\fBOSSL_CAPABILITY_TLS_GROUP_IS_KEM\fR) " 4 +.IX Item """tls-group-is-kem"" (OSSL_CAPABILITY_TLS_GROUP_IS_KEM) " +Boolean flag to describe if the group should be used in \fIkey exchange\fR (KEX) +mode (0, default) or in \fIkey encapsulation method\fR (KEM) mode (1). +.Sp +This parameter is optional: if not specified, KEX mode is assumed as the default +mode for the group. +.Sp +In KEX mode, in a typical Diffie\-Hellman fashion, both sides execute \fIkeygen\fR +then \fIderive\fR against the peer public key. To operate in KEX mode, the group +implementation must support the provider functions as described in +\&\fBprovider\-keyexch\fR\|(7). +.Sp +In KEM mode, the client executes \fIkeygen\fR and sends its public key, the server +executes \fIencapsulate\fR using the client\*(Aqs public key and sends back the +resulting \fIciphertext\fR, finally the client executes \fIdecapsulate\fR to retrieve +the same \fIshared secret\fR generated by the server\*(Aqs \fIencapsulate\fR. To operate +in KEM mode, the group implementation must support the provider functions as +described in \fBprovider\-kem\fR\|(7). +.Sp +Both in KEX and KEM mode, the resulting \fIshared secret\fR is then used according +to the protocol specification. +.IP """tls\-min\-tls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MIN_TLS\fR) " 4 +.IX Item """tls-min-tls"" (OSSL_CAPABILITY_TLS_GROUP_MIN_TLS) " +.PD 0 +.IP """tls\-max\-tls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MAX_TLS\fR) " 4 +.IX Item """tls-max-tls"" (OSSL_CAPABILITY_TLS_GROUP_MAX_TLS) " +.IP """tls\-min\-dtls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MIN_DTLS\fR) " 4 +.IX Item """tls-min-dtls"" (OSSL_CAPABILITY_TLS_GROUP_MIN_DTLS) " +.IP """tls\-max\-dtls"" (\fBOSSL_CAPABILITY_TLS_GROUP_MAX_DTLS\fR) " 4 +.IX Item """tls-max-dtls"" (OSSL_CAPABILITY_TLS_GROUP_MAX_DTLS) " +.PD +These parameters can be used to describe the minimum and maximum TLS and DTLS +versions supported by the group. The values equate to the on\-the\-wire encoding +of the various TLS versions. For example TLSv1.3 is 0x0304 (772 decimal), and +TLSv1.2 is 0x0303 (771 decimal). A 0 indicates that there is no defined minimum +or maximum. A \-1 indicates that the group should not be used in that protocol. +.PP +\fI"TLS\-SIGALG" Capability\fR +.IX Subsection """TLS-SIGALG"" Capability" +.PP +The "TLS\-SIGALG" capability can be queried by libssl to discover the list of +TLS signature algorithms that a provider can support. Each signature supported +can be used for client\- or server\-authentication in addition to the built\-in +signature algorithms. +TLS1.3 clients can advertise the list of TLS signature algorithms they support +in the signature_algorithms extension, and TLS servers can select an algorithm +from the offered list that they also support. In this way a provider can add +to the list of signature algorithms that libssl already supports with +additional ones. +.PP +Each TLS signature algorithm that a provider supports should be described via +the callback passed in through the provider_get_capabilities function. Each +algorithm can have the following details supplied: +.IP """iana\-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_IANA_NAME\fR) " 4 +.IX Item """iana-name"" (OSSL_CAPABILITY_TLS_SIGALG_IANA_NAME) " +The name of the signature algorithm as given in the IANA TLS Signature Scheme +registry as "Description": +. +This value must be supplied. +.IP """iana\-code\-point"" (\fBOSSL_CAPABILITY_TLS_SIGALG_CODE_POINT\fR) " 4 +.IX Item """iana-code-point"" (OSSL_CAPABILITY_TLS_SIGALG_CODE_POINT) " +The TLS algorithm ID value as given in the IANA TLS SignatureScheme registry. +This value must be supplied. +.Sp +It is possible to register the same code point from within different +providers. Users should note that if no property query is specified, or +more than one implementation matches the property query then it is +unspecified which implementation for a particular code point will be used. +.IP """sigalg\-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_NAME\fR) " 4 +.IX Item """sigalg-name"" (OSSL_CAPABILITY_TLS_SIGALG_NAME) " +A name for the full (possibly composite hash\-and\-signature) signature +algorithm. +The provider may, but is not obligated to, provide a signature implementation +with this name; if it doesn\*(Aqt, this is assumed to be a composite of a pure +signature algorithm and a hash algorithm, which must be given with the +parameters "sig\-name" and "hash\-name". +This value must be supplied. +.IP """sigalg\-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_OID\fR) " 4 +.IX Item """sigalg-oid"" (OSSL_CAPABILITY_TLS_SIGALG_OID) " +The OID of the "sigalg\-name" algorithm in canonical numeric text form. If +this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and +a NID for this OID, using the "sigalg\-name" parameter for its (short) name. +Otherwise, it\*(Aqs assumed to already exist in the object database, possibly +done by the provider with the \fBcore_obj_create()\fR upcall. +This value is optional. +.IP """sig\-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SIG_NAME\fR) " 4 +.IX Item """sig-name"" (OSSL_CAPABILITY_TLS_SIGALG_SIG_NAME) " +The name of the pure signature algorithm that is part of a composite +"sigalg\-name". If "sigalg\-name" is implemented by the provider, this +parameter is redundant and must not be given. +This value is optional. +.IP """sig\-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SIG_OID\fR) " 4 +.IX Item """sig-oid"" (OSSL_CAPABILITY_TLS_SIGALG_SIG_OID) " +The OID of the "sig\-name" algorithm in canonical numeric text form. If +this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and +a NID for this OID, using the "sig\-name" parameter for its (short) name. +Otherwise, it is assumed to already exist in the object database. This +can be done by the provider using the \fBcore_obj_create()\fR upcall. +This value is optional. +.IP """hash\-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_HASH_NAME\fR) " 4 +.IX Item """hash-name"" (OSSL_CAPABILITY_TLS_SIGALG_HASH_NAME) " +The name of the hash algorithm that is part of a composite "sigalg\-name". +If "sigalg\-name" is implemented by the provider, this parameter is redundant +and must not be given. +This value is optional. +.IP """hash\-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_HASH_OID\fR) " 4 +.IX Item """hash-oid"" (OSSL_CAPABILITY_TLS_SIGALG_HASH_OID) " +The OID of the "hash\-name" algorithm in canonical numeric text form. If +this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and +a NID for this OID, using the "hash\-name" parameter for its (short) name. +Otherwise, it\*(Aqs assumed to already exist in the object database, possibly +done by the provider with the \fBcore_obj_create()\fR upcall. +This value is optional. +.IP """key\-type"" (\fBOSSL_CAPABILITY_TLS_SIGALG_KEYTYPE\fR) " 4 +.IX Item """key-type"" (OSSL_CAPABILITY_TLS_SIGALG_KEYTYPE) " +The key type of the public key of applicable certificates. If this parameter +isn\*(Aqt present, it\*(Aqs assumed to be the same as "sig\-name" if that\*(Aqs present, +otherwise "sigalg\-name". +This value is optional. +.IP """key\-type\-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_KEYTYPE_OID\fR) " 4 +.IX Item """key-type-oid"" (OSSL_CAPABILITY_TLS_SIGALG_KEYTYPE_OID) " +The OID of the "key\-type" in canonical numeric text form. If +this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and +a NID for this OID, using the "key\-type" parameter for its (short) name. +Otherwise, it\*(Aqs assumed to already exist in the object database, possibly +done by the provider with the \fBcore_obj_create()\fR upcall. +This value is optional. +.IP """sec\-bits"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SECURITY_BITS\fR) " 4 +.IX Item """sec-bits"" (OSSL_CAPABILITY_TLS_SIGALG_SECURITY_BITS) " +The number of bits of security offered by keys of this algorithm. The number +of bits should be comparable with the ones given in table 2 and 3 of the NIST +SP800\-57 document. This number is used to determine the security strength of +the algorithm if no digest algorithm has been registered that otherwise +defines the security strength. If the signature algorithm implements its own +digest internally, this value needs to be set to properly reflect the overall +security strength. +This value must be supplied. +.IP """tls\-min\-tls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MIN_TLS\fR) " 4 +.IX Item """tls-min-tls"" (OSSL_CAPABILITY_TLS_SIGALG_MIN_TLS) " +.PD 0 +.IP """tls\-max\-tls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MAX_TLS\fR) " 4 +.IX Item """tls-max-tls"" (OSSL_CAPABILITY_TLS_SIGALG_MAX_TLS) " +.IP """tls\-min\-dtls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MIN_DTLS\fR) " 4 +.IX Item """tls-min-dtls"" (OSSL_CAPABILITY_TLS_SIGALG_MIN_DTLS) " +.IP """tls\-max\-dtls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MAX_DTLS\fR) " 4 +.IX Item """tls-max-dtls"" (OSSL_CAPABILITY_TLS_SIGALG_MAX_DTLS) " +.PD +These parameters can be used to describe the minimum and maximum TLS and DTLS +versions supported by the signature algorithm. The values equate to the +on\-the\-wire encoding of the various TLS versions. For example TLSv1.3 is +0x0304 (772 decimal), and TLSv1.2 is 0x0303 (771 decimal). A 0 indicates that +there is no defined minimum or maximum. A \-1 in either the min or max field +indicates that the signature algorithm should not be used in that protocol. +Presently, provider signature algorithms are used only with TLS 1.3, if +that\*(Aqs enclosed in the specified range. +.SH NOTES +.IX Header "NOTES" +The \fBcore_obj_create()\fR and \fBcore_obj_add_sigid()\fR functions were not thread safe +in OpenSSL 3.0. +.SH EXAMPLES +.IX Header "EXAMPLES" +This is an example of a simple provider made available as a +dynamically loadable module. +It implements the fictitious algorithm \f(CW\*(C`FOO\*(C'\fR for the fictitious +operation \f(CW\*(C`BAR\*(C'\fR. +.PP +.Vb 3 +\& #include +\& #include +\& #include +\& +\& /* Errors used in this provider */ +\& #define E_MALLOC 1 +\& +\& static const OSSL_ITEM reasons[] = { +\& { E_MALLOC, "memory allocation failure" }. +\& OSSL_DISPATCH_END +\& }; +\& +\& /* +\& * To ensure we get the function signature right, forward declare +\& * them using function types provided by openssl/core_dispatch.h +\& */ +\& OSSL_FUNC_bar_newctx_fn foo_newctx; +\& OSSL_FUNC_bar_freectx_fn foo_freectx; +\& OSSL_FUNC_bar_init_fn foo_init; +\& OSSL_FUNC_bar_update_fn foo_update; +\& OSSL_FUNC_bar_final_fn foo_final; +\& +\& OSSL_FUNC_provider_query_operation_fn p_query; +\& OSSL_FUNC_provider_get_reason_strings_fn p_reasons; +\& OSSL_FUNC_provider_teardown_fn p_teardown; +\& +\& OSSL_provider_init_fn OSSL_provider_init; +\& +\& OSSL_FUNC_core_put_error *c_put_error = NULL; +\& +\& /* Provider context */ +\& struct prov_ctx_st { +\& OSSL_CORE_HANDLE *handle; +\& } +\& +\& /* operation context for the algorithm FOO */ +\& struct foo_ctx_st { +\& struct prov_ctx_st *provctx; +\& int b; +\& }; +\& +\& static void *foo_newctx(void *provctx) +\& { +\& struct foo_ctx_st *fooctx = malloc(sizeof(*fooctx)); +\& +\& if (fooctx != NULL) +\& fooctx\->provctx = provctx; +\& else +\& c_put_error(provctx\->handle, E_MALLOC, _\|_FILE_\|_, _\|_LINE_\|_); +\& return fooctx; +\& } +\& +\& static void foo_freectx(void *fooctx) +\& { +\& free(fooctx); +\& } +\& +\& static int foo_init(void *vfooctx) +\& { +\& struct foo_ctx_st *fooctx = vfooctx; +\& +\& fooctx\->b = 0x33; +\& } +\& +\& static int foo_update(void *vfooctx, unsigned char *in, size_t inl) +\& { +\& struct foo_ctx_st *fooctx = vfooctx; +\& +\& /* did you expect something serious? */ +\& if (inl == 0) +\& return 1; +\& for (; inl\-\- > 0; in++) +\& *in ^= fooctx\->b; +\& return 1; +\& } +\& +\& static int foo_final(void *vfooctx) +\& { +\& struct foo_ctx_st *fooctx = vfooctx; +\& +\& fooctx\->b = 0x66; +\& } +\& +\& static const OSSL_DISPATCH foo_fns[] = { +\& { OSSL_FUNC_BAR_NEWCTX, (void (*)(void))foo_newctx }, +\& { OSSL_FUNC_BAR_FREECTX, (void (*)(void))foo_freectx }, +\& { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init }, +\& { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update }, +\& { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final }, +\& OSSL_DISPATCH_END +\& }; +\& +\& static const OSSL_ALGORITHM bars[] = { +\& { "FOO", "provider=chumbawamba", foo_fns }, +\& { NULL, NULL, NULL } +\& }; +\& +\& static const OSSL_ALGORITHM *p_query(void *provctx, int operation_id, +\& int *no_store) +\& { +\& switch (operation_id) { +\& case OSSL_OP_BAR: +\& return bars; +\& } +\& return NULL; +\& } +\& +\& static const OSSL_ITEM *p_reasons(void *provctx) +\& { +\& return reasons; +\& } +\& +\& static void p_teardown(void *provctx) +\& { +\& free(provctx); +\& } +\& +\& static const OSSL_DISPATCH prov_fns[] = { +\& { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown }, +\& { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query }, +\& { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons }, +\& OSSL_DISPATCH_END +\& }; +\& +\& int OSSL_provider_init(const OSSL_CORE_HANDLE *handle, +\& const OSSL_DISPATCH *in, +\& const OSSL_DISPATCH **out, +\& void **provctx) +\& { +\& struct prov_ctx_st *pctx = NULL; +\& +\& for (; in\->function_id != 0; in++) +\& switch (in\->function_id) { +\& case OSSL_FUNC_CORE_PUT_ERROR: +\& c_put_error = OSSL_FUNC_core_put_error(in); +\& break; +\& } +\& +\& *out = prov_fns; +\& +\& if ((pctx = malloc(sizeof(*pctx))) == NULL) { +\& /* +\& * ALEA IACTA EST, if the core retrieves the reason table +\& * regardless, that string will be displayed, otherwise not. +\& */ +\& c_put_error(handle, E_MALLOC, _\|_FILE_\|_, _\|_LINE_\|_); +\& return 0; +\& } +\& pctx\->handle = handle; +\& return 1; +\& } +.Ve +.PP +This relies on a few things existing in \fIopenssl/core_dispatch.h\fR: +.PP +.Vb 1 +\& #define OSSL_OP_BAR 4711 +\& +\& #define OSSL_FUNC_BAR_NEWCTX 1 +\& typedef void *(OSSL_FUNC_bar_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_bar_newctx(const OSSL_DISPATCH *opf) +\& { return (OSSL_FUNC_bar_newctx_fn *)opf\->function; } +\& +\& #define OSSL_FUNC_BAR_FREECTX 2 +\& typedef void (OSSL_FUNC_bar_freectx_fn)(void *ctx); +\& static ossl_inline OSSL_FUNC_bar_freectx(const OSSL_DISPATCH *opf) +\& { return (OSSL_FUNC_bar_freectx_fn *)opf\->function; } +\& +\& #define OSSL_FUNC_BAR_INIT 3 +\& typedef void *(OSSL_FUNC_bar_init_fn)(void *ctx); +\& static ossl_inline OSSL_FUNC_bar_init(const OSSL_DISPATCH *opf) +\& { return (OSSL_FUNC_bar_init_fn *)opf\->function; } +\& +\& #define OSSL_FUNC_BAR_UPDATE 4 +\& typedef void *(OSSL_FUNC_bar_update_fn)(void *ctx, +\& unsigned char *in, size_t inl); +\& static ossl_inline OSSL_FUNC_bar_update(const OSSL_DISPATCH *opf) +\& { return (OSSL_FUNC_bar_update_fn *)opf\->function; } +\& +\& #define OSSL_FUNC_BAR_FINAL 5 +\& typedef void *(OSSL_FUNC_bar_final_fn)(void *ctx); +\& static ossl_inline OSSL_FUNC_bar_final(const OSSL_DISPATCH *opf) +\& { return (OSSL_FUNC_bar_final_fn *)opf\->function; } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The concept of providers and everything surrounding them was +introduced in OpenSSL 3.0. +.PP +Definitions for +\&\fBOSSL_CAPABILITY_TLS_SIGALG_MIN_DTLS\fR +and +\&\fBOSSL_CAPABILITY_TLS_SIGALG_MAX_DTLS\fR +were added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-cipher.7 b/static/netbsd/man7/provider-cipher.7 new file mode 100644 index 00000000..25b86cc5 --- /dev/null +++ b/static/netbsd/man7/provider-cipher.7 @@ -0,0 +1,361 @@ +.\" $NetBSD: provider-cipher.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-CIPHER 7" +.TH PROVIDER-CIPHER 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-cipher \- The cipher library <\-> provider functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_cipher_newctx(void *provctx); +\& void OSSL_FUNC_cipher_freectx(void *cctx); +\& void *OSSL_FUNC_cipher_dupctx(void *cctx); +\& +\& /* Encryption/decryption */ +\& int OSSL_FUNC_cipher_encrypt_init(void *cctx, const unsigned char *key, +\& size_t keylen, const unsigned char *iv, +\& size_t ivlen, const OSSL_PARAM params[]); +\& int OSSL_FUNC_cipher_decrypt_init(void *cctx, const unsigned char *key, +\& size_t keylen, const unsigned char *iv, +\& size_t ivlen, const OSSL_PARAM params[]); +\& int OSSL_FUNC_cipher_encrypt_skey_init(void *cctx, void *skeydata, +\& const unsigned char *iv, size_t ivlen, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_cipher_encrypt_skey_init(void *cctx, void *skeydata, +\& const unsigned char *iv, size_t ivlen, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_cipher_update(void *cctx, unsigned char *out, size_t *outl, +\& size_t outsize, const unsigned char *in, size_t inl); +\& int OSSL_FUNC_cipher_final(void *cctx, unsigned char *out, size_t *outl, +\& size_t outsize); +\& int OSSL_FUNC_cipher_cipher(void *cctx, unsigned char *out, size_t *outl, +\& size_t outsize, const unsigned char *in, size_t inl); +\& +\& /* Encryption/decryption using cipher pipeline */ +\& int OSSL_FUNC_cipher_pipeline_encrypt_init(void *cctx, const unsigned char *key, +\& size_t keylen, size_t numpipes, +\& const unsigned char **iv, size_t ivlen, +\& const OSSL_PARAM params[])) +\& int OSSL_FUNC_cipher_pipeline_decrypt_init(void *cctx, const unsigned char *key, +\& size_t keylen, size_t numpipes, +\& const unsigned char **iv, size_t ivlen, +\& const OSSL_PARAM params[])) +\& int OSSL_FUNC_cipher_pipeline_update(void *cctx, size_t numpipes, +\& unsigned char **out, size_t *outl, +\& const size_t *outsize, +\& const unsigned char **in, const size_t *inl)) +\& int OSSL_FUNC_cipher_pipeline_final(void *cctx, size_t numpipes, +\& unsigned char **out, size_t *outl, +\& const size_t *outsize)) +\& +\& /* Cipher parameter descriptors */ +\& const OSSL_PARAM *OSSL_FUNC_cipher_gettable_params(void *provctx); +\& +\& /* Cipher operation parameter descriptors */ +\& const OSSL_PARAM *OSSL_FUNC_cipher_gettable_ctx_params(void *cctx, +\& void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_cipher_settable_ctx_params(void *cctx, +\& void *provctx); +\& +\& /* Cipher parameters */ +\& int OSSL_FUNC_cipher_get_params(OSSL_PARAM params[]); +\& +\& /* Cipher operation parameters */ +\& int OSSL_FUNC_cipher_get_ctx_params(void *cctx, OSSL_PARAM params[]); +\& int OSSL_FUNC_cipher_set_ctx_params(void *cctx, const OSSL_PARAM params[]); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The CIPHER operation enables providers to implement cipher algorithms and make +them available to applications via the API functions \fBEVP_EncryptInit_ex\fR\|(3), +\&\fBEVP_EncryptUpdate\fR\|(3) and \fBEVP_EncryptFinal\fR\|(3) (as well as the decrypt +equivalents and other related functions). +.PP +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via +\&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider\*(Aqs +\&\fBprovider_query_operation()\fR function +(see "Provider Functions" in \fBprovider\-base\fR\|(7)). +.PP +All these "functions" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the "function" \fBOSSL_FUNC_cipher_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_cipher_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_cipher_newctx_fn +\& OSSL_FUNC_cipher_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_cipher_newctx OSSL_FUNC_CIPHER_NEWCTX +\& OSSL_FUNC_cipher_freectx OSSL_FUNC_CIPHER_FREECTX +\& OSSL_FUNC_cipher_dupctx OSSL_FUNC_CIPHER_DUPCTX +\& +\& OSSL_FUNC_cipher_encrypt_init OSSL_FUNC_CIPHER_ENCRYPT_INIT +\& OSSL_FUNC_cipher_decrypt_init OSSL_FUNC_CIPHER_DECRYPT_INIT +\& OSSL_FUNC_cipher_encrypt_skey_init OSSL_FUNC_CIPHER_ENCRYPT_SKEY_INIT +\& OSSL_FUNC_cipher_decrypt_skey_init OSSL_FUNC_CIPHER_DECRYPT_SKEY_INIT +\& OSSL_FUNC_cipher_update OSSL_FUNC_CIPHER_UPDATE +\& OSSL_FUNC_cipher_final OSSL_FUNC_CIPHER_FINAL +\& OSSL_FUNC_cipher_cipher OSSL_FUNC_CIPHER_CIPHER +\& +\& OSSL_FUNC_cipher_pipeline_encrypt_init OSSL_FUNC_CIPHER_PIPELINE_ENCRYPT_INIT +\& OSSL_FUNC_cipher_pipeline_decrypt_init OSSL_FUNC_CIPHER_PIPELINE_DECRYPT_INIT +\& OSSL_FUNC_cipher_pipeline_update OSSL_FUNC_CIPHER_PIPELINE_UPDATE +\& OSSL_FUNC_cipher_pipeline_final OSSL_FUNC_CIPHER_PIPELINE_FINAL +\& +\& OSSL_FUNC_cipher_get_params OSSL_FUNC_CIPHER_GET_PARAMS +\& OSSL_FUNC_cipher_get_ctx_params OSSL_FUNC_CIPHER_GET_CTX_PARAMS +\& OSSL_FUNC_cipher_set_ctx_params OSSL_FUNC_CIPHER_SET_CTX_PARAMS +\& +\& OSSL_FUNC_cipher_gettable_params OSSL_FUNC_CIPHER_GETTABLE_PARAMS +\& OSSL_FUNC_cipher_gettable_ctx_params OSSL_FUNC_CIPHER_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_cipher_settable_ctx_params OSSL_FUNC_CIPHER_SETTABLE_CTX_PARAMS +.Ve +.PP +A cipher algorithm implementation may not implement all of these functions. +In order to be a consistent set of functions there must at least be a complete +set of "encrypt" functions, or a complete set of "decrypt" functions, or a +single "cipher" function. Similarly, there can be a complete set of pipeline +"encrypt" functions, and/or a complete set of pipeline "decrypt" functions. +In all cases the OSSL_FUNC_cipher_get_params and both OSSL_FUNC_cipher_newctx +and OSSL_FUNC_cipher_freectx functions must be present. +All other functions are optional. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_cipher_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during a cipher operation. +A pointer to this context will be passed back in a number of the other cipher +operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +.PP +\&\fBOSSL_FUNC_cipher_freectx()\fR is passed a pointer to the provider side cipher context in +the \fIcctx\fR parameter. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_cipher_dupctx()\fR should duplicate the provider side cipher context in the +\&\fIcctx\fR parameter and return the duplicate copy. +.SS "Encryption/Decryption Functions" +.IX Subsection "Encryption/Decryption Functions" +\&\fBOSSL_FUNC_cipher_encrypt_init()\fR initialises a cipher operation for encryption given a +newly created provider side cipher context in the \fIcctx\fR parameter. +The key to be used is given in \fIkey\fR which is \fIkeylen\fR bytes long. +The IV to be used is given in \fIiv\fR which is \fIivlen\fR bytes long. +The \fIparams\fR, if not NULL, should be set on the context in a manner similar to +using \fBOSSL_FUNC_cipher_set_ctx_params()\fR. +.PP +\&\fBOSSL_FUNC_cipher_decrypt_init()\fR is the same as \fBOSSL_FUNC_cipher_encrypt_init()\fR +except that it initialises the context for a decryption operation. +.PP +\&\fBOSSL_FUNC_cipher_encrypt_skey_init()\fR and +\&\fBOSSL_FUNC_cipher_decrypt_skey_init()\fR are variants of +\&\fBOSSL_FUNC_cipher_encrypt_init()\fR and \fBOSSL_FUNC_cipher_decrypt_init()\fR for working with +opaque objects containing provider\-specific key handles instead of raw bytes. +.PP +\&\fBOSSL_FUNC_cipher_update()\fR is called to supply data to be encrypted/decrypted as part of +a previously initialised cipher operation. +The \fIcctx\fR parameter contains a pointer to a previously initialised provider +side context. +\&\fBOSSL_FUNC_cipher_update()\fR should encrypt/decrypt \fIinl\fR bytes of data at the location +pointed to by \fIin\fR. +The encrypted data should be stored in \fIout\fR and the amount of data written to +\&\fI*outl\fR which should not exceed \fIoutsize\fR bytes. +\&\fBOSSL_FUNC_cipher_update()\fR may be called multiple times for a single cipher operation. +It is the responsibility of the cipher implementation to handle input lengths +that are not multiples of the block length. +In such cases a cipher implementation will typically cache partial blocks of +input data until a complete block is obtained. +The pointers \fIout\fR and \fIin\fR may point to the same location, in which +case the encryption must be done in\-place. If \fIout\fR and \fIin\fR point to different +locations, the requirements of \fBEVP_EncryptUpdate\fR\|(3) and \fBEVP_DecryptUpdate\fR\|(3) +guarantee that the two buffers are disjoint. +Similarly, the requirements of \fBEVP_EncryptUpdate\fR\|(3) and \fBEVP_DecryptUpdate\fR\|(3) +ensure that the buffer pointed to by \fIout\fR contains sufficient room for the +operation being performed. +.PP +\&\fBOSSL_FUNC_cipher_final()\fR completes an encryption or decryption started through previous +\&\fBOSSL_FUNC_cipher_encrypt_init()\fR or \fBOSSL_FUNC_cipher_decrypt_init()\fR, and \fBOSSL_FUNC_cipher_update()\fR +calls. +The \fIcctx\fR parameter contains a pointer to the provider side context. +Any final encryption/decryption output should be written to \fIout\fR and the +amount of data written to \fI*outl\fR which should not exceed \fIoutsize\fR bytes. +The same expectations apply to \fIoutsize\fR as documented for +\&\fBEVP_EncryptFinal\fR\|(3) and \fBEVP_DecryptFinal\fR\|(3). +.PP +\&\fBOSSL_FUNC_cipher_cipher()\fR performs encryption/decryption using the provider side cipher +context in the \fIcctx\fR parameter that should have been previously initialised via +a call to \fBOSSL_FUNC_cipher_encrypt_init()\fR or \fBOSSL_FUNC_cipher_decrypt_init()\fR. +This should call the raw underlying cipher function without any padding. +This will be invoked in the provider as a result of the application calling +\&\fBEVP_Cipher\fR\|(3). +The application is responsible for ensuring that the input is a multiple of the +block length. +The data to be encrypted/decrypted will be in \fIin\fR, and it will be \fIinl\fR bytes +in length. +The output from the encryption/decryption should be stored in \fIout\fR and the +amount of data stored should be put in \fI*outl\fR which should be no more than +\&\fIoutsize\fR bytes. +.PP +\&\fBOSSL_FUNC_cipher_pipeline_encrypt_init()\fR, \fBOSSL_FUNC_cipher_pipeline_decrypt_init()\fR +\&\fBOSSL_FUNC_cipher_pipeline_update()\fR, and \fBOSSL_FUNC_cipher_pipeline_final()\fR are similar to +the non\-pipeline variants, but are used when the application is using cipher pipelining. +The \fInumpipes\fR parameter is the number of pipes in the pipeline. The \fIiv\fR parameter +is an array of buffers with IVs, each \fIivlen\fR bytes long. The \fIin\fR and \fIout\fR are +arrays of buffer pointers. The \fIinl\fR and \fIoutl\fR, \fIoutsize\fR are arrays of size_t +representing corresponding buffer length as similar to the non\-pipeline variants. +All arrays are of length \fInumpipes\fR. See \fBEVP_CipherPipelineEncryptInit\fR\|(3) for more +information. +.SS "Cipher Parameters" +.IX Subsection "Cipher Parameters" +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by +these functions. +.PP +\&\fBOSSL_FUNC_cipher_get_params()\fR gets details of the algorithm implementation +and stores them in \fIparams\fR. +.PP +\&\fBOSSL_FUNC_cipher_set_ctx_params()\fR sets cipher operation parameters for the +provider side cipher context \fIcctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_cipher_get_ctx_params()\fR gets cipher operation details details from +the given provider side cipher context \fIcctx\fR and stores them in \fIparams\fR. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_cipher_gettable_params()\fR, \fBOSSL_FUNC_cipher_gettable_ctx_params()\fR, +and \fBOSSL_FUNC_cipher_settable_ctx_params()\fR all return constant \fBOSSL_PARAM\fR\|(3) +arrays as descriptors of the parameters that \fBOSSL_FUNC_cipher_get_params()\fR, +\&\fBOSSL_FUNC_cipher_get_ctx_params()\fR, and \fBOSSL_FUNC_cipher_set_ctx_params()\fR +can handle, respectively. \fBOSSL_FUNC_cipher_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_cipher_settable_ctx_params()\fR will return the parameters associated +with the provider side context \fIcctx\fR in its current state if it is +not NULL. Otherwise, they return the parameters associated with the +provider side algorithm \fIprovctx\fR. +.PP +Parameters currently recognised by built\-in ciphers are listed in +"PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +Not all parameters are relevant to, or are understood by all ciphers. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_cipher_newctx()\fR and \fBOSSL_FUNC_cipher_dupctx()\fR should return the newly created +provider side cipher context, or NULL on failure. +.PP +\&\fBOSSL_FUNC_cipher_encrypt_init()\fR, \fBOSSL_FUNC_cipher_decrypt_init()\fR, \fBOSSL_FUNC_cipher_update()\fR, +\&\fBOSSL_FUNC_cipher_final()\fR, \fBOSSL_FUNC_cipher_cipher()\fR, +\&\fBOSSL_FUNC_cipher_encrypt_skey_init()\fR, \fBOSSL_FUNC_cipher_decrypt_skey_init()\fR, +\&\fBOSSL_FUNC_cipher_pipeline_encrypt_init()\fR, \fBOSSL_FUNC_cipher_pipeline_decrypt_init()\fR, +\&\fBOSSL_FUNC_cipher_pipeline_update()\fR, \fBOSSL_FUNC_cipher_pipeline_final()\fR, +\&\fBOSSL_FUNC_cipher_get_params()\fR, \fBOSSL_FUNC_cipher_get_ctx_params()\fR and +\&\fBOSSL_FUNC_cipher_set_ctx_params()\fR should return 1 for +success or 0 on error. +.PP +\&\fBOSSL_FUNC_cipher_gettable_params()\fR, \fBOSSL_FUNC_cipher_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_cipher_settable_ctx_params()\fR should return a constant \fBOSSL_PARAM\fR\|(3) +array, or NULL if none is offered. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), +\&\fBOSSL_PROVIDER\-legacy\fR\|(7), +\&\fBEVP_CIPHER\-AES\fR\|(7), \fBEVP_CIPHER\-ARIA\fR\|(7), \fBEVP_CIPHER\-BLOWFISH\fR\|(7), +\&\fBEVP_CIPHER\-CAMELLIA\fR\|(7), \fBEVP_CIPHER\-CAST\fR\|(7), \fBEVP_CIPHER\-CHACHA\fR\|(7), +\&\fBEVP_CIPHER\-DES\fR\|(7), \fBEVP_CIPHER\-IDEA\fR\|(7), \fBEVP_CIPHER\-RC2\fR\|(7), +\&\fBEVP_CIPHER\-RC4\fR\|(7), \fBEVP_CIPHER\-RC5\fR\|(7), \fBEVP_CIPHER\-SEED\fR\|(7), +\&\fBEVP_CIPHER\-SM4\fR\|(7), \fBEVP_CIPHER\-NULL\fR\|(7), +\&\fBlife_cycle\-cipher\fR\|(7), \fBEVP_EncryptInit\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The provider CIPHER interface was introduced in OpenSSL 3.0. +.PP +The \fBOSSL_FUNC_cipher_encrypt_skey_init()\fR and +\&\fBOSSL_FUNC_cipher_decrypt_skey_init()\fR were introduced in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-decoder.7 b/static/netbsd/man7/provider-decoder.7 new file mode 100644 index 00000000..7a408639 --- /dev/null +++ b/static/netbsd/man7/provider-decoder.7 @@ -0,0 +1,346 @@ +.\" $NetBSD: provider-decoder.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-DECODER 7" +.TH PROVIDER-DECODER 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-decoder \- The OSSL_DECODER library <\-> provider functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Decoder parameter accessor and descriptor */ +\& const OSSL_PARAM *OSSL_FUNC_decoder_gettable_params(void *provctx); +\& int OSSL_FUNC_decoder_get_params(OSSL_PARAM params[]); +\& +\& /* Functions to construct / destruct / manipulate the decoder context */ +\& void *OSSL_FUNC_decoder_newctx(void *provctx); +\& void OSSL_FUNC_decoder_freectx(void *ctx); +\& const OSSL_PARAM *OSSL_FUNC_decoder_settable_ctx_params(void *provctx); +\& int OSSL_FUNC_decoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]); +\& +\& /* Functions to check selection support */ +\& int OSSL_FUNC_decoder_does_selection(void *provctx, int selection); +\& +\& /* Functions to decode object data */ +\& int OSSL_FUNC_decoder_decode(void *ctx, OSSL_CORE_BIO *in, +\& int selection, +\& OSSL_CALLBACK *data_cb, void *data_cbarg, +\& OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); +\& +\& /* Functions to export a decoded object */ +\& int OSSL_FUNC_decoder_export_object(void *ctx, +\& const void *objref, size_t objref_sz, +\& OSSL_CALLBACK *export_cb, +\& void *export_cbarg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fIThe term "decode" is used throughout this manual. This includes but is +not limited to deserialization as individual decoders can also do +decoding into intermediate data formats.\fR +.PP +The DECODER operation is a generic method to create a provider\-native +object reference or intermediate decoded data from an encoded form +read from the given \fBOSSL_CORE_BIO\fR. If the caller wants to decode +data from memory, it should provide a \fBBIO_s_mem\fR\|(3) \fBBIO\fR. The decoded +data or object reference is passed along with eventual metadata +to the \fImetadata_cb\fR as \fBOSSL_PARAM\fR\|(3) parameters. +.PP +The decoder doesn\*(Aqt need to know more about the \fBOSSL_CORE_BIO\fR +pointer than being able to pass it to the appropriate BIO upcalls (see +"Core functions" in \fBprovider\-base\fR\|(7)). +.PP +The DECODER implementation may be part of a chain, where data is +passed from one to the next. For example, there may be an +implementation to decode an object from PEM to DER, and another one +that decodes DER to a provider\-native object. +.PP +The last decoding step in the decoding chain is usually supposed to create +a provider\-native object referenced by an object reference. To import +that object into a different provider the \fBOSSL_FUNC_decoder_export_object()\fR +can be called as the final step of the decoding process. +.PP +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via +\&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider\*(Aqs +\&\fBprovider_query_operation()\fR function +(see "Provider Functions" in \fBprovider\-base\fR\|(7)). +.PP +All these "functions" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the "function" \fBOSSL_FUNC_decoder_decode()\fR has these: +.PP +.Vb 7 +\& typedef int +\& (OSSL_FUNC_decoder_decode_fn)(void *ctx, OSSL_CORE_BIO *in, +\& int selection, +\& OSSL_CALLBACK *data_cb, void *data_cbarg, +\& OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); +\& static ossl_inline OSSL_FUNC_decoder_decode_fn* +\& OSSL_FUNC_decoder_decode(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 2 +\& OSSL_FUNC_decoder_get_params OSSL_FUNC_DECODER_GET_PARAMS +\& OSSL_FUNC_decoder_gettable_params OSSL_FUNC_DECODER_GETTABLE_PARAMS +\& +\& OSSL_FUNC_decoder_newctx OSSL_FUNC_DECODER_NEWCTX +\& OSSL_FUNC_decoder_freectx OSSL_FUNC_DECODER_FREECTX +\& OSSL_FUNC_decoder_set_ctx_params OSSL_FUNC_DECODER_SET_CTX_PARAMS +\& OSSL_FUNC_decoder_settable_ctx_params OSSL_FUNC_DECODER_SETTABLE_CTX_PARAMS +\& +\& OSSL_FUNC_decoder_does_selection OSSL_FUNC_DECODER_DOES_SELECTION +\& +\& OSSL_FUNC_decoder_decode OSSL_FUNC_DECODER_DECODE +\& +\& OSSL_FUNC_decoder_export_object OSSL_FUNC_DECODER_EXPORT_OBJECT +.Ve +.SS "Names and properties" +.IX Subsection "Names and properties" +The name of an implementation should match the target type of object +it decodes. For example, an implementation that decodes an RSA key +should be named "RSA". Likewise, an implementation that decodes DER data +from PEM input should be named "DER". +.PP +Properties, as defined in the \fBOSSL_ALGORITHM\fR\|(3) array element of each +decoder implementation, can be used to further specify details about an +implementation: +.IP input 4 +.IX Item "input" +This property is used to specify what format of input the implementation +can decode. +.Sp +This property is \fImandatory\fR. +.Sp +OpenSSL providers recognize the following input types: +.RS 4 +.IP pem 4 +.IX Item "pem" +An implementation with that input type decodes PEM formatted data. +.IP der 4 +.IX Item "der" +An implementation with that input type decodes DER formatted data. +.IP msblob 4 +.IX Item "msblob" +An implementation with that input type decodes MSBLOB formatted data. +.IP pvk 4 +.IX Item "pvk" +An implementation with that input type decodes PVK formatted data. +.RE +.RS 4 +.RE +.IP structure 4 +.IX Item "structure" +This property is used to specify the structure that the decoded data is +expected to have. +.Sp +This property is \fIoptional\fR. +.Sp +Structures currently recognised by built\-in decoders: +.RS 4 +.IP """type\-specific""" 4 +.IX Item """type-specific""" +Type specific structure. +.IP """pkcs8""" 4 +.IX Item """pkcs8""" +Structure according to the PKCS#8 specification. +.IP """SubjectPublicKeyInfo""" 4 +.IX Item """SubjectPublicKeyInfo""" +Encoding of public keys according to the Subject Public Key Info of RFC 5280. +.RE +.RS 4 +.RE +.PP +The possible values of both these properties is open ended. A provider may +very well specify input types and structures that libcrypto doesn\*(Aqt know +anything about. +.SS "Subset selections" +.IX Subsection "Subset selections" +Sometimes, an object has more than one subset of data that is interesting to +treat separately or together. It\*(Aqs possible to specify what subsets are to +be decoded, with a set of bits \fIselection\fR that are passed in an \fBint\fR. +.PP +This set of bits depend entirely on what kind of provider\-side object is +to be decoded. For example, those bits are assumed to be the same as those +used with \fBprovider\-keymgmt\fR\|(7) (see "Key Objects" in \fBprovider\-keymgmt\fR\|(7)) when +the object is an asymmetric keypair \- e.g., \fBOSSL_KEYMGMT_SELECT_PRIVATE_KEY\fR +if the object to be decoded is supposed to contain private key components. +.PP +\&\fBOSSL_FUNC_decoder_does_selection()\fR should tell if a particular implementation +supports any of the combinations given by \fIselection\fR. +.SS "Context functions" +.IX Subsection "Context functions" +\&\fBOSSL_FUNC_decoder_newctx()\fR returns a context to be used with the rest of +the functions. +.PP +\&\fBOSSL_FUNC_decoder_freectx()\fR frees the given \fIctx\fR as created by +\&\fBOSSL_FUNC_decoder_newctx()\fR. +.PP +\&\fBOSSL_FUNC_decoder_set_ctx_params()\fR sets context data according to parameters +from \fIparams\fR that it recognises. Unrecognised parameters should be +ignored. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_decoder_settable_ctx_params()\fR returns a constant \fBOSSL_PARAM\fR\|(3) +array describing the parameters that \fBOSSL_FUNC_decoder_set_ctx_params()\fR +can handle. +.PP +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by +\&\fBOSSL_FUNC_decoder_set_ctx_params()\fR and \fBOSSL_FUNC_decoder_settable_ctx_params()\fR. +.SS "Export function" +.IX Subsection "Export function" +When a provider\-native object is created by a decoder it would be unsuitable +for direct use with a foreign provider. The export function allows for +exporting the object into that foreign provider if the foreign provider +supports the type of the object and provides an import function. +.PP +\&\fBOSSL_FUNC_decoder_export_object()\fR should export the object of size \fIobjref_sz\fR +referenced by \fIobjref\fR as an \fBOSSL_PARAM\fR\|(3) array and pass that into the +\&\fIexport_cb\fR as well as the given \fIexport_cbarg\fR. +.SS "Decoding functions" +.IX Subsection "Decoding functions" +\&\fBOSSL_FUNC_decoder_decode()\fR should decode the data as read from +the \fBOSSL_CORE_BIO\fR \fIin\fR to produce decoded data or an object to be +passed as reference in an \fBOSSL_PARAM\fR\|(3) array along with possible other +metadata that was decoded from the input. This \fBOSSL_PARAM\fR\|(3) array is +then passed to the \fIdata_cb\fR callback. The \fIselection\fR bits, +if relevant, should determine what the input data should contain. +The decoding functions also take an \fBOSSL_PASSPHRASE_CALLBACK\fR\|(3) function +pointer along with a pointer to application data \fIcbarg\fR, which should be +used when a pass phrase prompt is needed. +.PP +It\*(Aqs important to understand that the return value from this function is +interpreted as follows: +.IP "True (1)" 4 +.IX Item "True (1)" +This means "carry on the decoding process", and is meaningful even though +this function couldn\*(Aqt decode the input into anything, because there may be +another decoder implementation that can decode it into something. +.Sp +The \fIdata_cb\fR callback should never be called when this function can\*(Aqt +decode the input into anything. +.IP "False (0)" 4 +.IX Item "False (0)" +This means "stop the decoding process", and is meaningful when the input +could be decoded into some sort of object that this function understands, +but further treatment of that object results into errors that won\*(Aqt be +possible for some other decoder implementation to get a different result. +.PP +The conditions to stop the decoding process are at the discretion of the +implementation. +.SS "Decoder operation parameters" +.IX Subsection "Decoder operation parameters" +There are currently no operation parameters currently recognised by the +built\-in decoders. +.PP +Parameters currently recognised by the built\-in pass phrase callback: +.IP """info"" (\fBOSSL_PASSPHRASE_PARAM_INFO\fR) " 4 +.IX Item """info"" (OSSL_PASSPHRASE_PARAM_INFO) " +A string of information that will become part of the pass phrase +prompt. This could be used to give the user information on what kind +of object it\*(Aqs being prompted for. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_decoder_newctx()\fR returns a pointer to a context, or NULL on +failure. +.PP +\&\fBOSSL_FUNC_decoder_set_ctx_params()\fR returns 1, unless a recognised +parameter was invalid or caused an error, for which 0 is returned. +.PP +\&\fBOSSL_FUNC_decoder_settable_ctx_params()\fR returns a pointer to an array of +constant \fBOSSL_PARAM\fR\|(3) elements. +.PP +\&\fBOSSL_FUNC_decoder_does_selection()\fR returns 1 if the decoder implementation +supports any of the \fIselection\fR bits, otherwise 0. +.PP +\&\fBOSSL_FUNC_decoder_decode()\fR returns 1 to signal that the decoding process +should continue, or 0 to signal that it should stop. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The DECODER interface was introduced in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-digest.7 b/static/netbsd/man7/provider-digest.7 new file mode 100644 index 00000000..f829e8a2 --- /dev/null +++ b/static/netbsd/man7/provider-digest.7 @@ -0,0 +1,341 @@ +.\" $NetBSD: provider-digest.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-DIGEST 7" +.TH PROVIDER-DIGEST 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-digest \- The digest library <\-> provider functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& /* +\& * Digests support the following function signatures in OSSL_DISPATCH arrays. +\& * (The function signatures are not actual functions). +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_digest_newctx(void *provctx); +\& void OSSL_FUNC_digest_freectx(void *dctx); +\& void *OSSL_FUNC_digest_dupctx(void *dctx); +\& void OSSL_FUNC_digest_copyctx(void *voutctx, void *vinctx); +\& +\& /* Digest generation */ +\& int OSSL_FUNC_digest_init(void *dctx, const OSSL_PARAM params[]); +\& int OSSL_FUNC_digest_update(void *dctx, const unsigned char *in, size_t inl); +\& int OSSL_FUNC_digest_final(void *dctx, unsigned char *out, size_t *outl, +\& size_t outsz); +\& int OSSL_FUNC_digest_digest(void *provctx, const unsigned char *in, size_t inl, +\& unsigned char *out, size_t *outl, size_t outsz); +\& +\& /* Digest parameter descriptors */ +\& const OSSL_PARAM *OSSL_FUNC_digest_gettable_params(void *provctx); +\& +\& /* Digest operation parameter descriptors */ +\& const OSSL_PARAM *OSSL_FUNC_digest_gettable_ctx_params(void *dctx, +\& void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_digest_settable_ctx_params(void *dctx, +\& void *provctx); +\& +\& /* Digest parameters */ +\& int OSSL_FUNC_digest_get_params(OSSL_PARAM params[]); +\& +\& /* Digest operation parameters */ +\& int OSSL_FUNC_digest_set_ctx_params(void *dctx, const OSSL_PARAM params[]); +\& int OSSL_FUNC_digest_get_ctx_params(void *dctx, OSSL_PARAM params[]); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The DIGEST operation enables providers to implement digest algorithms and make +them available to applications via the API functions \fBEVP_DigestInit_ex\fR\|(3), +\&\fBEVP_DigestUpdate\fR\|(3) and \fBEVP_DigestFinal\fR\|(3) (and other related functions). +.PP +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via +\&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider\*(Aqs +\&\fBprovider_query_operation()\fR function +(see "Provider Functions" in \fBprovider\-base\fR\|(7)). +.PP +All these "functions" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the "function" \fBOSSL_FUNC_digest_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_digest_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_digest_newctx_fn +\& OSSL_FUNC_digest_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 4 +\& OSSL_FUNC_digest_newctx OSSL_FUNC_DIGEST_NEWCTX +\& OSSL_FUNC_digest_freectx OSSL_FUNC_DIGEST_FREECTX +\& OSSL_FUNC_digest_dupctx OSSL_FUNC_DIGEST_DUPCTX +\& OSSL_FUNC_digest_copyctx OSSL_FUNC_DIGEST_COPYCTX +\& +\& OSSL_FUNC_digest_init OSSL_FUNC_DIGEST_INIT +\& OSSL_FUNC_digest_update OSSL_FUNC_DIGEST_UPDATE +\& OSSL_FUNC_digest_final OSSL_FUNC_DIGEST_FINAL +\& OSSL_FUNC_digest_digest OSSL_FUNC_DIGEST_DIGEST +\& +\& OSSL_FUNC_digest_get_params OSSL_FUNC_DIGEST_GET_PARAMS +\& OSSL_FUNC_digest_get_ctx_params OSSL_FUNC_DIGEST_GET_CTX_PARAMS +\& OSSL_FUNC_digest_set_ctx_params OSSL_FUNC_DIGEST_SET_CTX_PARAMS +\& +\& OSSL_FUNC_digest_gettable_params OSSL_FUNC_DIGEST_GETTABLE_PARAMS +\& OSSL_FUNC_digest_gettable_ctx_params OSSL_FUNC_DIGEST_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_digest_settable_ctx_params OSSL_FUNC_DIGEST_SETTABLE_CTX_PARAMS +.Ve +.PP +A digest algorithm implementation may not implement all of these functions. +In order to be usable all or none of OSSL_FUNC_digest_newctx, OSSL_FUNC_digest_freectx, +OSSL_FUNC_digest_init, OSSL_FUNC_digest_update, OSSL_FUNC_digest_final +and OSSL_FUNC_digest_get_params should be implemented. +All other functions are optional. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_digest_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during a digest operation. +A pointer to this context will be passed back in a number of the other digest +operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +.PP +\&\fBOSSL_FUNC_digest_freectx()\fR is passed a pointer to the provider side digest context in +the \fIdctx\fR parameter. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_digest_dupctx()\fR should duplicate the provider side digest context in the +\&\fIdctx\fR parameter and return the duplicate copy. +.PP +\&\fBOSSL_FUNC_digest_copyctx()\fR should copy the provider side digest context in the +\&\fIvinctx\fR parameter to the \fIvoutctx\fR parameter which is the another provider side +context. +The OSSL_FUNC_digest_copyctx function is used in the EVP_MD_CTX_copy_ex function to +speed up HMAC operations in the PBKDF2. +This function is optional, and dupctx will be used if there is no EVP_MD_CTX_copy_ex +function. +.SS "Digest Generation Functions" +.IX Subsection "Digest Generation Functions" +\&\fBOSSL_FUNC_digest_init()\fR initialises a digest operation given a newly created +provider side digest context in the \fIdctx\fR parameter. +The \fIparams\fR, if not NULL, should be set on the context in a manner similar to +using \fBOSSL_FUNC_digest_set_ctx_params()\fR. +.PP +\&\fBOSSL_FUNC_digest_update()\fR is called to supply data to be digested as part of a +previously initialised digest operation. +The \fIdctx\fR parameter contains a pointer to a previously initialised provider +side context. +\&\fBOSSL_FUNC_digest_update()\fR should digest \fIinl\fR bytes of data at the location pointed to +by \fIin\fR. +\&\fBOSSL_FUNC_digest_update()\fR may be called multiple times for a single digest operation. +.PP +\&\fBOSSL_FUNC_digest_final()\fR generates a digest started through previous \fBOSSL_FUNC_digest_init()\fR +and \fBOSSL_FUNC_digest_update()\fR calls. +The \fIdctx\fR parameter contains a pointer to the provider side context. +The digest should be written to \fI*out\fR and the length of the digest to +\&\fI*outl\fR. +The digest should not exceed \fIoutsz\fR bytes. +.PP +\&\fBOSSL_FUNC_digest_digest()\fR is a "oneshot" digest function. +No provider side digest context is used. +Instead the provider context that was created during provider initialisation is +passed in the \fIprovctx\fR parameter (see \fBprovider\fR\|(7)). +\&\fIinl\fR bytes at \fIin\fR should be digested and the result should be stored at +\&\fIout\fR. The length of the digest should be stored in \fI*outl\fR which should not +exceed \fIoutsz\fR bytes. +.SS "Digest Parameters" +.IX Subsection "Digest Parameters" +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by +these functions. +.PP +\&\fBOSSL_FUNC_digest_get_params()\fR gets details of the algorithm implementation +and stores them in \fIparams\fR. +.PP +\&\fBOSSL_FUNC_digest_set_ctx_params()\fR sets digest operation parameters for the +provider side digest context \fIdctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_digest_get_ctx_params()\fR gets digest operation details details from +the given provider side digest context \fIdctx\fR and stores them in \fIparams\fR. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_digest_gettable_params()\fR returns a constant \fBOSSL_PARAM\fR\|(3) array +containing descriptors of the parameters that \fBOSSL_FUNC_digest_get_params()\fR +can handle. +.PP +\&\fBOSSL_FUNC_digest_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_digest_settable_ctx_params()\fR both return constant +\&\fBOSSL_PARAM\fR\|(3) arrays as descriptors of the parameters that +\&\fBOSSL_FUNC_digest_get_ctx_params()\fR and \fBOSSL_FUNC_digest_set_ctx_params()\fR +can handle, respectively. The array is based on the current state of +the provider side context if \fIdctx\fR is not NULL and on the provider +side algorithm \fIprovctx\fR otherwise. +.PP +Parameters currently recognised by built\-in digests with this function +are as follows. Not all parameters are relevant to, or are understood +by all digests: +.IP """blocksize"" (\fBOSSL_DIGEST_PARAM_BLOCK_SIZE\fR) " 4 +.IX Item """blocksize"" (OSSL_DIGEST_PARAM_BLOCK_SIZE) " +The digest block size. +The length of the "blocksize" parameter should not exceed that of a \fBsize_t\fR. +.IP """size"" (\fBOSSL_DIGEST_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_DIGEST_PARAM_SIZE) " +The digest output size. +The length of the "size" parameter should not exceed that of a \fBsize_t\fR. +.IP """flags"" (\fBOSSL_DIGEST_PARAM_FLAGS\fR) " 4 +.IX Item """flags"" (OSSL_DIGEST_PARAM_FLAGS) " +Diverse flags that describe exceptional behaviour for the digest: +.RS 4 +.IP \fBEVP_MD_FLAG_ONESHOT\fR 4 +.IX Item "EVP_MD_FLAG_ONESHOT" +This digest method can only handle one block of input. +.IP \fBEVP_MD_FLAG_XOF\fR 4 +.IX Item "EVP_MD_FLAG_XOF" +This digest method is an extensible\-output function (XOF). +.IP \fBEVP_MD_FLAG_DIGALGID_NULL\fR 4 +.IX Item "EVP_MD_FLAG_DIGALGID_NULL" +When setting up a DigestAlgorithmIdentifier, this flag will have the +parameter set to NULL by default. Use this for PKCS#1. \fINote: if +combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.\fR +.IP \fBEVP_MD_FLAG_DIGALGID_ABSENT\fR 4 +.IX Item "EVP_MD_FLAG_DIGALGID_ABSENT" +When setting up a DigestAlgorithmIdentifier, this flag will have the +parameter be left absent by default. \fINote: if combined with +EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.\fR +.IP \fBEVP_MD_FLAG_DIGALGID_CUSTOM\fR 4 +.IX Item "EVP_MD_FLAG_DIGALGID_CUSTOM" +Custom DigestAlgorithmIdentifier handling via ctrl, with +\&\fBEVP_MD_FLAG_DIGALGID_ABSENT\fR as default. \fINote: if combined with +EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.\fR +Currently unused. +.RE +.RS 4 +.Sp +The length of the "flags" parameter should equal that of an +\&\fBunsigned long int\fR. +.RE +.SS "Digest Context Parameters" +.IX Subsection "Digest Context Parameters" +\&\fBOSSL_FUNC_digest_set_ctx_params()\fR sets digest parameters associated with the +given provider side digest context \fIdctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure. +.PP +\&\fBOSSL_FUNC_digest_get_ctx_params()\fR gets details of currently set parameters +values associated with the give provider side digest context \fIdctx\fR +and stores them in \fIparams\fR. +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_digest_newctx()\fR and \fBOSSL_FUNC_digest_dupctx()\fR should return the newly created +provider side digest context, or NULL on failure. +.PP +\&\fBOSSL_FUNC_digest_init()\fR, \fBOSSL_FUNC_digest_update()\fR, \fBOSSL_FUNC_digest_final()\fR, \fBOSSL_FUNC_digest_digest()\fR, +\&\fBOSSL_FUNC_digest_set_params()\fR and \fBOSSL_FUNC_digest_get_params()\fR should return 1 for success or +0 on error. +.PP +\&\fBOSSL_FUNC_digest_size()\fR should return the digest size. +.PP +\&\fBOSSL_FUNC_digest_block_size()\fR should return the block size of the underlying digest +algorithm. +.SH BUGS +.IX Header "BUGS" +The \fBEVP_Q_digest()\fR, \fBEVP_Digest()\fR and \fBEVP_DigestFinal_ex()\fR API calls do not +expect the digest size to be larger than EVP_MAX_MD_SIZE. Any algorithm which +produces larger digests is unusable with those API calls. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), +\&\fBOSSL_PROVIDER\-legacy\fR\|(7), +\&\fBEVP_MD\-common\fR\|(7), \fBEVP_MD\-BLAKE2\fR\|(7), \fBEVP_MD\-MD2\fR\|(7), +\&\fBEVP_MD\-MD4\fR\|(7), \fBEVP_MD\-MD5\fR\|(7), \fBEVP_MD\-MD5\-SHA1\fR\|(7), +\&\fBEVP_MD\-MDC2\fR\|(7), \fBEVP_MD\-RIPEMD160\fR\|(7), \fBEVP_MD\-SHA1\fR\|(7), +\&\fBEVP_MD\-SHA2\fR\|(7), \fBEVP_MD\-SHA3\fR\|(7), \fBEVP_MD\-KECCAK\fR\|(7) +\&\fBEVP_MD\-SHAKE\fR\|(7), \fBEVP_MD\-SM3\fR\|(7), \fBEVP_MD\-WHIRLPOOL\fR\|(7), +\&\fBEVP_MD\-NULL\fR\|(7), +\&\fBlife_cycle\-digest\fR\|(7), \fBEVP_DigestInit\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The provider DIGEST interface was introduced in OpenSSL 3.0. +\&\fBOSSL_FUNC_digest_copyctx()\fR was added in 3.5 version. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-encoder.7 b/static/netbsd/man7/provider-encoder.7 new file mode 100644 index 00000000..f43a01e6 --- /dev/null +++ b/static/netbsd/man7/provider-encoder.7 @@ -0,0 +1,355 @@ +.\" $NetBSD: provider-encoder.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-ENCODER 7" +.TH PROVIDER-ENCODER 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-encoder \- The OSSL_ENCODER library <\-> provider functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Encoder parameter accessor and descriptor */ +\& const OSSL_PARAM *OSSL_FUNC_encoder_gettable_params(void *provctx); +\& int OSSL_FUNC_encoder_get_params(OSSL_PARAM params[]); +\& +\& /* Functions to construct / destruct / manipulate the encoder context */ +\& void *OSSL_FUNC_encoder_newctx(void *provctx); +\& void OSSL_FUNC_encoder_freectx(void *ctx); +\& int OSSL_FUNC_encoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_encoder_settable_ctx_params(void *provctx); +\& +\& /* Functions to check selection support */ +\& int OSSL_FUNC_encoder_does_selection(void *provctx, int selection); +\& +\& /* Functions to encode object data */ +\& int OSSL_FUNC_encoder_encode(void *ctx, OSSL_CORE_BIO *out, +\& const void *obj_raw, +\& const OSSL_PARAM obj_abstract[], +\& int selection, +\& OSSL_PASSPHRASE_CALLBACK *cb, +\& void *cbarg); +\& +\& /* Functions to import and free a temporary object to be encoded */ +\& void *OSSL_FUNC_encoder_import_object(void *ctx, int selection, +\& const OSSL_PARAM params[]); +\& void OSSL_FUNC_encoder_free_object(void *obj); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fIWe use the wide term "encode" in this manual. This includes but is +not limited to serialization.\fR +.PP +The ENCODER operation is a generic method to encode a provider\-native +object (\fIobj_raw\fR) or an object abstraction (\fIobject_abstract\fR, see +\&\fBprovider\-object\fR\|(7)) into an encoded form, and write the result to +the given OSSL_CORE_BIO. If the caller wants to get the encoded +stream to memory, it should provide a \fBBIO_s_mem\fR\|(3) \fBBIO\fR. +.PP +The encoder doesn\*(Aqt need to know more about the \fBOSSL_CORE_BIO\fR +pointer than being able to pass it to the appropriate BIO upcalls (see +"Core functions" in \fBprovider\-base\fR\|(7)). +.PP +The ENCODER implementation may be part of a chain, where data is +passed from one to the next. For example, there may be an +implementation to encode an object to DER (that object is assumed to +be provider\-native and thereby passed via \fIobj_raw\fR), and another one +that encodes DER to PEM (that one would receive the DER encoding via +\&\fIobj_abstract\fR). +.PP +The encoding using the \fBOSSL_PARAM\fR\|(3) array form allows a +encoder to be used for data that\*(Aqs been exported from another +provider, and thereby allow them to exist independently of each +other. +.PP +The encoding using a provider side object can only be safely used +with provider data coming from the same provider, for example keys +with the KEYMGMT provider. +.PP +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via +\&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider\*(Aqs +\&\fBprovider_query_operation()\fR function +(see "Provider Functions" in \fBprovider\-base\fR\|(7)). +.PP +All these "functions" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the "function" \fBOSSL_FUNC_encoder_encode()\fR has these: +.PP +.Vb 8 +\& typedef int +\& (OSSL_FUNC_encoder_encode_fn)(void *ctx, OSSL_CORE_BIO *out, +\& const void *obj_raw, +\& const OSSL_PARAM obj_abstract[], +\& int selection, +\& OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); +\& static ossl_inline OSSL_FUNC_encoder_encode_fn +\& OSSL_FUNC_encoder_encode(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 2 +\& OSSL_FUNC_encoder_get_params OSSL_FUNC_ENCODER_GET_PARAMS +\& OSSL_FUNC_encoder_gettable_params OSSL_FUNC_ENCODER_GETTABLE_PARAMS +\& +\& OSSL_FUNC_encoder_newctx OSSL_FUNC_ENCODER_NEWCTX +\& OSSL_FUNC_encoder_freectx OSSL_FUNC_ENCODER_FREECTX +\& OSSL_FUNC_encoder_set_ctx_params OSSL_FUNC_ENCODER_SET_CTX_PARAMS +\& OSSL_FUNC_encoder_settable_ctx_params OSSL_FUNC_ENCODER_SETTABLE_CTX_PARAMS +\& +\& OSSL_FUNC_encoder_does_selection OSSL_FUNC_ENCODER_DOES_SELECTION +\& +\& OSSL_FUNC_encoder_encode OSSL_FUNC_ENCODER_ENCODE +\& +\& OSSL_FUNC_encoder_import_object OSSL_FUNC_ENCODER_IMPORT_OBJECT +\& OSSL_FUNC_encoder_free_object OSSL_FUNC_ENCODER_FREE_OBJECT +.Ve +.SS "Names and properties" +.IX Subsection "Names and properties" +The name of an implementation should match the type of object it handles. +For example, an implementation that encodes an RSA key should be named "RSA". +Likewise, an implementation that further encodes DER should be named "DER". +.PP +Properties, as defined in the \fBOSSL_ALGORITHM\fR\|(3) array element of each +decoder implementation, can be used to further specify details about an +implementation: +.IP output 4 +.IX Item "output" +This property is used to specify what type of output the implementation +produces. +.Sp +This property is \fImandatory\fR. +.Sp +OpenSSL providers recognize the following output types: +.RS 4 +.IP text 4 +.IX Item "text" +An implementation with that output type outputs human readable text, making +that implementation suitable for \f(CW\*(C`\-text\*(C'\fR output in diverse \fBopenssl\fR\|(1) +commands. +.IP pem 4 +.IX Item "pem" +An implementation with that output type outputs PEM formatted data. +.IP der 4 +.IX Item "der" +An implementation with that output type outputs DER formatted data. +.IP msblob 4 +.IX Item "msblob" +An implementation with that output type outputs MSBLOB formatted data. +.IP pvk 4 +.IX Item "pvk" +An implementation with that output type outputs PVK formatted data. +.RE +.RS 4 +.RE +.IP structure 4 +.IX Item "structure" +This property is used to specify the structure that is used for the encoded +object. An example could be \f(CW\*(C`pkcs8\*(C'\fR, to specify explicitly that an object +(presumably an asymmetric key pair, in this case) will be wrapped in a +PKCS#8 structure as part of the encoding. +.Sp +This property is \fIoptional\fR. +.PP +The possible values of both these properties is open ended. A provider may +very well specify output types and structures that libcrypto doesn\*(Aqt know +anything about. +.SS "Subset selections" +.IX Subsection "Subset selections" +Sometimes, an object has more than one subset of data that is interesting to +treat separately or together. It\*(Aqs possible to specify what subsets are to +be encoded, with a set of bits \fIselection\fR that are passed in an \fBint\fR. +.PP +This set of bits depend entirely on what kind of provider\-side object is +passed. For example, those bits are assumed to be the same as those used +with \fBprovider\-keymgmt\fR\|(7) (see "Key Objects" in \fBprovider\-keymgmt\fR\|(7)) when +the object is an asymmetric keypair. +.PP +ENCODER implementations are free to regard the \fIselection\fR as a set of +hints, but must do so with care. In the end, the output must make sense, +and if there\*(Aqs a corresponding decoder, the resulting decoded object must +match the original object that was encoded. +.PP +\&\fBOSSL_FUNC_encoder_does_selection()\fR should tell if a particular implementation +supports any of the combinations given by \fIselection\fR. +.SS "Context functions" +.IX Subsection "Context functions" +\&\fBOSSL_FUNC_encoder_newctx()\fR returns a context to be used with the rest of +the functions. +.PP +\&\fBOSSL_FUNC_encoder_freectx()\fR frees the given \fIctx\fR, if it was created by +\&\fBOSSL_FUNC_encoder_newctx()\fR. +.PP +\&\fBOSSL_FUNC_encoder_set_ctx_params()\fR sets context data according to parameters +from \fIparams\fR that it recognises. Unrecognised parameters should be +ignored. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_encoder_settable_ctx_params()\fR returns a constant \fBOSSL_PARAM\fR\|(3) +array describing the parameters that \fBOSSL_FUNC_encoder_set_ctx_params()\fR +can handle. +.PP +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by +\&\fBOSSL_FUNC_encoder_set_ctx_params()\fR and \fBOSSL_FUNC_encoder_settable_ctx_params()\fR. +.SS "Import functions" +.IX Subsection "Import functions" +A provider\-native object may be associated with a foreign provider, and may +therefore be unsuitable for direct use with a given ENCODER implementation. +Provided that the foreign provider\*(Aqs implementation to handle the object has +a function to export that object in \fBOSSL_PARAM\fR\|(3) array form, the ENCODER +implementation should be able to import that array and create a suitable +object to be passed to \fBOSSL_FUNC_encoder_encode()\fR\*(Aqs \fIobj_raw\fR. +.PP +\&\fBOSSL_FUNC_encoder_import_object()\fR should import the subset of \fIparams\fR +given with \fIselection\fR to create a provider\-native object that can be +passed as \fIobj_raw\fR to \fBOSSL_FUNC_encoder_encode()\fR. +.PP +\&\fBOSSL_FUNC_encoder_free_object()\fR should free the object that was created with +\&\fBOSSL_FUNC_encoder_import_object()\fR. +.SS "Encoding functions" +.IX Subsection "Encoding functions" +\&\fBOSSL_FUNC_encoder_encode()\fR should take a provider\-native object (in +\&\fIobj_raw\fR) or an object abstraction (in \fIobj_abstract\fR), and should output +the object in encoded form to the \fBOSSL_CORE_BIO\fR. The \fIselection\fR bits, +if relevant, should determine in greater detail what will be output. +The encoding functions also take an \fBOSSL_PASSPHRASE_CALLBACK\fR\|(3) function +pointer along with a pointer to application data \fIcbarg\fR, which should be +used when a pass phrase prompt is needed. +.SS "Encoder operation parameters" +.IX Subsection "Encoder operation parameters" +Operation parameters currently recognised by built\-in encoders are as +follows: +.IP """cipher"" (\fBOSSL_ENCODER_PARAM_CIPHER\fR) " 4 +.IX Item """cipher"" (OSSL_ENCODER_PARAM_CIPHER) " +The name of the encryption cipher to be used when generating encrypted +encoding. This is used when encoding private keys, as well as +other objects that need protection. +.Sp +If this name is invalid for the encoding implementation, the +implementation should refuse to perform the encoding, i.e. +\&\fBOSSL_FUNC_encoder_encode_data()\fR and \fBOSSL_FUNC_encoder_encode_object()\fR +should return an error. +.IP """properties"" (\fBOSSL_ENCODER_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_ENCODER_PARAM_PROPERTIES) " +The properties to be queried when trying to fetch the algorithm given +with the "cipher" parameter. +This must be given together with the "cipher" parameter to be +considered valid. +.Sp +The encoding implementation isn\*(Aqt obligated to use this value. +However, it is recommended that implementations that do not handle +property strings return an error on receiving this parameter unless +its value NULL or the empty string. +.IP """save\-parameters"" (\fBOSSL_ENCODER_PARAM_SAVE_PARAMETERS\fR) " 4 +.IX Item """save-parameters"" (OSSL_ENCODER_PARAM_SAVE_PARAMETERS) " +If set to 0 disables saving of key domain parameters. Default is 1. +It currently has an effect only on DSA keys. +.PP +Parameters currently recognised by the built\-in pass phrase callback: +.IP """info"" (\fBOSSL_PASSPHRASE_PARAM_INFO\fR) " 4 +.IX Item """info"" (OSSL_PASSPHRASE_PARAM_INFO) " +A string of information that will become part of the pass phrase +prompt. This could be used to give the user information on what kind +of object it\*(Aqs being prompted for. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_encoder_newctx()\fR returns a pointer to a context, or NULL on +failure. +.PP +\&\fBOSSL_FUNC_encoder_set_ctx_params()\fR returns 1, unless a recognised +parameter was invalid or caused an error, for which 0 is returned. +.PP +\&\fBOSSL_FUNC_encoder_settable_ctx_params()\fR returns a pointer to an array of +constant \fBOSSL_PARAM\fR\|(3) elements. +.PP +\&\fBOSSL_FUNC_encoder_does_selection()\fR returns 1 if the encoder implementation +supports any of the \fIselection\fR bits, otherwise 0. +.PP +\&\fBOSSL_FUNC_encoder_encode()\fR returns 1 on success, or 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The ENCODER interface was introduced in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-kdf.7 b/static/netbsd/man7/provider-kdf.7 new file mode 100644 index 00000000..e0e37357 --- /dev/null +++ b/static/netbsd/man7/provider-kdf.7 @@ -0,0 +1,381 @@ +.\" $NetBSD: provider-kdf.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-KDF 7" +.TH PROVIDER-KDF 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-kdf \- The KDF library <\-> provider functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_kdf_newctx(void *provctx); +\& void OSSL_FUNC_kdf_freectx(void *kctx); +\& void *OSSL_FUNC_kdf_dupctx(void *src); +\& +\& /* Encryption/decryption */ +\& int OSSL_FUNC_kdf_reset(void *kctx); +\& int OSSL_FUNC_kdf_derive(void *kctx, unsigned char *key, size_t keylen, +\& const OSSL_PARAM params[]); +\& +\& /* KDF parameter descriptors */ +\& const OSSL_PARAM *OSSL_FUNC_kdf_gettable_params(void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_kdf_gettable_ctx_params(void *kcxt, void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_kdf_settable_ctx_params(void *kcxt, void *provctx); +\& +\& /* KDF parameters */ +\& int OSSL_FUNC_kdf_get_params(OSSL_PARAM params[]); +\& int OSSL_FUNC_kdf_get_ctx_params(void *kctx, OSSL_PARAM params[]); +\& int OSSL_FUNC_kdf_set_ctx_params(void *kctx, const OSSL_PARAM params[]); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The KDF operation enables providers to implement KDF algorithms and make +them available to applications via the API functions \fBEVP_KDF_CTX_reset\fR\|(3), +and \fBEVP_KDF_derive\fR\|(3). +.PP +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via +\&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider\*(Aqs +\&\fBprovider_query_operation()\fR function +(see "Provider Functions" in \fBprovider\-base\fR\|(7)). +.PP +All these "functions" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the "function" \fBOSSL_FUNC_kdf_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_kdf_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_kdf_newctx_fn +\& OSSL_FUNC_kdf_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\fBOSSL_DISPATCH\fR\|(3) array entries are identified by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_kdf_newctx OSSL_FUNC_KDF_NEWCTX +\& OSSL_FUNC_kdf_freectx OSSL_FUNC_KDF_FREECTX +\& OSSL_FUNC_kdf_dupctx OSSL_FUNC_KDF_DUPCTX +\& +\& OSSL_FUNC_kdf_reset OSSL_FUNC_KDF_RESET +\& OSSL_FUNC_kdf_derive OSSL_FUNC_KDF_DERIVE +\& +\& OSSL_FUNC_kdf_get_params OSSL_FUNC_KDF_GET_PARAMS +\& OSSL_FUNC_kdf_get_ctx_params OSSL_FUNC_KDF_GET_CTX_PARAMS +\& OSSL_FUNC_kdf_set_ctx_params OSSL_FUNC_KDF_SET_CTX_PARAMS +\& +\& OSSL_FUNC_kdf_gettable_params OSSL_FUNC_KDF_GETTABLE_PARAMS +\& OSSL_FUNC_kdf_gettable_ctx_params OSSL_FUNC_KDF_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_kdf_settable_ctx_params OSSL_FUNC_KDF_SETTABLE_CTX_PARAMS +.Ve +.PP +A KDF algorithm implementation may not implement all of these functions. +In order to be a consistent set of functions, at least the following functions +must be implemented: \fBOSSL_FUNC_kdf_newctx()\fR, \fBOSSL_FUNC_kdf_freectx()\fR, +\&\fBOSSL_FUNC_kdf_set_ctx_params()\fR, \fBOSSL_FUNC_kdf_derive()\fR. +All other functions are optional. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_kdf_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during a KDF operation. +A pointer to this context will be passed back in a number of the other KDF +operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +.PP +\&\fBOSSL_FUNC_kdf_freectx()\fR is passed a pointer to the provider side KDF context in +the \fIkctx\fR parameter. +If it receives NULL as \fIkctx\fR value, it should not do anything other than +return. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_kdf_dupctx()\fR should duplicate the provider side KDF context in the +\&\fIkctx\fR parameter and return the duplicate copy. +.SS "Encryption/Decryption Functions" +.IX Subsection "Encryption/Decryption Functions" +\&\fBOSSL_FUNC_kdf_reset()\fR initialises a KDF operation given a provider +side KDF context in the \fIkctx\fR parameter. +.PP +\&\fBOSSL_FUNC_kdf_derive()\fR performs the KDF operation after processing the +\&\fIparams\fR as per \fBOSSL_FUNC_kdf_set_ctx_params()\fR. +The \fIkctx\fR parameter contains a pointer to the provider side context. +The resulting key of the desired \fIkeylen\fR should be written to \fIkey\fR. +If the algorithm does not support the requested \fIkeylen\fR the function must +return error. +.SS "KDF Parameters" +.IX Subsection "KDF Parameters" +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by +these functions. +.PP +\&\fBOSSL_FUNC_kdf_get_params()\fR gets details of parameter values associated with the +provider algorithm and stores them in \fIparams\fR. +.PP +\&\fBOSSL_FUNC_kdf_set_ctx_params()\fR sets KDF parameters associated with the given +provider side KDF context \fIkctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_kdf_get_ctx_params()\fR retrieves gettable parameter values associated +with the given provider side KDF context \fIkctx\fR and stores them in \fIparams\fR. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_kdf_gettable_params()\fR, \fBOSSL_FUNC_kdf_gettable_ctx_params()\fR, +and \fBOSSL_FUNC_kdf_settable_ctx_params()\fR all return constant \fBOSSL_PARAM\fR\|(3) +arrays as descriptors of the parameters that \fBOSSL_FUNC_kdf_get_params()\fR, +\&\fBOSSL_FUNC_kdf_get_ctx_params()\fR, and \fBOSSL_FUNC_kdf_set_ctx_params()\fR +can handle, respectively. \fBOSSL_FUNC_kdf_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_kdf_settable_ctx_params()\fR will return the parameters associated +with the provider side context \fIkctx\fR in its current state if it is +not NULL. Otherwise, they return the parameters associated with the +provider side algorithm \fIprovctx\fR. +.PP +Parameters currently recognised by built\-in KDFs are as follows. Not all +parameters are relevant to, or are understood by all KDFs: +.IP """size"" (\fBOSSL_KDF_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_KDF_PARAM_SIZE) " +Gets the output size from the associated KDF ctx. +If the algorithm produces a variable amount of output, SIZE_MAX should be +returned. +If the input parameters required to calculate the fixed output size have not yet +been supplied, 0 should be returned indicating an error. +.IP """key"" (\fBOSSL_KDF_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_KDF_PARAM_KEY) " +Sets the key in the associated KDF ctx. +.IP """secret"" (\fBOSSL_KDF_PARAM_SECRET\fR) " 4 +.IX Item """secret"" (OSSL_KDF_PARAM_SECRET) " +Sets the secret in the associated KDF ctx. +.IP """pass"" (\fBOSSL_KDF_PARAM_PASSWORD\fR) " 4 +.IX Item """pass"" (OSSL_KDF_PARAM_PASSWORD) " +Sets the password in the associated KDF ctx. +.IP """cipher"" (\fBOSSL_KDF_PARAM_CIPHER\fR) " 4 +.IX Item """cipher"" (OSSL_KDF_PARAM_CIPHER) " +.PD 0 +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) " +.IP """mac"" (\fBOSSL_KDF_PARAM_MAC\fR) " 4 +.IX Item """mac"" (OSSL_KDF_PARAM_MAC) " +.PD +Sets the name of the underlying cipher, digest or MAC to be used. +It must name a suitable algorithm for the KDF that\*(Aqs being used. +.IP """maclen"" (\fBOSSL_KDF_PARAM_MAC_SIZE\fR) " 4 +.IX Item """maclen"" (OSSL_KDF_PARAM_MAC_SIZE) " +Sets the length of the MAC in the associated KDF ctx. +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +Sets the properties to be queried when trying to fetch the underlying algorithm. +This must be given together with the algorithm naming parameter to be +considered valid. +.IP """iter"" (\fBOSSL_KDF_PARAM_ITER\fR) " 4 +.IX Item """iter"" (OSSL_KDF_PARAM_ITER) " +Sets the number of iterations in the associated KDF ctx. +.IP """mode"" (\fBOSSL_KDF_PARAM_MODE\fR) " 4 +.IX Item """mode"" (OSSL_KDF_PARAM_MODE) " +Sets the mode in the associated KDF ctx. +.IP """pkcs5"" (\fBOSSL_KDF_PARAM_PKCS5\fR) " 4 +.IX Item """pkcs5"" (OSSL_KDF_PARAM_PKCS5) " +Enables or disables the SP800\-132 compliance checks. +A mode of 0 enables the compliance checks. +.Sp +The checks performed are: +.RS 4 +.IP "\- the iteration count is at least 1000." 4 +.IX Item "- the iteration count is at least 1000." +.PD 0 +.IP "\- the salt length is at least 128 bits." 4 +.IX Item "- the salt length is at least 128 bits." +.IP "\- the derived key length is at least 112 bits." 4 +.IX Item "- the derived key length is at least 112 bits." +.PD +.RE +.RS 4 +.RE +.IP """ukm"" (\fBOSSL_KDF_PARAM_UKM\fR) " 4 +.IX Item """ukm"" (OSSL_KDF_PARAM_UKM) " +Sets an optional random string that is provided by the sender called +"partyAInfo". In CMS this is the user keying material. +.IP """cekalg"" (\fBOSSL_KDF_PARAM_CEK_ALG\fR) " 4 +.IX Item """cekalg"" (OSSL_KDF_PARAM_CEK_ALG) " +Sets the CEK wrapping algorithm name in the associated KDF ctx. +.IP """n"" (\fBOSSL_KDF_PARAM_SCRYPT_N\fR) " 4 +.IX Item """n"" (OSSL_KDF_PARAM_SCRYPT_N) " +Sets the scrypt work factor parameter N in the associated KDF ctx. +.IP """r"" (\fBOSSL_KDF_PARAM_SCRYPT_R\fR) " 4 +.IX Item """r"" (OSSL_KDF_PARAM_SCRYPT_R) " +Sets the scrypt work factor parameter r in the associated KDF ctx. +.IP """p"" (\fBOSSL_KDF_PARAM_SCRYPT_P\fR) " 4 +.IX Item """p"" (OSSL_KDF_PARAM_SCRYPT_P) " +Sets the scrypt work factor parameter p in the associated KDF ctx. +.IP """maxmem_bytes"" (\fBOSSL_KDF_PARAM_SCRYPT_MAXMEM\fR) " 4 +.IX Item """maxmem_bytes"" (OSSL_KDF_PARAM_SCRYPT_MAXMEM) " +Sets the scrypt work factor parameter maxmem in the associated KDF ctx. +.IP """prefix"" (\fBOSSL_KDF_PARAM_PREFIX\fR) " 4 +.IX Item """prefix"" (OSSL_KDF_PARAM_PREFIX) " +Sets the prefix string using by the TLS 1.3 version of HKDF in the +associated KDF ctx. +.IP """label"" (\fBOSSL_KDF_PARAM_LABEL\fR) " 4 +.IX Item """label"" (OSSL_KDF_PARAM_LABEL) " +Sets the label string using by the TLS 1.3 version of HKDF in the +associated KDF ctx. +.IP """data"" (\fBOSSL_KDF_PARAM_DATA\fR) " 4 +.IX Item """data"" (OSSL_KDF_PARAM_DATA) " +Sets the context string using by the TLS 1.3 version of HKDF in the +associated KDF ctx. +.IP """info"" (\fBOSSL_KDF_PARAM_INFO\fR) " 4 +.IX Item """info"" (OSSL_KDF_PARAM_INFO) " +Sets the optional shared info in the associated KDF ctx. +.IP """seed"" (\fBOSSL_KDF_PARAM_SEED\fR) " 4 +.IX Item """seed"" (OSSL_KDF_PARAM_SEED) " +Sets the IV in the associated KDF ctx. +.IP """xcghash"" (\fBOSSL_KDF_PARAM_SSHKDF_XCGHASH\fR) " 4 +.IX Item """xcghash"" (OSSL_KDF_PARAM_SSHKDF_XCGHASH) " +Sets the xcghash in the associated KDF ctx. +.IP """session_id"" (\fBOSSL_KDF_PARAM_SSHKDF_SESSION_ID\fR) " 4 +.IX Item """session_id"" (OSSL_KDF_PARAM_SSHKDF_SESSION_ID) " +Sets the session ID in the associated KDF ctx. +.IP """type"" (\fBOSSL_KDF_PARAM_SSHKDF_TYPE\fR) " 4 +.IX Item """type"" (OSSL_KDF_PARAM_SSHKDF_TYPE) " +Sets the SSH KDF type parameter in the associated KDF ctx. +There are six supported types: +.RS 4 +.IP EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV" +The Initial IV from client to server. +A single char of value 65 (ASCII char \*(AqA\*(Aq). +.IP EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI" +The Initial IV from server to client +A single char of value 66 (ASCII char \*(AqB\*(Aq). +.IP EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV" +The Encryption Key from client to server +A single char of value 67 (ASCII char \*(AqC\*(Aq). +.IP EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI" +The Encryption Key from server to client +A single char of value 68 (ASCII char \*(AqD\*(Aq). +.IP EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV" +The Integrity Key from client to server +A single char of value 69 (ASCII char \*(AqE\*(Aq). +.IP EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI 4 +.IX Item "EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI" +The Integrity Key from client to server +A single char of value 70 (ASCII char \*(AqF\*(Aq). +.RE +.RS 4 +.RE +.IP """constant"" (\fBOSSL_KDF_PARAM_CONSTANT\fR) " 4 +.IX Item """constant"" (OSSL_KDF_PARAM_CONSTANT) " +Sets the constant value in the associated KDF ctx. +.IP """id"" (\fBOSSL_KDF_PARAM_PKCS12_ID\fR) " 4 +.IX Item """id"" (OSSL_KDF_PARAM_PKCS12_ID) " +Sets the intended usage of the output bits in the associated KDF ctx. +It is defined as per RFC 7292 section B.3. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_kdf_newctx()\fR and \fBOSSL_FUNC_kdf_dupctx()\fR should return the newly created +provider side KDF context, or NULL on failure. +.PP +\&\fBOSSL_FUNC_kdf_derive()\fR, \fBOSSL_FUNC_kdf_get_params()\fR, +\&\fBOSSL_FUNC_kdf_get_ctx_params()\fR and \fBOSSL_FUNC_kdf_set_ctx_params()\fR should return 1 for +success or 0 on error. +.PP +\&\fBOSSL_FUNC_kdf_gettable_params()\fR, \fBOSSL_FUNC_kdf_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_kdf_settable_ctx_params()\fR should return a constant \fBOSSL_PARAM\fR\|(3) +array, or NULL if none is offered. +.SH NOTES +.IX Header "NOTES" +The KDF life\-cycle is described in \fBlife_cycle\-kdf\fR\|(7). Providers should +ensure that the various transitions listed there are supported. At some point +the EVP layer will begin enforcing the listed transitions. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \fBlife_cycle\-kdf\fR\|(7), \fBEVP_KDF\fR\|(3). +.SH HISTORY +.IX Header "HISTORY" +The provider KDF interface was introduced in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-kem.7 b/static/netbsd/man7/provider-kem.7 new file mode 100644 index 00000000..6af04611 --- /dev/null +++ b/static/netbsd/man7/provider-kem.7 @@ -0,0 +1,309 @@ +.\" $NetBSD: provider-kem.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-KEM 7" +.TH PROVIDER-KEM 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-kem \- The kem library <\-> provider functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_kem_newctx(void *provctx); +\& void OSSL_FUNC_kem_freectx(void *ctx); +\& void *OSSL_FUNC_kem_dupctx(void *ctx); +\& +\& /* Encapsulation */ +\& int OSSL_FUNC_kem_encapsulate_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_kem_auth_encapsulate_init(void *ctx, void *provkey, +\& void *provauthkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_kem_encapsulate(void *ctx, unsigned char *out, size_t *outlen, +\& unsigned char *secret, size_t *secretlen); +\& +\& /* Decapsulation */ +\& int OSSL_FUNC_kem_decapsulate_init(void *ctx, void *provkey); +\& int OSSL_FUNC_kem_auth_decapsulate_init(void *ctx, void *provkey, +\& void *provauthkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_kem_decapsulate(void *ctx, unsigned char *out, size_t *outlen, +\& const unsigned char *in, size_t inlen); +\& +\& /* KEM parameters */ +\& int OSSL_FUNC_kem_get_ctx_params(void *ctx, OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_kem_gettable_ctx_params(void *ctx, void *provctx); +\& int OSSL_FUNC_kem_set_ctx_params(void *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_kem_settable_ctx_params(void *ctx, void *provctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The asymmetric kem (OSSL_OP_KEM) operation enables providers to +implement asymmetric kem algorithms and make them available to applications +via the API functions \fBEVP_PKEY_encapsulate\fR\|(3), +\&\fBEVP_PKEY_decapsulate\fR\|(3) and other related functions. +.PP +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via +\&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider\*(Aqs +\&\fBprovider_query_operation()\fR function +(see "Provider Functions" in \fBprovider\-base\fR\|(7)). +.PP +All these "functions" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the "function" \fBOSSL_FUNC_kem_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_kem_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_kem_newctx_fn +\& OSSL_FUNC_kem_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_kem_newctx OSSL_FUNC_KEM_NEWCTX +\& OSSL_FUNC_kem_freectx OSSL_FUNC_KEM_FREECTX +\& OSSL_FUNC_kem_dupctx OSSL_FUNC_KEM_DUPCTX +\& +\& OSSL_FUNC_kem_encapsulate_init OSSL_FUNC_KEM_ENCAPSULATE_INIT +\& OSSL_FUNC_kem_auth_encapsulate_init OSSL_FUNC_KEM_AUTH_ENCAPSULATE_INIT +\& OSSL_FUNC_kem_encapsulate OSSL_FUNC_KEM_ENCAPSULATE +\& +\& OSSL_FUNC_kem_decapsulate_init OSSL_FUNC_KEM_DECAPSULATE_INIT +\& OSSL_FUNC_kem_auth_decapsulate_init OSSL_FUNC_KEM_AUTH_DECAPSULATE_INIT +\& OSSL_FUNC_kem_decapsulate OSSL_FUNC_KEM_DECAPSULATE +\& +\& OSSL_FUNC_kem_get_ctx_params OSSL_FUNC_KEM_GET_CTX_PARAMS +\& OSSL_FUNC_kem_gettable_ctx_params OSSL_FUNC_KEM_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_kem_set_ctx_params OSSL_FUNC_KEM_SET_CTX_PARAMS +\& OSSL_FUNC_kem_settable_ctx_params OSSL_FUNC_KEM_SETTABLE_CTX_PARAMS +.Ve +.PP +An asymmetric kem algorithm implementation may not implement all of these +functions. +In order to be a consistent set of functions a provider must implement +OSSL_FUNC_kem_newctx and OSSL_FUNC_kem_freectx. +It must also implement both of OSSL_FUNC_kem_encapsulate_init and +OSSL_FUNC_kem_encapsulate, or both of OSSL_FUNC_kem_decapsulate_init and +OSSL_FUNC_kem_decapsulate. +OSSL_FUNC_kem_auth_encapsulate_init is optional but if it is present then so +must OSSL_FUNC_kem_auth_decapsulate_init. +OSSL_FUNC_kem_get_ctx_params is optional but if it is present then so must +OSSL_FUNC_kem_gettable_ctx_params. +Similarly, OSSL_FUNC_kem_set_ctx_params is optional but if it is present then +OSSL_FUNC_kem_settable_ctx_params must also be present. +.PP +An asymmetric kem algorithm must also implement some mechanism for generating, +loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation. +See \fBprovider\-keymgmt\fR\|(7) for further details. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_kem_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during an asymmetric kem operation. +A pointer to this context will be passed back in a number of the other +asymmetric kem operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +.PP +\&\fBOSSL_FUNC_kem_freectx()\fR is passed a pointer to the provider side asymmetric +kem context in the \fIctx\fR parameter. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_kem_dupctx()\fR should duplicate the provider side asymmetric kem +context in the \fIctx\fR parameter and return the duplicate copy. +.SS "Asymmetric Key Encapsulation Functions" +.IX Subsection "Asymmetric Key Encapsulation Functions" +\&\fBOSSL_FUNC_kem_encapsulate_init()\fR initialises a context for an asymmetric +encapsulation given a provider side asymmetric kem context in the \fIctx\fR +parameter, a pointer to a provider key object in the \fIprovkey\fR parameter and +the \fIname\fR of the algorithm. +The \fIparams\fR, if not NULL, should be set on the context in a manner similar to +using \fBOSSL_FUNC_kem_set_ctx_params()\fR. +The key object should have been previously generated, loaded or imported into +the provider using the key management (OSSL_OP_KEYMGMT) operation (see +\&\fBprovider\-keymgmt\fR\|(7)>. +.PP +\&\fBOSSL_FUNC_kem_auth_encapsulate_init()\fR is similar to +\&\fBOSSL_FUNC_kem_encapsulate_init()\fR, but also passes an additional authentication +key \fIprovauthkey\fR which cannot be NULL. +.PP +\&\fBOSSL_FUNC_kem_encapsulate()\fR performs the actual encapsulation itself. +A previously initialised asymmetric kem context is passed in the \fIctx\fR +parameter. +Unless \fIout\fR is NULL, the data to be encapsulated is internally generated, +and returned into the buffer pointed to by the \fIsecret\fR parameter and the +encapsulated data should also be written to the location pointed to by the +\&\fIout\fR parameter. The length of the encapsulated data should be written to +\&\fI*outlen\fR and the length of the generated secret should be written to +\&\fI*secretlen\fR. +.PP +If \fIout\fR is NULL then the maximum length of the encapsulated data should be +written to \fI*outlen\fR, and the maximum length of the generated secret should be +written to \fI*secretlen\fR. +.SS "Decapsulation Functions" +.IX Subsection "Decapsulation Functions" +\&\fBOSSL_FUNC_kem_decapsulate_init()\fR initialises a context for an asymmetric +decapsulation given a provider side asymmetric kem context in the \fIctx\fR +parameter, a pointer to a provider key object in the \fIprovkey\fR parameter, and +a \fIname\fR of the algorithm. +The key object should have been previously generated, loaded or imported into +the provider using the key management (OSSL_OP_KEYMGMT) operation (see +\&\fBprovider\-keymgmt\fR\|(7)>. +.PP +\&\fBOSSL_FUNC_kem_auth_decapsulate_init()\fR is similar to +\&\fBOSSL_FUNC_kem_decapsulate_init()\fR, but also passes an additional authentication +key \fIprovauthkey\fR which cannot be NULL. +.PP +\&\fBOSSL_FUNC_kem_decapsulate()\fR performs the actual decapsulation itself. +A previously initialised asymmetric kem context is passed in the \fIctx\fR +parameter. +The data to be decapsulated is pointed to by the \fIin\fR parameter which is \fIinlen\fR +bytes long. +Unless \fIout\fR is NULL, the decapsulated data should be written to the location +pointed to by the \fIout\fR parameter. +The length of the decapsulated data should be written to \fI*outlen\fR. +If \fIout\fR is NULL then the maximum length of the decapsulated data should be +written to \fI*outlen\fR. +.SS "Asymmetric Key Encapsulation Parameters" +.IX Subsection "Asymmetric Key Encapsulation Parameters" +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by +the \fBOSSL_FUNC_kem_get_ctx_params()\fR and \fBOSSL_FUNC_kem_set_ctx_params()\fR +functions. +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_KEM_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_KEM_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling either \fBOSSL_FUNC_kem_encapsulate()\fR or +\&\fBOSSL_FUNC_kem_decapsulate()\fR. It may return 0 if the "key\-check" is set to 0. +.IP """key\-check"" (\fBOSSL_KEM_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_KEM_PARAM_FIPS_KEY_CHECK) " +If required this parameter should be set using \fBOSSL_FUNC_kem_encapsulate_init()\fR +or \fBOSSL_FUNC_kem_decapsulate_init()\fR. +The default value of 1 causes an error during the init if the key is not FIPS +approved (e.g. The key has a security strength of less than 112 bits). Setting +this to 0 will ignore the error and set the approved "fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SS "Asymmetric Key Encapsulation Parameter Functions" +.IX Subsection "Asymmetric Key Encapsulation Parameter Functions" +\&\fBOSSL_FUNC_kem_get_ctx_params()\fR gets asymmetric KEM parameters associated +with the given provider side asymmetric kem context \fIctx\fR and stores them in +\&\fIparams\fR. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_kem_set_ctx_params()\fR sets the asymmetric KEM parameters associated +with the given provider side asymmetric kem context \fIctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing NULL for \fIparams\fR should return true. +.PP +No parameters are currently recognised by built\-in asymmetric kem algorithms. +.PP +\&\fBOSSL_FUNC_kem_gettable_ctx_params()\fR and \fBOSSL_FUNC_kem_settable_ctx_params()\fR +get a constant \fBOSSL_PARAM\fR\|(3) array that describes the gettable and settable +parameters, i.e. parameters that can be used with \fBOSSL_FUNC_kem_get_ctx_params()\fR +and \fBOSSL_FUNC_kem_set_ctx_params()\fR respectively. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_kem_newctx()\fR and \fBOSSL_FUNC_kem_dupctx()\fR should return the newly +created provider side asymmetric kem context, or NULL on failure. +.PP +All other functions should return 1 for success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The provider KEM interface was introduced in OpenSSL 3.0. +.PP +\&\fBOSSL_FUNC_kem_auth_encapsulate_init()\fR and \fBOSSL_FUNC_kem_auth_decapsulate_init()\fR +were added in OpenSSL 3.2. +.PP +The Asymmetric Key Encapsulation Parameters "fips\-indicator" and "key\-check" +were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-keyexch.7 b/static/netbsd/man7/provider-keyexch.7 new file mode 100644 index 00000000..d2bc4de1 --- /dev/null +++ b/static/netbsd/man7/provider-keyexch.7 @@ -0,0 +1,310 @@ +.\" $NetBSD: provider-keyexch.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-KEYEXCH 7" +.TH PROVIDER-KEYEXCH 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-keyexch \- The keyexch library <\-> provider functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_keyexch_newctx(void *provctx); +\& void OSSL_FUNC_keyexch_freectx(void *ctx); +\& void *OSSL_FUNC_keyexch_dupctx(void *ctx); +\& +\& /* Shared secret derivation */ +\& int OSSL_FUNC_keyexch_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_keyexch_set_peer(void *ctx, void *provkey); +\& int OSSL_FUNC_keyexch_derive(void *ctx, unsigned char *secret, size_t *secretlen, +\& size_t outlen); +\& +\& /* Key Exchange parameters */ +\& int OSSL_FUNC_keyexch_set_ctx_params(void *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_keyexch_settable_ctx_params(void *ctx, +\& void *provctx); +\& int OSSL_FUNC_keyexch_get_ctx_params(void *ctx, OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_keyexch_gettable_ctx_params(void *ctx, +\& void *provctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The key exchange (OSSL_OP_KEYEXCH) operation enables providers to implement key +exchange algorithms and make them available to applications via +\&\fBEVP_PKEY_derive\fR\|(3) and +other related functions). +.PP +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via +\&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider\*(Aqs +\&\fBprovider_query_operation()\fR function +(see "Provider Functions" in \fBprovider\-base\fR\|(7)). +.PP +All these "functions" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the "function" \fBOSSL_FUNC_keyexch_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_keyexch_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_keyexch_newctx_fn +\& OSSL_FUNC_keyexch_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_keyexch_newctx OSSL_FUNC_KEYEXCH_NEWCTX +\& OSSL_FUNC_keyexch_freectx OSSL_FUNC_KEYEXCH_FREECTX +\& OSSL_FUNC_keyexch_dupctx OSSL_FUNC_KEYEXCH_DUPCTX +\& +\& OSSL_FUNC_keyexch_init OSSL_FUNC_KEYEXCH_INIT +\& OSSL_FUNC_keyexch_set_peer OSSL_FUNC_KEYEXCH_SET_PEER +\& OSSL_FUNC_keyexch_derive OSSL_FUNC_KEYEXCH_DERIVE +\& +\& OSSL_FUNC_keyexch_set_ctx_params OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS +\& OSSL_FUNC_keyexch_settable_ctx_params OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS +\& OSSL_FUNC_keyexch_get_ctx_params OSSL_FUNC_KEYEXCH_GET_CTX_PARAMS +\& OSSL_FUNC_keyexch_gettable_ctx_params OSSL_FUNC_KEYEXCH_GETTABLE_CTX_PARAMS +.Ve +.PP +A key exchange algorithm implementation may not implement all of these functions. +In order to be a consistent set of functions a provider must implement +OSSL_FUNC_keyexch_newctx, OSSL_FUNC_keyexch_freectx, OSSL_FUNC_keyexch_init and OSSL_FUNC_keyexch_derive. +All other functions are optional. +.PP +A key exchange algorithm must also implement some mechanism for generating, +loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation. +See \fBprovider\-keymgmt\fR\|(7) for further details. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_keyexch_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during a key exchange operation. +A pointer to this context will be passed back in a number of the other key +exchange operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +.PP +\&\fBOSSL_FUNC_keyexch_freectx()\fR is passed a pointer to the provider side key exchange +context in the \fIctx\fR parameter. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_keyexch_dupctx()\fR should duplicate the provider side key exchange context in +the \fIctx\fR parameter and return the duplicate copy. +.SS "Shared Secret Derivation Functions" +.IX Subsection "Shared Secret Derivation Functions" +\&\fBOSSL_FUNC_keyexch_init()\fR initialises a key exchange operation given a provider side key +exchange context in the \fIctx\fR parameter, and a pointer to a provider key object +in the \fIprovkey\fR parameter. +The \fIparams\fR, if not NULL, should be set on the context in a manner similar to +using \fBOSSL_FUNC_keyexch_set_params()\fR. +The key object should have been previously +generated, loaded or imported into the provider using the key management +(OSSL_OP_KEYMGMT) operation (see \fBprovider\-keymgmt\fR\|(7)>. +.PP +\&\fBOSSL_FUNC_keyexch_set_peer()\fR is called to supply the peer\*(Aqs public key (in the +\&\fIprovkey\fR parameter) to be used when deriving the shared secret. +It is also passed a previously initialised key exchange context in the \fIctx\fR +parameter. +The key object should have been previously generated, loaded or imported into +the provider using the key management (OSSL_OP_KEYMGMT) operation (see +\&\fBprovider\-keymgmt\fR\|(7)>. +.PP +\&\fBOSSL_FUNC_keyexch_derive()\fR performs the actual key exchange itself by deriving a shared +secret. +A previously initialised key exchange context is passed in the \fIctx\fR +parameter. +The derived secret should be written to the location \fIsecret\fR which should not +exceed \fIoutlen\fR bytes. +The length of the shared secret should be written to \fI*secretlen\fR. +If \fIsecret\fR is NULL then the maximum length of the shared secret should be +written to \fI*secretlen\fR. +.SS "Key Exchange Parameters Functions" +.IX Subsection "Key Exchange Parameters Functions" +\&\fBOSSL_FUNC_keyexch_set_ctx_params()\fR sets key exchange parameters associated with the +given provider side key exchange context \fIctx\fR to \fIparams\fR, +see "Common Key Exchange parameters". +Any parameter settings are additional to any that were previously set. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_keyexch_get_ctx_params()\fR gets key exchange parameters associated with the +given provider side key exchange context \fIctx\fR into \fIparams\fR, +see "Common Key Exchange parameters". +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_keyexch_settable_ctx_params()\fR yields a constant \fBOSSL_PARAM\fR\|(3) array that +describes the settable parameters, i.e. parameters that can be used with +\&\fBOP_signature_set_ctx_params()\fR. +If \fBOSSL_FUNC_keyexch_settable_ctx_params()\fR is present, \fBOSSL_FUNC_keyexch_set_ctx_params()\fR must +also be present, and vice versa. +Similarly, \fBOSSL_FUNC_keyexch_gettable_ctx_params()\fR yields a constant \fBOSSL_PARAM\fR\|(3) +array that describes the gettable parameters, i.e. parameters that can be +handled by \fBOP_signature_get_ctx_params()\fR. +If \fBOSSL_FUNC_keyexch_gettable_ctx_params()\fR is present, \fBOSSL_FUNC_keyexch_get_ctx_params()\fR must +also be present, and vice versa. +.PP +Notice that not all settable parameters are also gettable, and vice versa. +.SS "Common Key Exchange parameters" +.IX Subsection "Common Key Exchange parameters" +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by +the \fBOSSL_FUNC_keyexch_set_ctx_params()\fR and \fBOSSL_FUNC_keyexch_get_ctx_params()\fR functions. +.PP +Common parameters currently recognised by built\-in key exchange algorithms are +as follows. +.IP """kdf\-type"" (\fBOSSL_EXCHANGE_PARAM_KDF_TYPE\fR) " 4 +.IX Item """kdf-type"" (OSSL_EXCHANGE_PARAM_KDF_TYPE) " +Sets or gets the Key Derivation Function type to apply within the associated key +exchange ctx. +.IP """kdf\-digest"" (\fBOSSL_EXCHANGE_PARAM_KDF_DIGEST\fR) " 4 +.IX Item """kdf-digest"" (OSSL_EXCHANGE_PARAM_KDF_DIGEST) " +Sets or gets the Digest algorithm to be used as part of the Key Derivation Function +associated with the given key exchange ctx. +.IP """kdf\-digest\-props"" (\fBOSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS\fR) " 4 +.IX Item """kdf-digest-props"" (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) " +Sets properties to be used upon look up of the implementation for the selected +Digest algorithm for the Key Derivation Function associated with the given key +exchange ctx. +.IP """kdf\-outlen"" (\fBOSSL_EXCHANGE_PARAM_KDF_OUTLEN\fR) " 4 +.IX Item """kdf-outlen"" (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) " +Sets or gets the desired size for the output of the chosen Key Derivation Function +associated with the given key exchange ctx. +The length of the "kdf\-outlen" parameter should not exceed that of a \fBsize_t\fR. +.IP """kdf\-ukm"" (\fBOSSL_EXCHANGE_PARAM_KDF_UKM\fR) " 4 +.IX Item """kdf-ukm"" (OSSL_EXCHANGE_PARAM_KDF_UKM) " +Sets the User Key Material to be used as part of the selected Key Derivation +Function associated with the given key exchange ctx. +.IP """kdf\-ukm"" (\fBOSSL_EXCHANGE_PARAM_KDF_UKM\fR) " 4 +.IX Item """kdf-ukm"" (OSSL_EXCHANGE_PARAM_KDF_UKM) " +Gets a pointer to the User Key Material to be used as part of the selected +Key Derivation Function associated with the given key exchange ctx. Providers +usually do not need to support this gettable parameter as its sole purpose +is to support functionality of the deprecated \fBEVP_PKEY_CTX_get0_ecdh_kdf_ukm()\fR +and \fBEVP_PKEY_CTX_get0_dh_kdf_ukm()\fR functions. +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling \fBOSSL_FUNC_keyexch_derive()\fR. It may +return 0 if either the "digest\-check" or the "key\-check" are set to 0. +.IP """key\-check"" (\fBOSSL_EXCHANGE_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_EXCHANGE_PARAM_FIPS_KEY_CHECK) " +If required this parameter should be set using \fBOSSL_FUNC_keyexch_init()\fR. +The default value of 1 causes an error during the init if the key is not FIPS +approved (e.g. The key has a security strength of less than 112 bits). Setting +this to 0 will ignore the error and set the approved "fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.IP """digest\-check"" (\fBOSSL_EXCHANGE_PARAM_FIPS_DIGEST_CHECK\fR) " 4 +.IX Item """digest-check"" (OSSL_EXCHANGE_PARAM_FIPS_DIGEST_CHECK) " +If required this parameter should be set before any optional digest is set. +The default value of 1 causes an error when the digest is set if the digest is +not FIPS approved. Setting this to 0 will ignore the error and set the +approved "fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_keyexch_newctx()\fR and \fBOSSL_FUNC_keyexch_dupctx()\fR should return the newly created +provider side key exchange context, or NULL on failure. +.PP +\&\fBOSSL_FUNC_keyexch_init()\fR, \fBOSSL_FUNC_keyexch_set_peer()\fR, \fBOSSL_FUNC_keyexch_derive()\fR, +\&\fBOSSL_FUNC_keyexch_set_params()\fR, and \fBOSSL_FUNC_keyexch_get_params()\fR should return 1 for success +or 0 on error. +.PP +\&\fBOSSL_FUNC_keyexch_settable_ctx_params()\fR and \fBOSSL_FUNC_keyexch_gettable_ctx_params()\fR should +always return a constant \fBOSSL_PARAM\fR\|(3) array. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The provider KEYEXCH interface was introduced in OpenSSL 3.0. +.PP +The Key Exchange Parameters "fips\-indicator", "key\-check" and "digest\-check" +were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-keymgmt.7 b/static/netbsd/man7/provider-keymgmt.7 new file mode 100644 index 00000000..b56e13fe --- /dev/null +++ b/static/netbsd/man7/provider-keymgmt.7 @@ -0,0 +1,557 @@ +.\" $NetBSD: provider-keymgmt.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-KEYMGMT 7" +.TH PROVIDER-KEYMGMT 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-keymgmt \- The KEYMGMT library <\-> provider functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Key object (keydata) creation and destruction */ +\& void *OSSL_FUNC_keymgmt_new(void *provctx); +\& void OSSL_FUNC_keymgmt_free(void *keydata); +\& +\& /* Generation, a more complex constructor */ +\& void *OSSL_FUNC_keymgmt_gen_init(void *provctx, int selection, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_keymgmt_gen_set_template(void *genctx, void *template); +\& int OSSL_FUNC_keymgmt_gen_get_params(void *genctx, OSSL_PARAM params[]); +\& int OSSL_FUNC_keymgmt_gen_set_params(void *genctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_gen_gettable_params(void *genctx, +\& void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_gen_settable_params(void *genctx, +\& void *provctx); +\& void *OSSL_FUNC_keymgmt_gen(void *genctx, OSSL_CALLBACK *cb, void *cbarg); +\& void OSSL_FUNC_keymgmt_gen_cleanup(void *genctx); +\& +\& /* Key loading by object reference, also a constructor */ +\& void *OSSL_FUNC_keymgmt_load(const void *reference, size_t reference_sz); +\& +\& /* Key object information */ +\& int OSSL_FUNC_keymgmt_get_params(void *keydata, OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_gettable_params(void *provctx); +\& int OSSL_FUNC_keymgmt_set_params(void *keydata, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_settable_params(void *provctx); +\& +\& /* Key object content checks */ +\& int OSSL_FUNC_keymgmt_has(const void *keydata, int selection); +\& int OSSL_FUNC_keymgmt_match(const void *keydata1, const void *keydata2, +\& int selection); +\& +\& /* Discovery of supported operations */ +\& const char *OSSL_FUNC_keymgmt_query_operation_name(int operation_id); +\& +\& /* Key object import and export functions */ +\& int OSSL_FUNC_keymgmt_import(void *keydata, int selection, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types(int selection); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types_ex(void *provctx, int selection); +\& int OSSL_FUNC_keymgmt_export(void *keydata, int selection, +\& OSSL_CALLBACK *param_cb, void *cbarg); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types(int selection); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types_ex(void *provctx, int selection); +\& +\& /* Key object duplication, a constructor */ +\& void *OSSL_FUNC_keymgmt_dup(const void *keydata_from, int selection); +\& +\& /* Key object validation */ +\& int OSSL_FUNC_keymgmt_validate(const void *keydata, int selection, int checktype); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The KEYMGMT operation doesn\*(Aqt have much public visibility in OpenSSL +libraries, it\*(Aqs rather an internal operation that\*(Aqs designed to work +in tandem with operations that use private/public key pairs. +.PP +Because the KEYMGMT operation shares knowledge with the operations it +works with in tandem, they must belong to the same provider. +The OpenSSL libraries will ensure that they do. +.PP +The primary responsibility of the KEYMGMT operation is to hold the +provider side key data for the OpenSSL library EVP_PKEY structure. +.PP +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via +\&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider\*(Aqs +\&\fBprovider_query_operation()\fR function +(see "Provider Functions" in \fBprovider\-base\fR\|(7)). +.PP +All these "functions" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from a \fBOSSL_DISPATCH\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the "function" \fBOSSL_FUNC_keymgmt_new()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_keymgmt_new_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_keymgmt_new_fn +\& OSSL_FUNC_keymgmt_new(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 2 +\& OSSL_FUNC_keymgmt_new OSSL_FUNC_KEYMGMT_NEW +\& OSSL_FUNC_keymgmt_free OSSL_FUNC_KEYMGMT_FREE +\& +\& OSSL_FUNC_keymgmt_gen_init OSSL_FUNC_KEYMGMT_GEN_INIT +\& OSSL_FUNC_keymgmt_gen_set_template OSSL_FUNC_KEYMGMT_GEN_SET_TEMPLATE +\& OSSL_FUNC_keymgmt_gen_get_params OSSL_FUNC_KEYMGMT_GEN_GET_PARAMS +\& OSSL_FUNC_keymgmt_gen_gettable_params OSSL_FUNC_KEYMGMT_GEN_GETTABLE_PARAMS +\& OSSL_FUNC_keymgmt_gen_set_params OSSL_FUNC_KEYMGMT_GEN_SET_PARAMS +\& OSSL_FUNC_keymgmt_gen_settable_params OSSL_FUNC_KEYMGMT_GEN_SETTABLE_PARAMS +\& OSSL_FUNC_keymgmt_gen OSSL_FUNC_KEYMGMT_GEN +\& OSSL_FUNC_keymgmt_gen_cleanup OSSL_FUNC_KEYMGMT_GEN_CLEANUP +\& +\& OSSL_FUNC_keymgmt_load OSSL_FUNC_KEYMGMT_LOAD +\& +\& OSSL_FUNC_keymgmt_get_params OSSL_FUNC_KEYMGMT_GET_PARAMS +\& OSSL_FUNC_keymgmt_gettable_params OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS +\& OSSL_FUNC_keymgmt_set_params OSSL_FUNC_KEYMGMT_SET_PARAMS +\& OSSL_FUNC_keymgmt_settable_params OSSL_FUNC_KEYMGMT_SETTABLE_PARAMS +\& +\& OSSL_FUNC_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME +\& +\& OSSL_FUNC_keymgmt_has OSSL_FUNC_KEYMGMT_HAS +\& OSSL_FUNC_keymgmt_validate OSSL_FUNC_KEYMGMT_VALIDATE +\& OSSL_FUNC_keymgmt_match OSSL_FUNC_KEYMGMT_MATCH +\& +\& OSSL_FUNC_keymgmt_import OSSL_FUNC_KEYMGMT_IMPORT +\& OSSL_FUNC_keymgmt_import_types OSSL_FUNC_KEYMGMT_IMPORT_TYPES +\& OSSL_FUNC_keymgmt_import_types_ex OSSL_FUNC_KEYMGMT_IMPORT_TYPES_EX +\& OSSL_FUNC_keymgmt_export OSSL_FUNC_KEYMGMT_EXPORT +\& OSSL_FUNC_keymgmt_export_types OSSL_FUNC_KEYMGMT_EXPORT_TYPES +\& OSSL_FUNC_keymgmt_export_types_ex OSSL_FUNC_KEYMGMT_EXPORT_TYPES_EX +\& +\& OSSL_FUNC_keymgmt_dup OSSL_FUNC_KEYMGMT_DUP +.Ve +.SS "Key Objects" +.IX Subsection "Key Objects" +A key object is a collection of data for an asymmetric key, and is +represented as \fIkeydata\fR in this manual. +.PP +The exact contents of a key object are defined by the provider, and it +is assumed that different operations in one and the same provider use +the exact same structure to represent this collection of data, so that +for example, a key object that has been created using the KEYMGMT +interface that we document here can be passed as is to other provider +operations, such as \fBOP_signature_sign_init()\fR (see +\&\fBprovider\-signature\fR\|(7)). +.PP +With some of the KEYMGMT functions, it\*(Aqs possible to select a specific +subset of data to handle, governed by the bits in a \fIselection\fR +indicator. The bits are: +.IP \fBOSSL_KEYMGMT_SELECT_PRIVATE_KEY\fR 4 +.IX Item "OSSL_KEYMGMT_SELECT_PRIVATE_KEY" +Indicating that the private key data in a key object should be +considered. +.IP \fBOSSL_KEYMGMT_SELECT_PUBLIC_KEY\fR 4 +.IX Item "OSSL_KEYMGMT_SELECT_PUBLIC_KEY" +Indicating that the public key data in a key object should be +considered. +.IP \fBOSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS\fR 4 +.IX Item "OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS" +Indicating that the domain parameters in a key object should be +considered. +.IP \fBOSSL_KEYMGMT_SELECT_OTHER_PARAMETERS\fR 4 +.IX Item "OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS" +Indicating that other parameters in a key object should be +considered. +.Sp +Other parameters are key parameters that don\*(Aqt fit any other +classification. In other words, this particular selector bit works as +a last resort bit bucket selector. +.PP +Some selector bits have also been combined for easier use: +.IP \fBOSSL_KEYMGMT_SELECT_ALL_PARAMETERS\fR 4 +.IX Item "OSSL_KEYMGMT_SELECT_ALL_PARAMETERS" +Indicating that all key object parameters should be considered, +regardless of their more granular classification. +.Sp +This is a combination of \fBOSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS\fR and +\&\fBOSSL_KEYMGMT_SELECT_OTHER_PARAMETERS\fR. +.IP \fBOSSL_KEYMGMT_SELECT_KEYPAIR\fR 4 +.IX Item "OSSL_KEYMGMT_SELECT_KEYPAIR" +Indicating that both the whole key pair in a key object should be +considered, i.e. the combination of public and private key. +.Sp +This is a combination of \fBOSSL_KEYMGMT_SELECT_PRIVATE_KEY\fR and +\&\fBOSSL_KEYMGMT_SELECT_PUBLIC_KEY\fR. +.IP \fBOSSL_KEYMGMT_SELECT_ALL\fR 4 +.IX Item "OSSL_KEYMGMT_SELECT_ALL" +Indicating that everything in a key object should be considered. +.PP +The exact interpretation of those bits or how they combine is left to +each function where you can specify a selector. +.PP +It\*(Aqs left to the provider implementation to decide what is reasonable +to do with regards to received selector bits and how to do it. +Among others, an implementation of \fBOSSL_FUNC_keymgmt_match()\fR might opt +to not compare the private half if it has compared the public half, +since a match of one half implies a match of the other half. +.SS "Constructing and Destructing Functions" +.IX Subsection "Constructing and Destructing Functions" +\&\fBOSSL_FUNC_keymgmt_new()\fR should create a provider side key object. The +provider context \fIprovctx\fR is passed and may be incorporated in the +key object, but that is not mandatory. +.PP +\&\fBOSSL_FUNC_keymgmt_free()\fR should free the passed \fIkeydata\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_gen_init()\fR, \fBOSSL_FUNC_keymgmt_gen_set_template()\fR, +\&\fBOSSL_FUNC_keymgmt_gen_get_params()\fR, \fBOSSL_FUNC_keymgmt_gen_gettable_params()\fR, +\&\fBOSSL_FUNC_keymgmt_gen_set_params()\fR, \fBOSSL_FUNC_keymgmt_gen_settable_params()\fR, +\&\fBOSSL_FUNC_keymgmt_gen()\fR and \fBOSSL_FUNC_keymgmt_gen_cleanup()\fR work together as a +more elaborate context based key object constructor. +.PP +\&\fBOSSL_FUNC_keymgmt_gen_init()\fR should create the key object generation context +and initialize it with \fIselections\fR, which will determine what kind +of contents the key object to be generated should get. +The \fIparams\fR, if not NULL, should be set on the context in a manner similar to +using \fBOSSL_FUNC_keymgmt_set_params()\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_gen_set_template()\fR should add \fItemplate\fR to the context +\&\fIgenctx\fR. The \fItemplate\fR is assumed to be a key object constructed +with the same KEYMGMT, and from which content that the implementation +chooses can be used as a template for the key object to be generated. +Typically, the generation of a DSA or DH key would get the domain +parameters from this \fItemplate\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_gen_get_params()\fR should retrieve parameters into +\&\fIparams\fR in the key object generation context \fIgenctx\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_gen_gettable_params()\fR should return a constant array of +descriptor \fBOSSL_PARAM\fR\|(3), for parameters that +\&\fBOSSL_FUNC_keymgmt_gen_get_params()\fR can handle. +.PP +\&\fBOSSL_FUNC_keymgmt_gen_set_params()\fR should set additional parameters from +\&\fIparams\fR in the key object generation context \fIgenctx\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_gen_settable_params()\fR should return a constant array of +descriptor \fBOSSL_PARAM\fR\|(3), for parameters that \fBOSSL_FUNC_keymgmt_gen_set_params()\fR +can handle. +.PP +\&\fBOSSL_FUNC_keymgmt_gen()\fR should perform the key object generation itself, and +return the result. The callback \fIcb\fR should be called at regular +intervals with indications on how the key object generation +progresses. +.PP +\&\fBOSSL_FUNC_keymgmt_gen_cleanup()\fR should clean up and free the key object +generation context \fIgenctx\fR +.PP +\&\fBOSSL_FUNC_keymgmt_load()\fR creates a provider side key object based on a +\&\fIreference\fR object with a size of \fIreference_sz\fR bytes, that only the +provider knows how to interpret, but that may come from other operations. +Outside the provider, this reference is simply an array of bytes. +.PP +At least one of \fBOSSL_FUNC_keymgmt_new()\fR, \fBOSSL_FUNC_keymgmt_gen()\fR and +\&\fBOSSL_FUNC_keymgmt_load()\fR are mandatory, as well as \fBOSSL_FUNC_keymgmt_free()\fR and +\&\fBOSSL_FUNC_keymgmt_has()\fR. Additionally, if \fBOSSL_FUNC_keymgmt_gen()\fR is present, +\&\fBOSSL_FUNC_keymgmt_gen_init()\fR and \fBOSSL_FUNC_keymgmt_gen_cleanup()\fR must be +present as well. +.SS "Key Object Information Functions" +.IX Subsection "Key Object Information Functions" +\&\fBOSSL_FUNC_keymgmt_get_params()\fR should extract information data associated +with the given \fIkeydata\fR, see "Common Information Parameters". +.PP +\&\fBOSSL_FUNC_keymgmt_gettable_params()\fR should return a constant array of +descriptor \fBOSSL_PARAM\fR\|(3), for parameters that \fBOSSL_FUNC_keymgmt_get_params()\fR +can handle. +.PP +If \fBOSSL_FUNC_keymgmt_gettable_params()\fR is present, \fBOSSL_FUNC_keymgmt_get_params()\fR +must also be present, and vice versa. +.PP +\&\fBOSSL_FUNC_keymgmt_set_params()\fR should update information data associated +with the given \fIkeydata\fR, see "Common Information Parameters". +.PP +\&\fBOSSL_FUNC_keymgmt_settable_params()\fR should return a constant array of +descriptor \fBOSSL_PARAM\fR\|(3), for parameters that \fBOSSL_FUNC_keymgmt_set_params()\fR +can handle. +.PP +If \fBOSSL_FUNC_keymgmt_settable_params()\fR is present, \fBOSSL_FUNC_keymgmt_set_params()\fR +must also be present, and vice versa. +.SS "Key Object Checking Functions" +.IX Subsection "Key Object Checking Functions" +\&\fBOSSL_FUNC_keymgmt_query_operation_name()\fR should return the name of the +supported algorithm for the operation \fIoperation_id\fR. This is +similar to \fBprovider_query_operation()\fR (see \fBprovider\-base\fR\|(7)), +but only works as an advisory. If this function is not present, or +returns NULL, the caller is free to assume that there\*(Aqs an algorithm +from the same provider, of the same name as the one used to fetch the +keymgmt and try to use that. +.PP +\&\fBOSSL_FUNC_keymgmt_has()\fR should check whether the given \fIkeydata\fR contains the subsets +of data indicated by the \fIselector\fR. A combination of several +selector bits must consider all those subsets, not just one. An +implementation is, however, free to consider an empty subset of data +to still be a valid subset. For algorithms where some selection is +not meaningful such as \fBOSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS\fR for +RSA keys the function should just return 1 as the selected subset +is not really missing in the key. +.PP +\&\fBOSSL_FUNC_keymgmt_validate()\fR should check if the \fIkeydata\fR contains valid +data subsets indicated by \fIselection\fR. Some combined selections of +data subsets may cause validation of the combined data. +For example, the combination of \fBOSSL_KEYMGMT_SELECT_PRIVATE_KEY\fR and +\&\fBOSSL_KEYMGMT_SELECT_PUBLIC_KEY\fR (or \fBOSSL_KEYMGMT_SELECT_KEYPAIR\fR +for short) is expected to check that the pairwise consistency of +\&\fIkeydata\fR is valid. The \fIchecktype\fR parameter controls what type of check is +performed on the subset of data. Two types of check are defined: +\&\fBOSSL_KEYMGMT_VALIDATE_FULL_CHECK\fR and \fBOSSL_KEYMGMT_VALIDATE_QUICK_CHECK\fR. +The interpretation of how much checking is performed in a full check versus a +quick check is key type specific. Some providers may have no distinction +between a full check and a quick check. For algorithms where some selection is +not meaningful such as \fBOSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS\fR for +RSA keys the function should just return 1 as there is nothing to validate for +that selection. +.PP +\&\fBOSSL_FUNC_keymgmt_match()\fR should check if the data subset indicated by +\&\fIselection\fR in \fIkeydata1\fR and \fIkeydata2\fR match. It is assumed that +the caller has ensured that \fIkeydata1\fR and \fIkeydata2\fR are both owned +by the implementation of this function. +.SS "Key Object Import, Export and Duplication Functions" +.IX Subsection "Key Object Import, Export and Duplication Functions" +\&\fBOSSL_FUNC_keymgmt_import()\fR should import data indicated by \fIselection\fR into +\&\fIkeydata\fR with values taken from the \fBOSSL_PARAM\fR\|(3) array \fIparams\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_export()\fR should extract values indicated by \fIselection\fR +from \fIkeydata\fR, create an \fBOSSL_PARAM\fR\|(3) array with them and call +\&\fIparam_cb\fR with that array as well as the given \fIcbarg\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_import_types()\fR and \fBOSSL_FUNC_keymgmt_import_types_ex()\fR +should return a constant array of descriptor +\&\fBOSSL_PARAM\fR\|(3) for data indicated by \fIselection\fR, for parameters that +\&\fBOSSL_FUNC_keymgmt_import()\fR can handle. +Either \fBOSSL_FUNC_keymgmt_import_types()\fR or \fBOSSL_FUNC_keymgmt_import_types_ex()\fR, +must be implemented, if \fBOSSL_FUNC_keymgmt_import_types_ex()\fR is implemented, then +it is preferred over \fBOSSL_FUNC_keymgmt_import_types()\fR. +Providers that are supposed to be backward compatible with OpenSSL 3.0 or 3.1 +must continue to implement \fBOSSL_FUNC_keymgmt_import_types()\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_export_types()\fR and \fBOSSL_FUNC_keymgmt_export_types_ex()\fR +should return a constant array of descriptor +\&\fBOSSL_PARAM\fR\|(3) for data indicated by \fIselection\fR, that the +\&\fBOSSL_FUNC_keymgmt_export()\fR callback can expect to receive. +Either \fBOSSL_FUNC_keymgmt_export_types()\fR or \fBOSSL_FUNC_keymgmt_export_types_ex()\fR, +must be implemented, if \fBOSSL_FUNC_keymgmt_export_types_ex()\fR is implemented, then +it is preferred over \fBOSSL_FUNC_keymgmt_export_types()\fR. +Providers that are supposed to be backward compatible with OpenSSL 3.0 or 3.1 +must continue to implement \fBOSSL_FUNC_keymgmt_export_types()\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_dup()\fR should duplicate data subsets indicated by +\&\fIselection\fR or the whole key data \fIkeydata_from\fR and create a new +provider side key object with the data. +.SS "Common Information Parameters" +.IX Subsection "Common Information Parameters" +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure. +.PP +Common information parameters currently recognised by all built\-in +keymgmt algorithms are as follows: +.IP """bits"" (\fBOSSL_PKEY_PARAM_BITS\fR) " 4 +.IX Item """bits"" (OSSL_PKEY_PARAM_BITS) " +The value should be the cryptographic length of the cryptosystem to +which the key belongs, in bits. The definition of cryptographic +length is specific to the key cryptosystem. +.IP """max\-size"" (\fBOSSL_PKEY_PARAM_MAX_SIZE\fR) " 4 +.IX Item """max-size"" (OSSL_PKEY_PARAM_MAX_SIZE) " +The value should be the maximum size that a caller should allocate to +safely store a signature (called \fIsig\fR in \fBprovider\-signature\fR\|(7)), +the result of asymmetric encryption / decryption (\fIout\fR in +\&\fBprovider\-asym_cipher\fR\|(7), a derived secret (\fIsecret\fR in +\&\fBprovider\-keyexch\fR\|(7), and similar data). +.Sp +Providers need to implement this parameter +in order to properly support various use cases such as CMS signing. +.Sp +Because an EVP_KEYMGMT method is always tightly bound to another method +(signature, asymmetric cipher, key exchange, ...) and must be of the +same provider, this number only needs to be synchronised with the +dimensions handled in the rest of the same provider. +.IP """security\-bits"" (\fBOSSL_PKEY_PARAM_SECURITY_BITS\fR) " 4 +.IX Item """security-bits"" (OSSL_PKEY_PARAM_SECURITY_BITS) " +The value should be the number of security bits of the given key. +Bits of security is defined in SP800\-57. +.IP """mandatory\-digest"" (\fBOSSL_PKEY_PARAM_MANDATORY_DIGEST\fR) " 4 +.IX Item """mandatory-digest"" (OSSL_PKEY_PARAM_MANDATORY_DIGEST) " +If there is a mandatory digest for performing a signature operation with +keys from this keymgmt, this parameter should get its name as value. +.Sp +When \fBEVP_PKEY_get_default_digest_name()\fR queries this parameter and it\*(Aqs +filled in by the implementation, its return value will be 2. +.Sp +If the keymgmt implementation fills in the value \f(CW""\fR or \f(CW"UNDEF"\fR, +\&\fBEVP_PKEY_get_default_digest_name\fR\|(3) will place the string \f(CW"UNDEF"\fR into +its argument \fImdname\fR. This signifies that no digest should be specified +with the corresponding signature operation. +.IP """default\-digest"" (\fBOSSL_PKEY_PARAM_DEFAULT_DIGEST\fR) " 4 +.IX Item """default-digest"" (OSSL_PKEY_PARAM_DEFAULT_DIGEST) " +If there is a default digest for performing a signature operation with +keys from this keymgmt, this parameter should get its name as value. +.Sp +When \fBEVP_PKEY_get_default_digest_name\fR\|(3) queries this parameter and it\*(Aqs +filled in by the implementation, its return value will be 1. Note that if +\&\fBOSSL_PKEY_PARAM_MANDATORY_DIGEST\fR is responded to as well, +\&\fBEVP_PKEY_get_default_digest_name\fR\|(3) ignores the response to this +parameter. +.Sp +If the keymgmt implementation fills in the value \f(CW""\fR or \f(CW"UNDEF"\fR, +\&\fBEVP_PKEY_get_default_digest_name\fR\|(3) will place the string \f(CW"UNDEF"\fR into +its argument \fImdname\fR. This signifies that no digest has to be specified +with the corresponding signature operation, but may be specified as an +option. +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling \fBOSSL_FUNC_keymgmt_gen()\fR function. It may +return 0 if either the "key\-check", or "sign\-check" are set to 0. +.IP """key\-check"" (\fBOSSL_PKEY_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_PKEY_PARAM_FIPS_KEY_CHECK) " +If required this parameter should be set using \fBOSSL_FUNC_keymgmt_gen_set_params()\fR +or \fBOSSL_FUNC_keymgmt_gen_init()\fR. +The default value of 1 causes an error during the init if the key is not FIPS +approved (e.g. The key has a security strength of less than 112 bits). Setting +this to 0 will ignore the error and set the approved "fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.IP """sign\-check"" (\fBOSSL_PKEY_PARAM_FIPS_SIGN_CHECK\fR) " 4 +.IX Item """sign-check"" (OSSL_PKEY_PARAM_FIPS_SIGN_CHECK) " +If required this parameter should be set before the \fBOSSL_FUNC_keymgmt_gen()\fR +function. This value is not supported by all keygen algorithms. +The default value of 1 will cause an error if the generated key is not +allowed to be used for signing. +Setting this to 0 will ignore the error and set the approved "fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_keymgmt_new()\fR and \fBOSSL_FUNC_keymgmt_dup()\fR should return a valid +reference to the newly created provider side key object, or NULL on failure. +.PP +\&\fBOSSL_FUNC_keymgmt_import()\fR, \fBOSSL_FUNC_keymgmt_export()\fR, \fBOSSL_FUNC_keymgmt_get_params()\fR and +\&\fBOSSL_FUNC_keymgmt_set_params()\fR should return 1 for success or 0 on error. +.PP +\&\fBOSSL_FUNC_keymgmt_validate()\fR should return 1 on successful validation, or 0 on +failure. +.PP +\&\fBOSSL_FUNC_keymgmt_has()\fR should return 1 if all the selected data subsets are contained +in the given \fIkeydata\fR or 0 otherwise. +.PP +\&\fBOSSL_FUNC_keymgmt_query_operation_name()\fR should return a pointer to a string matching +the requested operation, or NULL if the same name used to fetch the keymgmt +applies. +.PP +\&\fBOSSL_FUNC_keymgmt_gettable_params()\fR and \fBOSSL_FUNC_keymgmt_settable_params()\fR +\&\fBOSSL_FUNC_keymgmt_import_types()\fR, \fBOSSL_FUNC_keymgmt_import_types_ex()\fR, +\&\fBOSSL_FUNC_keymgmt_export_types()\fR, \fBOSSL_FUNC_keymgmt_export_types_ex()\fR +should +always return a constant \fBOSSL_PARAM\fR\|(3) array. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_get_size\fR\|(3), +\&\fBEVP_PKEY_get_bits\fR\|(3), +\&\fBEVP_PKEY_get_security_bits\fR\|(3), +\&\fBprovider\fR\|(7), +\&\fBEVP_PKEY\-X25519\fR\|(7), +\&\fBEVP_PKEY\-X448\fR\|(7), +\&\fBEVP_PKEY\-ED25519\fR\|(7), +\&\fBEVP_PKEY\-ED448\fR\|(7), +\&\fBEVP_PKEY\-EC\fR\|(7), +\&\fBEVP_PKEY\-RSA\fR\|(7), +\&\fBEVP_PKEY\-DSA\fR\|(7), +\&\fBEVP_PKEY\-DH\fR\|(7), +\&\fBEVP_PKEY\-ML\-DSA\fR\|(7), +\&\fBEVP_PKEY\-ML\-KEM\fR\|(7), +\&\fBEVP_PKEY\-SLH\-DSA\fR\|(7). +.SH HISTORY +.IX Header "HISTORY" +The KEYMGMT interface was introduced in OpenSSL 3.0. +.PP +Functions \fBOSSL_FUNC_keymgmt_import_types_ex()\fR, and \fBOSSL_FUNC_keymgmt_export_types_ex()\fR +were added with OpenSSL 3.2. +.PP +The functions \fBOSSL_FUNC_keymgmt_gen_get_params()\fR and +\&\fBOSSL_FUNC_keymgmt_gen_gettable_params()\fR were added in OpenSSL 3.4. +.PP +The parameters "sign\-check" and "fips\-indicator" were added in OpenSSL 3.4. +.PP +Support for the \fBML\-DSA\fR, \fBML\-KEM\fR and \fBSLH\-DSA\fR algorithms was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-mac.7 b/static/netbsd/man7/provider-mac.7 new file mode 100644 index 00000000..deeb7562 --- /dev/null +++ b/static/netbsd/man7/provider-mac.7 @@ -0,0 +1,320 @@ +.\" $NetBSD: provider-mac.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-MAC 7" +.TH PROVIDER-MAC 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-mac \- The mac library <\-> provider functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_mac_newctx(void *provctx); +\& void OSSL_FUNC_mac_freectx(void *mctx); +\& void *OSSL_FUNC_mac_dupctx(void *src); +\& +\& /* Encryption/decryption */ +\& int OSSL_FUNC_mac_init(void *mctx, unsigned char *key, size_t keylen, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_mac_init_skey(void *mctx, const void *key, const OSSL_PARAM params[]); +\& int OSSL_FUNC_mac_update(void *mctx, const unsigned char *in, size_t inl); +\& int OSSL_FUNC_mac_final(void *mctx, unsigned char *out, size_t *outl, size_t outsize); +\& +\& /* MAC parameter descriptors */ +\& const OSSL_PARAM *OSSL_FUNC_mac_gettable_params(void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_mac_gettable_ctx_params(void *mctx, void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_mac_settable_ctx_params(void *mctx, void *provctx); +\& +\& /* MAC parameters */ +\& int OSSL_FUNC_mac_get_params(OSSL_PARAM params[]); +\& int OSSL_FUNC_mac_get_ctx_params(void *mctx, OSSL_PARAM params[]); +\& int OSSL_FUNC_mac_set_ctx_params(void *mctx, const OSSL_PARAM params[]); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The MAC operation enables providers to implement mac algorithms and make +them available to applications via the API functions \fBEVP_MAC_init\fR\|(3), +\&\fBEVP_MAC_update\fR\|(3) and \fBEVP_MAC_final\fR\|(3). +.PP +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via +\&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider\*(Aqs +\&\fBprovider_query_operation()\fR function +(see "Provider Functions" in \fBprovider\-base\fR\|(7)). +.PP +All these "functions" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the "function" \fBOSSL_FUNC_mac_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_mac_newctx_fn)(void *provctx); +\& static ossl_inline OSSL_FUNC_mac_newctx_fn +\& OSSL_FUNC_mac_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_mac_newctx OSSL_FUNC_MAC_NEWCTX +\& OSSL_FUNC_mac_freectx OSSL_FUNC_MAC_FREECTX +\& OSSL_FUNC_mac_dupctx OSSL_FUNC_MAC_DUPCTX +\& +\& OSSL_FUNC_mac_init OSSL_FUNC_MAC_INIT +\& OSSL_FUNC_mac_init_skey OSSL_FUNC_MAC_INIT_SKEY +\& OSSL_FUNC_mac_update OSSL_FUNC_MAC_UPDATE +\& OSSL_FUNC_mac_final OSSL_FUNC_MAC_FINAL +\& +\& OSSL_FUNC_mac_get_params OSSL_FUNC_MAC_GET_PARAMS +\& OSSL_FUNC_mac_get_ctx_params OSSL_FUNC_MAC_GET_CTX_PARAMS +\& OSSL_FUNC_mac_set_ctx_params OSSL_FUNC_MAC_SET_CTX_PARAMS +\& +\& OSSL_FUNC_mac_gettable_params OSSL_FUNC_MAC_GETTABLE_PARAMS +\& OSSL_FUNC_mac_gettable_ctx_params OSSL_FUNC_MAC_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_mac_settable_ctx_params OSSL_FUNC_MAC_SETTABLE_CTX_PARAMS +.Ve +.PP +A mac algorithm implementation may not implement all of these functions. +In order to be a consistent set of functions, at least the following functions +must be implemented: \fBOSSL_FUNC_mac_newctx()\fR, \fBOSSL_FUNC_mac_freectx()\fR, +at least one of \fBOSSL_FUNC_mac_init()\fR or \fBOSSL_FUNC_mac_init_skey()\fR, +\&\fBOSSL_FUNC_mac_update()\fR, \fBOSSL_FUNC_mac_final()\fR. +All other functions are optional. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_mac_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during a mac operation. +A pointer to this context will be passed back in a number of the other mac +operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +.PP +\&\fBOSSL_FUNC_mac_freectx()\fR is passed a pointer to the provider side mac context in +the \fImctx\fR parameter. +If it receives NULL as \fImctx\fR value, it should not do anything other than +return. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_mac_dupctx()\fR should duplicate the provider side mac context in the +\&\fImctx\fR parameter and return the duplicate copy. +.SS "Encryption/Decryption Functions" +.IX Subsection "Encryption/Decryption Functions" +\&\fBOSSL_FUNC_mac_init()\fR initialises a mac operation given a newly created provider +side mac context in the \fImctx\fR parameter. The \fIparams\fR are set before setting +the MAC \fIkey\fR of \fIkeylen\fR bytes. +.PP +\&\fBOSSL_FUNC_mac_init_skey()\fR is similar but uses an opaque provider\-specific object +to initialize the MAC context. +.PP +\&\fBOSSL_FUNC_mac_update()\fR is called to supply data for MAC computation of a previously +initialised mac operation. +The \fImctx\fR parameter contains a pointer to a previously initialised provider +side context. +\&\fBOSSL_FUNC_mac_update()\fR may be called multiple times for a single mac operation. +.PP +\&\fBOSSL_FUNC_mac_final()\fR completes the MAC computation started through previous +\&\fBOSSL_FUNC_mac_init()\fR and \fBOSSL_FUNC_mac_update()\fR calls. +The \fImctx\fR parameter contains a pointer to the provider side context. +The resulting MAC should be written to \fIout\fR and the amount of data written +to \fI*outl\fR, which should not exceed \fIoutsize\fR bytes. +The same expectations apply to \fIoutsize\fR as documented for +\&\fBEVP_MAC_final\fR\|(3). +.SS "Mac Parameters" +.IX Subsection "Mac Parameters" +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by +these functions. +.PP +\&\fBOSSL_FUNC_mac_get_params()\fR gets details of parameter values associated with the +provider algorithm and stores them in \fIparams\fR. +.PP +\&\fBOSSL_FUNC_mac_set_ctx_params()\fR sets mac parameters associated with the given +provider side mac context \fImctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_mac_get_ctx_params()\fR gets details of currently set parameter values +associated with the given provider side mac context \fImctx\fR and stores them +in \fIparams\fR. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_mac_gettable_params()\fR, \fBOSSL_FUNC_mac_gettable_ctx_params()\fR, +and \fBOSSL_FUNC_mac_settable_ctx_params()\fR all return constant \fBOSSL_PARAM\fR\|(3) +arrays as descriptors of the parameters that \fBOSSL_FUNC_mac_get_params()\fR, +\&\fBOSSL_FUNC_mac_get_ctx_params()\fR, and \fBOSSL_FUNC_mac_set_ctx_params()\fR +can handle, respectively. \fBOSSL_FUNC_mac_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_mac_settable_ctx_params()\fR will return the parameters associated +with the provider side context \fImctx\fR in its current state if it is +not NULL. Otherwise, they return the parameters associated with the +provider side algorithm \fIprovctx\fR. +.PP +All MAC implementations are expected to handle the following parameters: +.IP "with \fBOSSL_FUNC_set_ctx_params()\fR:" 4 +.IX Item "with OSSL_FUNC_set_ctx_params():" +.RS 4 +.PD 0 +.IP """key"" (\fBOSSL_MAC_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_MAC_PARAM_KEY) " +.PD +Sets the key in the associated MAC ctx. This is identical to passing a \fIkey\fR +argument to the \fBOSSL_FUNC_mac_init()\fR function. +.RE +.RS 4 +.RE +.IP "with \fBOSSL_FUNC_get_params()\fR:" 4 +.IX Item "with OSSL_FUNC_get_params():" +.RS 4 +.PD 0 +.IP """size"" (\fBOSSL_MAC_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_MAC_PARAM_SIZE) " +.PD +Can be used to get the default MAC size (which might be the only allowable +MAC size for the implementation). +.Sp +Note that some implementations allow setting the size that the resulting MAC +should have as well, see the documentation of the implementation. +.RE +.RS 4 +.IP """size"" (\fBOSSL_MAC_PARAM_BLOCK_SIZE\fR) " 4 +.IX Item """size"" (OSSL_MAC_PARAM_BLOCK_SIZE) " +Can be used to get the MAC block size (if supported by the algorithm). +.RE +.RS 4 +.RE +.PP +The OpenSSL FIPS provider may support the following parameters: +.IP """fips\-indicator"" (\fBOSSL_MAC_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_MAC_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling the final function. It may return 0 if +either "no\-short\-mac" or "key\-check" are set to 0. +.IP """no\-short\-mac"" (\fBOSSL_MAC_PARAM_FIPS_NO_SHORT_MAC\fR) " 4 +.IX Item """no-short-mac"" (OSSL_MAC_PARAM_FIPS_NO_SHORT_MAC) " +If required this parameter should be set early via an init function. +The default value of 1 causes an error when too short MAC output is +asked for. Setting this to 0 will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.IP """key\-check"" (\fBOSSL_MAC_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_MAC_PARAM_FIPS_KEY_CHECK) " +If required this parameter should be set before OSSL_FUNC_mac_init. +The default value of 1 causes an error when small key sizes are +asked for. Setting this to 0 will ignore the error and set the approved +"fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SH NOTES +.IX Header "NOTES" +The MAC life\-cycle is described in \fBlife_cycle\-rand\fR\|(7). Providers should +ensure that the various transitions listed there are supported. At some point +the EVP layer will begin enforcing the listed transitions. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_mac_newctx()\fR and \fBOSSL_FUNC_mac_dupctx()\fR should return the newly created +provider side mac context, or NULL on failure. +.PP +\&\fBOSSL_FUNC_mac_init()\fR, \fBOSSL_FUNC_mac_init_skey()\fR, +\&\fBOSSL_FUNC_mac_update()\fR, \fBOSSL_FUNC_mac_final()\fR, \fBOSSL_FUNC_mac_get_params()\fR, +\&\fBOSSL_FUNC_mac_get_ctx_params()\fR and \fBOSSL_FUNC_mac_set_ctx_params()\fR should return 1 for +success or 0 on error. +.PP +\&\fBOSSL_FUNC_mac_gettable_params()\fR, \fBOSSL_FUNC_mac_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_mac_settable_ctx_params()\fR should return a constant \fBOSSL_PARAM\fR\|(3) +array, or NULL if none is offered. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), +\&\fBEVP_MAC\-BLAKE2\fR\|(7), \fBEVP_MAC\-CMAC\fR\|(7), \fBEVP_MAC\-GMAC\fR\|(7), +\&\fBEVP_MAC\-HMAC\fR\|(7), \fBEVP_MAC\-KMAC\fR\|(7), \fBEVP_MAC\-Poly1305\fR\|(7), +\&\fBEVP_MAC\-Siphash\fR\|(7), +\&\fBlife_cycle\-mac\fR\|(7), \fBEVP_MAC\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The provider MAC interface was introduced in OpenSSL 3.0. +The parameters "no\-short\-mac" and "fips\-indicator" were added in OpenSSL 3.4. +.PP +The function \fBOSSL_FUNC_mac_init_skey()\fR was introduced in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-object.7 b/static/netbsd/man7/provider-object.7 new file mode 100644 index 00000000..2c4dd6ee --- /dev/null +++ b/static/netbsd/man7/provider-object.7 @@ -0,0 +1,213 @@ +.\" $NetBSD: provider-object.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-OBJECT 7" +.TH PROVIDER-OBJECT 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-object \- A specification for a provider\-native object abstraction +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The provider\-native object abstraction is a set of \fBOSSL_PARAM\fR\|(3) keys and +values that can be used to pass provider\-native objects to OpenSSL library +code or between different provider operation implementations with the help +of OpenSSL library code. +.PP +The intention is that certain provider\-native operations can pass any sort +of object that belong with other operations, or with OpenSSL library code. +.PP +An object may be passed in the following manners: +.IP 1. 4 +\&\fIBy value\fR +.Sp +This means that the \fIobject data\fR is passed as an octet string or an UTF8 +string, which can be handled in diverse ways by other provided implementations. +The encoding of the object depends on the context it\*(Aqs used in; for example, +\&\fBOSSL_DECODER\fR\|(3) allows multiple encodings, depending on existing decoders. +If central OpenSSL library functionality is to handle the data directly, it +\&\fBmust\fR be encoded in DER for all object types except for \fBOSSL_OBJECT_NAME\fR +(see "Parameter reference" below), where it\*(Aqs assumed to a plain UTF8 string. +.IP 2. 4 +\&\fIBy reference\fR +.Sp +This means that the \fIobject data\fR isn\*(Aqt passed directly, an \fIobject +reference\fR is passed instead. It\*(Aqs an octet string that only the correct +provider understands correctly. +.PP +Objects \fIby value\fR can be used by anything that handles DER encoded +objects. +.PP +Objects \fIby reference\fR need a higher level of cooperation from the +implementation where the object originated (let\*(Aqs call it X) and its target +implementation (let\*(Aqs call it Y): +.IP 1. 4 +\&\fIAn object loading function in the target implementation\fR +.Sp +The target implementation (Y) may have a function that can take an \fIobject +reference\fR. This can only be used if the target implementation is from the +same provider as the one originating the object abstraction in question (X). +.Sp +The exact target implementation to use is determined from the \fIobject type\fR +and possibly the \fIobject data type\fR. +For example, when the OpenSSL library receives an object abstraction with the +\&\fIobject type\fR \fBOSSL_OBJECT_PKEY\fR, it will fetch a \fBprovider\-keymgmt\fR\|(7) +using the \fIobject data type\fR as its key type (the second argument in +\&\fBEVP_KEYMGMT_fetch\fR\|(3)). +.IP 2. 4 +\&\fIAn object exporter in the originating implementation\fR +.Sp +The originating implementation (X) may have an exporter function. This +exporter function can be used to export the object in \fBOSSL_PARAM\fR\|(3) form, +that can then be imported by the target implementation\*(Aqs imported function. +.Sp +This can be used when it\*(Aqs not possible to fetch the target implementation +(Y) from the same provider. +.SS "Parameter reference" +.IX Subsection "Parameter reference" +A provider\-native object abstraction is an \fBOSSL_PARAM\fR\|(3) with a selection +of the following parameters: +.IP """data"" (\fBOSSL_OBJECT_PARAM_DATA\fR) or " 4 +.IX Item """data"" (OSSL_OBJECT_PARAM_DATA) or " +The object data \fIpassed by value\fR. +.IP """reference"" (\fBOSSL_OBJECT_PARAM_REFERENCE\fR) " 4 +.IX Item """reference"" (OSSL_OBJECT_PARAM_REFERENCE) " +The object data \fIpassed by reference\fR. +.IP """type"" (\fBOSSL_OBJECT_PARAM_TYPE\fR) " 4 +.IX Item """type"" (OSSL_OBJECT_PARAM_TYPE) " +The \fIobject type\fR, a number that may have any of the following values (all +defined in \fI\fR): +.RS 4 +.IP \fBOSSL_OBJECT_NAME\fR 4 +.IX Item "OSSL_OBJECT_NAME" +The object data may only be \fIpassed by value\fR, and should be a UTF8 +string. +.Sp +This is useful for \fBprovider\-storemgmt\fR\|(7) when a URI load results in new +URIs. +.IP \fBOSSL_OBJECT_PKEY\fR 4 +.IX Item "OSSL_OBJECT_PKEY" +The object data is suitable as provider\-native \fBEVP_PKEY\fR key data. The +object data may be \fIpassed by value\fR or \fIpassed by reference\fR. +.IP \fBOSSL_OBJECT_CERT\fR 4 +.IX Item "OSSL_OBJECT_CERT" +The object data is suitable as \fBX509\fR data. The object data for this +object type can only be \fIpassed by value\fR, and should be an octet string. +.Sp +Since there\*(Aqs no provider\-native X.509 object, OpenSSL libraries that +receive this object abstraction are expected to convert the data to a +\&\fBX509\fR object with \fBd2i_X509()\fR. +.IP \fBOSSL_OBJECT_CRL\fR 4 +.IX Item "OSSL_OBJECT_CRL" +The object data is suitable as \fBX509_CRL\fR data. The object data can +only be \fIpassed by value\fR, and should be an octet string. +.Sp +Since there\*(Aqs no provider\-native X.509 CRL object, OpenSSL libraries that +receive this object abstraction are expected to convert the data to a +\&\fBX509_CRL\fR object with \fBd2i_X509_CRL()\fR. +.RE +.RS 4 +.RE +.IP """data\-type"" (\fBOSSL_OBJECT_PARAM_DATA_TYPE\fR) " 4 +.IX Item """data-type"" (OSSL_OBJECT_PARAM_DATA_TYPE) " +The specific type of the object content. Legitimate values depend on the +object type; if it is \fBOSSL_OBJECT_PKEY\fR, the data type is expected to be a +key type suitable for fetching a \fBprovider\-keymgmt\fR\|(7) that can handle the +data. +.IP """data\-structure"" (\fBOSSL_OBJECT_PARAM_DATA_STRUCTURE\fR) " 4 +.IX Item """data-structure"" (OSSL_OBJECT_PARAM_DATA_STRUCTURE) " +The outermost structure of the object content. Legitimate values depend on +the object type. +.IP """desc"" (\fBOSSL_OBJECT_PARAM_DESC\fR) " 4 +.IX Item """desc"" (OSSL_OBJECT_PARAM_DESC) " +A human readable text that describes extra details on the object. +.PP +When a provider\-native object abstraction is used, it \fImust\fR contain object +data in at least one form (object data \fIpassed by value\fR, i.e. the "data" +item, or object data \fIpassed by reference\fR, i.e. the "reference" item). +Both may be present at once, in which case the OpenSSL library code that +receives this will use the most optimal variant. +.PP +For objects with the object type \fBOSSL_OBJECT_NAME\fR, that object type +\&\fImust\fR be given. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \fBOSSL_DECODER\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The concept of providers and everything surrounding them was +introduced in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-rand.7 b/static/netbsd/man7/provider-rand.7 new file mode 100644 index 00000000..fe091404 --- /dev/null +++ b/static/netbsd/man7/provider-rand.7 @@ -0,0 +1,362 @@ +.\" $NetBSD: provider-rand.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-RAND 7" +.TH PROVIDER-RAND 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-rand \- The random number generation library <\-> provider +functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_rand_newctx(void *provctx, void *parent, +\& const OSSL_DISPATCH *parent_calls); +\& void OSSL_FUNC_rand_freectx(void *ctx); +\& +\& /* Random number generator functions: NIST */ +\& int OSSL_FUNC_rand_instantiate(void *ctx, unsigned int strength, +\& int prediction_resistance, +\& const unsigned char *pstr, size_t pstr_len, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_rand_uninstantiate(void *ctx); +\& int OSSL_FUNC_rand_generate(void *ctx, unsigned char *out, size_t outlen, +\& unsigned int strength, int prediction_resistance, +\& const unsigned char *addin, size_t addin_len); +\& int OSSL_FUNC_rand_reseed(void *ctx, int prediction_resistance, +\& const unsigned char *ent, size_t ent_len, +\& const unsigned char *addin, size_t addin_len); +\& +\& /* Random number generator functions: additional */ +\& size_t OSSL_FUNC_rand_nonce(void *ctx, unsigned char *out, size_t outlen, +\& int strength, size_t min_noncelen, +\& size_t max_noncelen); +\& size_t OSSL_FUNC_rand_get_seed(void *ctx, unsigned char **buffer, +\& int entropy, size_t min_len, size_t max_len, +\& int prediction_resistance, +\& const unsigned char *adin, size_t adin_len); +\& void OSSL_FUNC_rand_clear_seed(void *ctx, unsigned char *buffer, size_t b_len); +\& int OSSL_FUNC_rand_verify_zeroization(void *ctx); +\& +\& /* Context Locking */ +\& int OSSL_FUNC_rand_enable_locking(void *ctx); +\& int OSSL_FUNC_rand_lock(void *ctx); +\& void OSSL_FUNC_rand_unlock(void *ctx); +\& +\& /* RAND parameter descriptors */ +\& const OSSL_PARAM *OSSL_FUNC_rand_gettable_params(void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_rand_gettable_ctx_params(void *ctx, void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_rand_settable_ctx_params(void *ctx, void *provctx); +\& +\& /* RAND parameters */ +\& int OSSL_FUNC_rand_get_params(OSSL_PARAM params[]); +\& int OSSL_FUNC_rand_get_ctx_params(void *ctx, OSSL_PARAM params[]); +\& int OSSL_FUNC_rand_set_ctx_params(void *ctx, const OSSL_PARAM params[]); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The RAND operation enables providers to implement random number generation +algorithms and random number sources and make +them available to applications via the API function \fBEVP_RAND\fR\|(3). +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_rand_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during a rand operation. +A pointer to this context will be passed back in a number of the other rand +operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). +The parameter \fIparent\fR specifies another rand instance to be used for +seeding purposes. If NULL and the specific instance supports it, the +operating system will be used for seeding. +The parameter \fIparent_calls\fR points to the dispatch table for \fIparent\fR. +Thus, the parent need not be from the same provider as the new instance. +.PP +\&\fBOSSL_FUNC_rand_freectx()\fR is passed a pointer to the provider side rand context in +the \fImctx\fR parameter. +If it receives NULL as \fIctx\fR value, it should not do anything other than +return. +This function should free any resources associated with that context. +.SS "Random Number Generator Functions: NIST" +.IX Subsection "Random Number Generator Functions: NIST" +These functions correspond to those defined in NIST SP 800\-90A and SP 800\-90C. +.PP +\&\fBOSSL_FUNC_rand_instantiate()\fR is used to instantiate the DRBG \fIctx\fR at a requested +security \fIstrength\fR. In addition, \fIprediction_resistance\fR can be requested. +Additional input \fIaddin\fR of length \fIaddin_len\fR bytes can optionally +be provided. The parameters specified in \fIparams\fR configure the DRBG and these +should be processed before instantiation. +.PP +\&\fBOSSL_FUNC_rand_uninstantiate()\fR is used to uninstantiate the DRBG \fIctx\fR. After being +uninstantiated, a DRBG is unable to produce output until it is instantiated +anew. +.PP +\&\fBOSSL_FUNC_rand_generate()\fR is used to generate random bytes from the DRBG \fIctx\fR. +It will generate \fIoutlen\fR bytes placing them into the buffer pointed to by +\&\fIout\fR. The generated bytes will meet the specified security \fIstrength\fR and, +if \fIprediction_resistance\fR is true, the bytes will be produced after reseeding +from a live entropy source. Additional input \fIaddin\fR of length \fIaddin_len\fR +bytes can optionally be provided. +.SS "Random Number Generator Functions: Additional" +.IX Subsection "Random Number Generator Functions: Additional" +\&\fBOSSL_FUNC_rand_nonce()\fR is used to generate a nonce of the given \fIstrength\fR with a +length from \fImin_noncelen\fR to \fImax_noncelen\fR. If the output buffer \fIout\fR is +NULL, the length of the nonce should be returned. +.PP +\&\fBOSSL_FUNC_rand_get_seed()\fR is used by deterministic generators to obtain their +seeding material from their parent. The seed bytes will meet the specified +security level of \fIentropy\fR bits and there will be between \fImin_len\fR +and \fImax_len\fR inclusive bytes in total. If \fIprediction_resistance\fR is +true, the bytes will be produced from a live entropy source. Additional +input \fIaddin\fR of length \fIaddin_len\fR bytes can optionally be provided. +A pointer to the seed material is returned in \fI*buffer\fR and this must be +freed by a later call to \fBOSSL_FUNC_rand_clear_seed()\fR. +.PP +\&\fBOSSL_FUNC_rand_clear_seed()\fR frees a seed \fIbuffer\fR of length \fIb_len\fR bytes +which was previously allocated by \fBOSSL_FUNC_rand_get_seed()\fR. +.PP +\&\fBOSSL_FUNC_rand_verify_zeroization()\fR is used to determine if the internal state of the +DRBG is zero. This capability is mandated by NIST as part of the self +tests, it is unlikely to be useful in other circumstances. +.SS "Context Locking" +.IX Subsection "Context Locking" +When DRBGs are used by multiple threads, there must be locking employed to +ensure their proper operation. Because locking introduces an overhead, it +is disabled by default. +.PP +\&\fBOSSL_FUNC_rand_enable_locking()\fR allows locking to be turned on for a DRBG and all of +its parent DRBGs. From this call onwards, the DRBG can be used in a thread +safe manner. +.PP +\&\fBOSSL_FUNC_rand_lock()\fR is used to lock a DRBG. Once locked, exclusive access +is guaranteed. +.PP +\&\fBOSSL_FUNC_rand_unlock()\fR is used to unlock a DRBG. +.SS "Rand Parameters" +.IX Subsection "Rand Parameters" +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by +these functions. +.PP +\&\fBOSSL_FUNC_rand_get_params()\fR gets details of parameter values associated with the +provider algorithm and stores them in \fIparams\fR. +.PP +\&\fBOSSL_FUNC_rand_set_ctx_params()\fR sets rand parameters associated with the given +provider side rand context \fIctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_rand_get_ctx_params()\fR gets details of currently set parameter values +associated with the given provider side rand context \fIctx\fR and stores them +in \fIparams\fR. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_rand_gettable_params()\fR, \fBOSSL_FUNC_rand_gettable_ctx_params()\fR, +and \fBOSSL_FUNC_rand_settable_ctx_params()\fR all return constant \fBOSSL_PARAM\fR\|(3) +arrays as descriptors of the parameters that \fBOSSL_FUNC_rand_get_params()\fR, +\&\fBOSSL_FUNC_rand_get_ctx_params()\fR, and \fBOSSL_FUNC_rand_set_ctx_params()\fR +can handle, respectively. \fBOSSL_FUNC_rand_gettable_ctx_params()\fR +and \fBOSSL_FUNC_rand_settable_ctx_params()\fR will return the parameters +associated with the provider side context \fIctx\fR in its current state +if it is not NULL. Otherwise, they return the parameters associated +with the provider side algorithm \fIprovctx\fR. +.PP +Parameters currently recognised by built\-in rands are as follows. Not all +parameters are relevant to, or are understood by all rands: +.IP """state"" (\fBOSSL_RAND_PARAM_STATE\fR) " 4 +.IX Item """state"" (OSSL_RAND_PARAM_STATE) " +Returns the state of the random number generator. +.IP """strength"" (\fBOSSL_RAND_PARAM_STRENGTH\fR) " 4 +.IX Item """strength"" (OSSL_RAND_PARAM_STRENGTH) " +Returns the bit strength of the random number generator. +.IP """fips\-indicator"" (\fBOSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This option is used by the OpenSSL FIPS provider and is not supported +by all EVP_RAND sources. +.PP +For rands that are also deterministic random bit generators (DRBGs), these +additional parameters are recognised. Not all +parameters are relevant to, or are understood by all DRBG rands: +.IP """reseed_requests"" (\fBOSSL_DRBG_PARAM_RESEED_REQUESTS\fR) " 4 +.IX Item """reseed_requests"" (OSSL_DRBG_PARAM_RESEED_REQUESTS) " +Reads or set the number of generate requests before reseeding the +associated RAND ctx. +.IP """reseed_time_interval"" (\fBOSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\fR) " 4 +.IX Item """reseed_time_interval"" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) " +Reads or set the number of elapsed seconds before reseeding the +associated RAND ctx. +.IP """max_request"" (\fBOSSL_DRBG_PARAM_RESEED_REQUESTS\fR) " 4 +.IX Item """max_request"" (OSSL_DRBG_PARAM_RESEED_REQUESTS) " +Specifies the maximum number of bytes that can be generated in a single +call to OSSL_FUNC_rand_generate. +.IP """min_entropylen"" (\fBOSSL_DRBG_PARAM_MIN_ENTROPYLEN\fR) " 4 +.IX Item """min_entropylen"" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) " +.PD 0 +.IP """max_entropylen"" (\fBOSSL_DRBG_PARAM_MAX_ENTROPYLEN\fR) " 4 +.IX Item """max_entropylen"" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) " +.PD +Specify the minimum and maximum number of bytes of random material that +can be used to seed the DRBG. +.IP """min_noncelen"" (\fBOSSL_DRBG_PARAM_MIN_NONCELEN\fR) " 4 +.IX Item """min_noncelen"" (OSSL_DRBG_PARAM_MIN_NONCELEN) " +.PD 0 +.IP """max_noncelen"" (\fBOSSL_DRBG_PARAM_MAX_NONCELEN\fR) " 4 +.IX Item """max_noncelen"" (OSSL_DRBG_PARAM_MAX_NONCELEN) " +.PD +Specify the minimum and maximum number of bytes of nonce that can be used to +instantiate the DRBG. +.IP """max_perslen"" (\fBOSSL_DRBG_PARAM_MAX_PERSLEN\fR) " 4 +.IX Item """max_perslen"" (OSSL_DRBG_PARAM_MAX_PERSLEN) " +.PD 0 +.IP """max_adinlen"" (\fBOSSL_DRBG_PARAM_MAX_ADINLEN\fR) " 4 +.IX Item """max_adinlen"" (OSSL_DRBG_PARAM_MAX_ADINLEN) " +.PD +Specify the minimum and maximum number of bytes of personalisation string +that can be used with the DRBG. +.IP """reseed_counter"" (\fBOSSL_DRBG_PARAM_RESEED_COUNTER\fR) " 4 +.IX Item """reseed_counter"" (OSSL_DRBG_PARAM_RESEED_COUNTER) " +Specifies the number of times the DRBG has been seeded or reseeded. +.IP """digest"" (\fBOSSL_DRBG_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_DRBG_PARAM_DIGEST) " +.PD 0 +.IP """cipher"" (\fBOSSL_DRBG_PARAM_CIPHER\fR) " 4 +.IX Item """cipher"" (OSSL_DRBG_PARAM_CIPHER) " +.IP """mac"" (\fBOSSL_DRBG_PARAM_MAC\fR) " 4 +.IX Item """mac"" (OSSL_DRBG_PARAM_MAC) " +.PD +Sets the name of the underlying cipher, digest or MAC to be used. +It must name a suitable algorithm for the DRBG that\*(Aqs being used. +.IP """properties"" (\fBOSSL_DRBG_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_DRBG_PARAM_PROPERTIES) " +Sets the properties to be queried when trying to fetch an underlying algorithm. +This must be given together with the algorithm naming parameter to be +considered valid. +.PP +The OpenSSL FIPS provider also supports the following parameters: +.IP """fips\-indicator"" (\fBOSSL_DRBG_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_DRBG_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling \fBOSSL_FUNC_rand_generate()\fR. It may +return 0 if the "digest\-check" is set to 0. +.IP """digest\-check"" (\fBOSSL_DRBG_PARAM_FIPS_DIGEST_CHECK\fR) " 4 +.IX Item """digest-check"" (OSSL_DRBG_PARAM_FIPS_DIGEST_CHECK) " +If required this parameter should be set before the digest is set. +The default value of 1 causes an error when the digest is set if the digest is +not FIPS approved (e.g. truncated digests). Setting this to 0 will ignore +the error and set the approved "fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_rand_newctx()\fR should return the newly created +provider side rand context, or NULL on failure. +.PP +\&\fBOSSL_FUNC_rand_gettable_params()\fR, \fBOSSL_FUNC_rand_gettable_ctx_params()\fR and +\&\fBOSSL_FUNC_rand_settable_ctx_params()\fR should return a constant \fBOSSL_PARAM\fR\|(3) +array, or NULL if none is offered. +.PP +\&\fBOSSL_FUNC_rand_nonce()\fR returns the size of the generated nonce, or 0 on error. +.PP +\&\fBOSSL_FUNC_rand_get_seed()\fR returns the size of the generated seed, or 0 on +error. +.PP +All of the remaining functions should return 1 for success or 0 on error. +.SH NOTES +.IX Header "NOTES" +The RAND life\-cycle is described in \fBlife_cycle\-rand\fR\|(7). Providers should +ensure that the various transitions listed there are supported. At some point +the EVP layer will begin enforcing the listed transitions. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), +\&\fBRAND\fR\|(7), +\&\fBEVP_RAND\fR\|(7), +\&\fBlife_cycle\-rand\fR\|(7), +\&\fBEVP_RAND\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The provider RAND interface was introduced in OpenSSL 3.0. +The Rand Parameters "fips\-indicator" and "digest\-check" were added in +OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-signature.7 b/static/netbsd/man7/provider-signature.7 new file mode 100644 index 00000000..f2fdb292 --- /dev/null +++ b/static/netbsd/man7/provider-signature.7 @@ -0,0 +1,718 @@ +.\" $NetBSD: provider-signature.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-SIGNATURE 7" +.TH PROVIDER-SIGNATURE 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-signature \- The signature library <\-> provider functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Context management */ +\& void *OSSL_FUNC_signature_newctx(void *provctx, const char *propq); +\& void OSSL_FUNC_signature_freectx(void *ctx); +\& void *OSSL_FUNC_signature_dupctx(void *ctx); +\& +\& /* Get the key types that a signature algorithm supports */ +\& const char **OSSL_FUNC_signature_query_key_types(void); +\& +\& /* Signing */ +\& int OSSL_FUNC_signature_sign_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_signature_sign(void *ctx, unsigned char *sig, size_t *siglen, +\& size_t sigsize, const unsigned char *tbs, size_t tbslen); +\& int OSSL_FUNC_signature_sign_message_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_signature_sign_message_update(void *ctx, const unsigned char *in, +\& size_t inlen); +\& int OSSL_FUNC_signature_sign_message_final(void *ctx, unsigned char *sig, +\& size_t *siglen, size_t sigsize); +\& +\& /* Verifying */ +\& int OSSL_FUNC_signature_verify_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_signature_verify(void *ctx, const unsigned char *sig, size_t siglen, +\& const unsigned char *tbs, size_t tbslen); +\& int OSSL_FUNC_signature_verify_message_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_signature_verify_message_update(void *ctx, const unsigned char *in, +\& size_t inlen); +\& /* +\& * OSSL_FUNC_signature_verify_message_final requires that the signature to be +\& * verified is specified via a "signature" OSSL_PARAM, which is given with a +\& * previous call of OSSL_FUNC_signature_set_ctx_params(). +\& */ +\& int OSSL_FUNC_signature_verify_message_final(void *ctx); +\& +\& /* Verify Recover */ +\& int OSSL_FUNC_signature_verify_recover_init(void *ctx, void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_signature_verify_recover(void *ctx, unsigned char *rout, +\& size_t *routlen, size_t routsize, +\& const unsigned char *sig, size_t siglen); +\& +\& /* Digest Sign */ +\& int OSSL_FUNC_signature_digest_sign_init(void *ctx, const char *mdname, +\& void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_signature_digest_sign_update(void *ctx, const unsigned char *data, +\& size_t datalen); +\& int OSSL_FUNC_signature_digest_sign_final(void *ctx, unsigned char *sig, +\& size_t *siglen, size_t sigsize); +\& int OSSL_FUNC_signature_digest_sign(void *ctx, +\& unsigned char *sig, size_t *siglen, +\& size_t sigsize, const unsigned char *tbs, +\& size_t tbslen); +\& +\& /* Digest Verify */ +\& int OSSL_FUNC_signature_digest_verify_init(void *ctx, const char *mdname, +\& void *provkey, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_signature_digest_verify_update(void *ctx, +\& const unsigned char *data, +\& size_t datalen); +\& int OSSL_FUNC_signature_digest_verify_final(void *ctx, const unsigned char *sig, +\& size_t siglen); +\& int OSSL_FUNC_signature_digest_verify(void *ctx, const unsigned char *sig, +\& size_t siglen, const unsigned char *tbs, +\& size_t tbslen); +\& +\& /* Signature parameters */ +\& int OSSL_FUNC_signature_get_ctx_params(void *ctx, OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_signature_gettable_ctx_params(void *ctx, +\& void *provctx); +\& int OSSL_FUNC_signature_set_ctx_params(void *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_signature_settable_ctx_params(void *ctx, +\& void *provctx); +\& /* MD parameters */ +\& int OSSL_FUNC_signature_get_ctx_md_params(void *ctx, OSSL_PARAM params[]); +\& const OSSL_PARAM * OSSL_FUNC_signature_gettable_ctx_md_params(void *ctx); +\& int OSSL_FUNC_signature_set_ctx_md_params(void *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM * OSSL_FUNC_signature_settable_ctx_md_params(void *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7) +for further information. +.PP +The signature (OSSL_OP_SIGNATURE) operation enables providers to implement +signature algorithms and make them available to applications via the API +functions \fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify\fR\|(3), +and \fBEVP_PKEY_verify_recover\fR\|(3) (as well as other related functions). +.PP +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via +\&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider\*(Aqs +\&\fBprovider_query_operation()\fR function +(see "Provider Functions" in \fBprovider\-base\fR\|(7)). +.PP +All these "functions" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +For example, the "function" \fBOSSL_FUNC_signature_newctx()\fR has these: +.PP +.Vb 3 +\& typedef void *(OSSL_FUNC_signature_newctx_fn)(void *provctx, const char *propq); +\& static ossl_inline OSSL_FUNC_signature_newctx_fn +\& OSSL_FUNC_signature_newctx(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 3 +\& OSSL_FUNC_signature_newctx OSSL_FUNC_SIGNATURE_NEWCTX +\& OSSL_FUNC_signature_freectx OSSL_FUNC_SIGNATURE_FREECTX +\& OSSL_FUNC_signature_dupctx OSSL_FUNC_SIGNATURE_DUPCTX +\& +\& OSSL_FUNC_signature_query_key_types OSSL_FUNC_SIGNATURE_QUERY_KEY_TYPES +\& +\& OSSL_FUNC_signature_sign_init OSSL_FUNC_SIGNATURE_SIGN_INIT +\& OSSL_FUNC_signature_sign OSSL_FUNC_SIGNATURE_SIGN +\& OSSL_FUNC_signature_sign_message_init OSSL_FUNC_SIGNATURE_SIGN_MESSAGE_INIT +\& OSSL_FUNC_signature_sign_message_update OSSL_FUNC_SIGNATURE_SIGN_MESSAGE_UPDATE +\& OSSL_FUNC_signature_sign_message_final OSSL_FUNC_SIGNATURE_SIGN_MESSAGE_FINAL +\& +\& OSSL_FUNC_signature_verify_init OSSL_FUNC_SIGNATURE_VERIFY_INIT +\& OSSL_FUNC_signature_verify OSSL_FUNC_SIGNATURE_VERIFY +\& OSSL_FUNC_signature_verify_message_init OSSL_FUNC_SIGNATURE_VERIFY_MESSAGE_INIT +\& OSSL_FUNC_signature_verify_message_update OSSL_FUNC_SIGNATURE_VERIFY_MESSAGE_UPDATE +\& OSSL_FUNC_signature_verify_message_final OSSL_FUNC_SIGNATURE_VERIFY_MESSAGE_FINAL +\& +\& OSSL_FUNC_signature_verify_recover_init OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT +\& OSSL_FUNC_signature_verify_recover OSSL_FUNC_SIGNATURE_VERIFY_RECOVER +\& +\& OSSL_FUNC_signature_digest_sign_init OSSL_FUNC_SIGNATURE_DIGEST_SIGN_INIT +\& OSSL_FUNC_signature_digest_sign_update OSSL_FUNC_SIGNATURE_DIGEST_SIGN_UPDATE +\& OSSL_FUNC_signature_digest_sign_final OSSL_FUNC_SIGNATURE_DIGEST_SIGN_FINAL +\& OSSL_FUNC_signature_digest_sign OSSL_FUNC_SIGNATURE_DIGEST_SIGN +\& +\& OSSL_FUNC_signature_digest_verify_init OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_INIT +\& OSSL_FUNC_signature_digest_verify_update OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_UPDATE +\& OSSL_FUNC_signature_digest_verify_final OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_FINAL +\& OSSL_FUNC_signature_digest_verify OSSL_FUNC_SIGNATURE_DIGEST_VERIFY +\& +\& OSSL_FUNC_signature_get_ctx_params OSSL_FUNC_SIGNATURE_GET_CTX_PARAMS +\& OSSL_FUNC_signature_gettable_ctx_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_signature_set_ctx_params OSSL_FUNC_SIGNATURE_SET_CTX_PARAMS +\& OSSL_FUNC_signature_settable_ctx_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_PARAMS +\& +\& OSSL_FUNC_signature_get_ctx_md_params OSSL_FUNC_SIGNATURE_GET_CTX_MD_PARAMS +\& OSSL_FUNC_signature_gettable_ctx_md_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_MD_PARAMS +\& OSSL_FUNC_signature_set_ctx_md_params OSSL_FUNC_SIGNATURE_SET_CTX_MD_PARAMS +\& OSSL_FUNC_signature_settable_ctx_md_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_MD_PARAMS +.Ve +.PP +A signature algorithm implementation may not implement all of these functions. +In order to be a consistent set of functions we must have at least a set of +context functions (OSSL_FUNC_signature_newctx and OSSL_FUNC_signature_freectx) as well as a +set of "signature" functions, i.e. at least one of: +.IP "OSSL_FUNC_signature_sign_init and OSSL_FUNC_signature_sign" 4 +.IX Item "OSSL_FUNC_signature_sign_init and OSSL_FUNC_signature_sign" +Used via \fBEVP_PKEY_sign_init\fR\|(3) and \fBEVP_PKEY_sign\fR\|(3). +These functions operate on pre\-digested data (the "to be signed" or TBS value). +.IP "OSSL_FUNC_signature_sign_message_init and OSSL_FUNC_signature_sign" 4 +.IX Item "OSSL_FUNC_signature_sign_message_init and OSSL_FUNC_signature_sign" +Used via \fBEVP_PKEY_sign_message_init\fR\|(3) and \fBEVP_PKEY_sign\fR\|(3) when signing a complete message. +The implementation internally handles message digesting. +.IP "OSSL_FUNC_signature_sign_message_init, OSSL_FUNC_signature_sign_message_update and OSSL_FUNC_signature_sign_message_final" 4 +.IX Item "OSSL_FUNC_signature_sign_message_init, OSSL_FUNC_signature_sign_message_update and OSSL_FUNC_signature_sign_message_final" +Streaming variant of message signing, used via \fBEVP_PKEY_sign_message_init\fR\|(3), +\&\fBEVP_PKEY_sign_message_update\fR\|(3), and \fBEVP_PKEY_sign_message_final\fR\|(3). +.IP "OSSL_FUNC_signature_verify_init and OSSL_FUNC_signature_verify" 4 +.IX Item "OSSL_FUNC_signature_verify_init and OSSL_FUNC_signature_verify" +Used via \fBEVP_PKEY_verify_init\fR\|(3) and \fBEVP_PKEY_verify\fR\|(3). +These functions operate on pre\-digested data. +.IP "OSSL_FUNC_signature_verify_message_init and OSSL_FUNC_signature_verify" 4 +.IX Item "OSSL_FUNC_signature_verify_message_init and OSSL_FUNC_signature_verify" +Used via \fBEVP_PKEY_verify_message_init\fR\|(3) and \fBEVP_PKEY_verify\fR\|(3) when verifying a complete message. +The implementation internally handles message digesting. +.IP "OSSL_FUNC_signature_verify_message_init, OSSL_FUNC_signature_verify_message_update and OSSL_FUNC_signature_verify_message_final" 4 +.IX Item "OSSL_FUNC_signature_verify_message_init, OSSL_FUNC_signature_verify_message_update and OSSL_FUNC_signature_verify_message_final" +Streaming variant of message verification, used via \fBEVP_PKEY_verify_message_init\fR\|(3), +\&\fBEVP_PKEY_verify_message_update\fR\|(3), and \fBEVP_PKEY_verify_message_final\fR\|(3). +.IP "OSSL_FUNC_signature_verify_recover_init and OSSL_FUNC_signature_verify_recover" 4 +.IX Item "OSSL_FUNC_signature_verify_recover_init and OSSL_FUNC_signature_verify_recover" +Used via \fBEVP_PKEY_verify_recover_init\fR\|(3) and \fBEVP_PKEY_verify_recover\fR\|(3). +Applicable only to signature schemes that support signature recovery (such as RSA). +.IP "OSSL_FUNC_signature_digest_sign_init, OSSL_FUNC_signature_digest_sign_update and OSSL_FUNC_signature_digest_sign_final" 4 +.IX Item "OSSL_FUNC_signature_digest_sign_init, OSSL_FUNC_signature_digest_sign_update and OSSL_FUNC_signature_digest_sign_final" +Streaming digest\-sign variant, used via \fBEVP_DigestSignInit\fR\|(3), +\&\fBEVP_DigestSignUpdate\fR\|(3), and \fBEVP_DigestSignFinal\fR\|(3). +.IP "OSSL_FUNC_signature_digest_verify_init, OSSL_FUNC_signature_digest_verify_update and OSSL_FUNC_signature_digest_verify_final" 4 +.IX Item "OSSL_FUNC_signature_digest_verify_init, OSSL_FUNC_signature_digest_verify_update and OSSL_FUNC_signature_digest_verify_final" +Streaming digest\-verify variant, used via \fBEVP_DigestVerifyInit\fR\|(3), +\&\fBEVP_DigestVerifyUpdate\fR\|(3), and \fBEVP_DigestVerifyFinal\fR\|(3). +.IP "OSSL_FUNC_signature_digest_sign_init and OSSL_FUNC_signature_digest_sign" 4 +.IX Item "OSSL_FUNC_signature_digest_sign_init and OSSL_FUNC_signature_digest_sign" +One\-shot digest\-sign variant, used via \fBEVP_DigestSign\fR\|(3). +.IP "OSSL_FUNC_signature_digest_verify_init and OSSL_FUNC_signature_digest_verify" 4 +.IX Item "OSSL_FUNC_signature_digest_verify_init and OSSL_FUNC_signature_digest_verify" +One\-shot digest\-verify variant, used via \fBEVP_DigestVerify\fR\|(3). +.PP +\&\fBImportant Note for TLS Support:\fR For a provider signature implementation to +be usable within \fIlibssl\fR for TLS connections, it \fBmust\fR implement the +digest\-sign and digest\-verify functions +(OSSL_FUNC_signature_digest_sign_init/update/final or the one\-shot variant, and +OSSL_FUNC_signature_digest_verify_init/update/final or the one\-shot variant). +The TLS handshake code in \fIlibssl\fR specifically requires these digest functions +and will not use implementations that only provide the basic sign/verify functions +(OSSL_FUNC_signature_sign_init/sign or OSSL_FUNC_signature_verify_init/verify). +.PP +The choice of which function set to implement depends on your use case: +.IP \(bu 4 +For general\-purpose signature operations and TLS support: implement the +digest\-sign and digest\-verify functions. +.IP \(bu 4 +For operations on pre\-digested data only: implement the basic sign and verify +functions. +.IP \(bu 4 +For signature schemes with recovery capability: additionally implement the +verify\-recover functions. +.PP +The \fBOSSL_FUNC_signature_set_ctx_params()\fR and +\&\fBOSSL_FUNC_signature_settable_ctx_params()\fR functions are optional, +but if one of them is provided then the other one must also be provided. +The same applies to the \fBOSSL_FUNC_signature_get_ctx_params()\fR and +\&\fBOSSL_FUNC_signature_gettable_ctx_params()\fR functions, +as well as the "md_params" functions. +.PP +The \fBOSSL_FUNC_signature_dupctx()\fR function is optional. +It is not yet used by OpenSSL. +.PP +The \fBOSSL_FUNC_signature_query_key_types()\fR function is optional. +When present, it should return a NULL\-terminated array of strings +indicating the key types supported by the provider for signature operations. +Otherwise the signature algorithm name must match the given key +or match the default signature algorithm name of the key, +both checked using \fBEVP_SIGNATURE_is_a\fR\|(3). +.PP +A signature algorithm must also implement some mechanism for generating, +loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation. +See \fBprovider\-keymgmt\fR\|(7) for further details. +.SS "Context Management Functions" +.IX Subsection "Context Management Functions" +\&\fBOSSL_FUNC_signature_newctx()\fR should create and return a pointer to a provider side +structure for holding context information during a signature operation. +A pointer to this context will be passed back in a number of the other signature +operation function calls. +The parameter \fIprovctx\fR is the provider context generated during provider +initialisation (see \fBprovider\fR\|(7)). The \fIpropq\fR parameter is a property query +string that may be (optionally) used by the provider during any "fetches" that +it may perform (if it performs any). +.PP +\&\fBOSSL_FUNC_signature_freectx()\fR is passed a pointer to the provider side signature +context in the \fIctx\fR parameter. +This function should free any resources associated with that context. +.PP +\&\fBOSSL_FUNC_signature_dupctx()\fR should duplicate the provider side signature context in +the \fIctx\fR parameter and return the duplicate copy. +.SS "Signing Functions" +.IX Subsection "Signing Functions" +\&\fBOSSL_FUNC_signature_sign_init()\fR initialises a context for signing given a provider side +signature context in the \fIctx\fR parameter, and a pointer to a provider key object +in the \fIprovkey\fR parameter. +The \fIparams\fR, if not NULL, should be set on the context in a manner similar to +using \fBOSSL_FUNC_signature_set_ctx_params()\fR. +The key object should have been previously generated, loaded or imported into +the provider using the key management (OSSL_OP_KEYMGMT) operation (see +\&\fBprovider\-keymgmt\fR\|(7)). +.PP +\&\fBOSSL_FUNC_signature_sign()\fR performs the actual signing itself. +A previously initialised signature context is passed in the \fIctx\fR +parameter. +The data to be signed is pointed to be the \fItbs\fR parameter which is \fItbslen\fR +bytes long. +Unless \fIsig\fR is NULL, the signature should be written to the location pointed +to by the \fIsig\fR parameter and it should not exceed \fIsigsize\fR bytes in length. +The length of the signature should be written to \fI*siglen\fR. +If \fIsig\fR is NULL then the maximum length of the signature should be written to +\&\fI*siglen\fR. +.SS "Message Signing Functions" +.IX Subsection "Message Signing Functions" +These functions are suitable for providers that implement algorithms that +accumulate a full message and sign the result of that accumulation, such as +RSA\-SHA256. +.PP +\&\fBOSSL_FUNC_signature_sign_message_init()\fR initialises a context for signing a +message given a provider side signature context in the \fIctx\fR parameter, and a +pointer to a provider key object in the \fIprovkey\fR parameter. +The \fIparams\fR, if not NULL, should be set on the context in a manner similar to +using \fBOSSL_FUNC_signature_set_ctx_params()\fR. +The key object should have been previously generated, loaded or imported into +the provider using the key management (OSSL_OP_KEYMGMT) operation (see +\&\fBprovider\-keymgmt\fR\|(7)). +.PP +\&\fBOSSL_FUNC_signature_sign_message_update()\fR gathers the data pointed at by +\&\fIin\fR, which is \fIinlen\fR bytes long. +.PP +\&\fBOSSL_FUNC_signature_sign_message_final()\fR performs the actual signing on the +data that was gathered with \fBOSSL_FUNC_signature_sign_message_update()\fR. +.PP +\&\fBOSSL_FUNC_signature_sign()\fR can be used for one\-shot signature calls. In that +case, \fItbs\fR is expected to be the whole message to be signed, \fItbslen\fR bytes +long. +.PP +For both \fBOSSL_FUNC_signature_sign_message_final()\fR and \fBOSSL_FUNC_signature_sign()\fR, +if \fIsig\fR is not NULL, the signature should be written to the location pointed +to by \fIsig\fR, and it should not exceed \fIsigsize\fR bytes in length. +The length of the signature should be written to \fI*siglen\fR. +If \fIsig\fR is NULL then the maximum length of the signature should be written to +\&\fI*siglen\fR. +.SS "Verify Functions" +.IX Subsection "Verify Functions" +\&\fBOSSL_FUNC_signature_verify_init()\fR initialises a context for verifying a signature given +a provider side signature context in the \fIctx\fR parameter, and a pointer to a +provider key object in the \fIprovkey\fR parameter. +The \fIparams\fR, if not NULL, should be set on the context in a manner similar to +using \fBOSSL_FUNC_signature_set_ctx_params()\fR. +The key object should have been previously generated, loaded or imported into +the provider using the key management (OSSL_OP_KEYMGMT) operation (see +\&\fBprovider\-keymgmt\fR\|(7)). +.PP +\&\fBOSSL_FUNC_signature_verify()\fR performs the actual verification itself. +A previously initialised signature context is passed in the \fIctx\fR parameter. +The data that the signature covers is pointed to be the \fItbs\fR parameter which +is \fItbslen\fR bytes long. +The signature is pointed to by the \fIsig\fR parameter which is \fIsiglen\fR bytes +long. +.SS "Message Verify Functions" +.IX Subsection "Message Verify Functions" +These functions are suitable for providers that implement algorithms that +accumulate a full message and verify a signature on the result of that +accumulation, such as RSA\-SHA256. +.PP +\&\fBOSSL_FUNC_signature_verify_message_init()\fR initialises a context for verifying +a signature on a message given a provider side signature context in the \fIctx\fR +parameter, and a pointer to a provider key object in the \fIprovkey\fR parameter. +The \fIparams\fR, if not NULL, should be set on the context in a manner similar to +using \fBOSSL_FUNC_signature_set_ctx_params()\fR. +The key object should have been previously generated, loaded or imported into +the provider using the key management (OSSL_OP_KEYMGMT) operation (see +\&\fBprovider\-keymgmt\fR\|(7)). +.PP +\&\fBOSSL_FUNC_signature_verify_message_update()\fR gathers the data pointed at by +\&\fIin\fR, which is \fIinlen\fR bytes long. +.PP +\&\fBOSSL_FUNC_signature_verify_message_final()\fR performs the actual verification on +the data that was gathered with \fBOSSL_FUNC_signature_verify_message_update()\fR. +The signature itself must have been passed through the "signature" +(\fBOSSL_SIGNATURE_PARAM_SIGNATURE\fR) Signature parameter +before this function is called. +.PP +\&\fBOSSL_FUNC_signature_verify()\fR can be used for one\-shot verification calls. In +that case, \fItbs\fR is expected to be the whole message to be verified on, +\&\fItbslen\fR bytes long. +.SS "Verify Recover Functions" +.IX Subsection "Verify Recover Functions" +\&\fBOSSL_FUNC_signature_verify_recover_init()\fR initialises a context for recovering the +signed data given a provider side signature context in the \fIctx\fR parameter, and +a pointer to a provider key object in the \fIprovkey\fR parameter. +The \fIparams\fR, if not NULL, should be set on the context in a manner similar to +using \fBOSSL_FUNC_signature_set_ctx_params()\fR. +The key object should have been previously generated, loaded or imported into +the provider using the key management (OSSL_OP_KEYMGMT) operation (see +\&\fBprovider\-keymgmt\fR\|(7)). +.PP +\&\fBOSSL_FUNC_signature_verify_recover()\fR performs the actual verify recover itself. +A previously initialised signature context is passed in the \fIctx\fR parameter. +The signature is pointed to by the \fIsig\fR parameter which is \fIsiglen\fR bytes +long. +Unless \fIrout\fR is NULL, the recovered data should be written to the location +pointed to by \fIrout\fR which should not exceed \fIroutsize\fR bytes in length. +The length of the recovered data should be written to \fI*routlen\fR. +If \fIrout\fR is NULL then the maximum size of the output buffer is written to +the \fIroutlen\fR parameter. +.SS "Digest Sign Functions" +.IX Subsection "Digest Sign Functions" +\&\fBOSSL_FUNC_signature_digest_sign_init()\fR initialises a context for signing given a +provider side signature context in the \fIctx\fR parameter, and a pointer to a +provider key object in the \fIprovkey\fR parameter. +The \fIparams\fR, if not NULL, should be set on the context in a manner similar to +using \fBOSSL_FUNC_signature_set_ctx_params()\fR and +\&\fBOSSL_FUNC_signature_set_ctx_md_params()\fR. +The key object should have been +previously generated, loaded or imported into the provider using the +key management (OSSL_OP_KEYMGMT) operation (see \fBprovider\-keymgmt\fR\|(7)). +The name of the digest to be used will be in the \fImdname\fR parameter. +.PP +\&\fBOSSL_FUNC_signature_digest_sign_update()\fR provides data to be signed in the \fIdata\fR +parameter which should be of length \fIdatalen\fR. A previously initialised +signature context is passed in the \fIctx\fR parameter. This function may be called +multiple times to cumulatively add data to be signed. +.PP +\&\fBOSSL_FUNC_signature_digest_sign_final()\fR finalises a signature operation previously +started through \fBOSSL_FUNC_signature_digest_sign_init()\fR and +\&\fBOSSL_FUNC_signature_digest_sign_update()\fR calls. Once finalised no more data will be +added through \fBOSSL_FUNC_signature_digest_sign_update()\fR. A previously initialised +signature context is passed in the \fIctx\fR parameter. Unless \fIsig\fR is NULL, the +signature should be written to the location pointed to by the \fIsig\fR parameter +and it should not exceed \fIsigsize\fR bytes in length. The length of the signature +should be written to \fI*siglen\fR. If \fIsig\fR is NULL then the maximum length of +the signature should be written to \fI*siglen\fR. +.PP +\&\fBOSSL_FUNC_signature_digest_sign()\fR implements a "one shot" digest sign operation +previously started through \fBOSSL_FUNC_signature_digest_sign_init()\fR. A previously +initialised signature context is passed in the \fIctx\fR parameter. The data to be +signed is in \fItbs\fR which should be \fItbslen\fR bytes long. Unless \fIsig\fR is NULL, +the signature should be written to the location pointed to by the \fIsig\fR +parameter and it should not exceed \fIsigsize\fR bytes in length. The length of the +signature should be written to \fI*siglen\fR. If \fIsig\fR is NULL then the maximum +length of the signature should be written to \fI*siglen\fR. +.SS "Digest Verify Functions" +.IX Subsection "Digest Verify Functions" +\&\fBOSSL_FUNC_signature_digest_verify_init()\fR initialises a context for verifying given a +provider side verification context in the \fIctx\fR parameter, and a pointer to a +provider key object in the \fIprovkey\fR parameter. +The \fIparams\fR, if not NULL, should be set on the context in a manner similar to +\&\fBOSSL_FUNC_signature_set_ctx_params()\fR and +\&\fBOSSL_FUNC_signature_set_ctx_md_params()\fR. +The key object should have been +previously generated, loaded or imported into the provider using the +key management (OSSL_OP_KEYMGMT) operation (see \fBprovider\-keymgmt\fR\|(7)). +The name of the digest to be used will be in the \fImdname\fR parameter. +.PP +\&\fBOSSL_FUNC_signature_digest_verify_update()\fR provides data to be verified in the \fIdata\fR +parameter which should be of length \fIdatalen\fR. A previously initialised +verification context is passed in the \fIctx\fR parameter. This function may be +called multiple times to cumulatively add data to be verified. +.PP +\&\fBOSSL_FUNC_signature_digest_verify_final()\fR finalises a verification operation previously +started through \fBOSSL_FUNC_signature_digest_verify_init()\fR and +\&\fBOSSL_FUNC_signature_digest_verify_update()\fR calls. Once finalised no more data will be +added through \fBOSSL_FUNC_signature_digest_verify_update()\fR. A previously initialised +verification context is passed in the \fIctx\fR parameter. The signature to be +verified is in \fIsig\fR which is \fIsiglen\fR bytes long. +.PP +\&\fBOSSL_FUNC_signature_digest_verify()\fR implements a "one shot" digest verify operation +previously started through \fBOSSL_FUNC_signature_digest_verify_init()\fR. A previously +initialised verification context is passed in the \fIctx\fR parameter. The data to be +verified is in \fItbs\fR which should be \fItbslen\fR bytes long. The signature to be +verified is in \fIsig\fR which is \fIsiglen\fR bytes long. +.SS "Signature parameters" +.IX Subsection "Signature parameters" +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by +the \fBOSSL_FUNC_signature_get_ctx_params()\fR and \fBOSSL_FUNC_signature_set_ctx_params()\fR functions. +.PP +\&\fBOSSL_FUNC_signature_get_ctx_params()\fR gets signature parameters associated with the +given provider side signature context \fIctx\fR and stored them in \fIparams\fR. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_signature_set_ctx_params()\fR sets the signature parameters associated with the +given provider side signature context \fIctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing NULL for \fIparams\fR should return true. +.PP +Common parameters currently recognised by built\-in signature algorithms are as +follows. +.IP """digest"" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_SIGNATURE_PARAM_DIGEST) " +Get or sets the name of the digest algorithm used for the input to the +signature functions. It is required in order to calculate the "algorithm\-id". +.IP """properties"" (\fBOSSL_SIGNATURE_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_SIGNATURE_PARAM_PROPERTIES) " +Sets the name of the property query associated with the "digest" algorithm. +NULL is used if this optional value is not set. +.PP +Note that when implementing a signature algorithm that gathers a full message, +like RSA\-SHA256, the "digest" and "properties" parameters should not be used. +For such implementations, it\*(Aqs acceptable to simply ignore them if they happen +to be passed in a call to \fBOSSL_FUNC_signature_set_ctx_params()\fR. For such +implementations, however, it is not acceptable to have them in the \fBOSSL_PARAM\fR +array that\*(Aqs returned by \fBOSSL_FUNC_signature_settable_ctx_params()\fR. +.IP """signature"" (\fBOSSL_SIGNATURE_PARAM_SIGNATURE\fR) " 4 +.IX Item """signature"" (OSSL_SIGNATURE_PARAM_SIGNATURE) " +Sets the signature to verify, specifically when +\&\fBOSSL_FUNC_signature_verify_message_final()\fR is used. +.IP """digest\-size"" (\fBOSSL_SIGNATURE_PARAM_DIGEST_SIZE\fR) " 4 +.IX Item """digest-size"" (OSSL_SIGNATURE_PARAM_DIGEST_SIZE) " +Gets or sets the output size of the digest algorithm used for the input to the +signature functions. +The length of the "digest\-size" parameter should not exceed that of a \fBsize_t\fR. +.IP """algorithm\-id"" (\fBOSSL_SIGNATURE_PARAM_ALGORITHM_ID\fR) " 4 +.IX Item """algorithm-id"" (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) " +Gets the DER\-encoded AlgorithmIdentifier for the signature operation. +This typically corresponds to the combination of a digest algorithm +with a purely asymmetric signature algorithm, such as SHA256WithECDSA. +.Sp +The \fBASN1_item_sign_ctx\fR\|(3) function relies on this operation and is used by +many other functions that sign ASN.1 structures such as X.509 certificates, +certificate requests, and CRLs, as well as OCSP, CMP, and CMS messages. +.IP """nonce\-type"" (\fBOSSL_SIGNATURE_PARAM_NONCE_TYPE\fR) " 4 +.IX Item """nonce-type"" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) " +Set this to 1 to use deterministic digital signature generation with +ECDSA or DSA, as defined in RFC 6979 (see Section 3.2 "Generation of +k"). In this case, the "digest" parameter must be explicitly set +(otherwise, deterministic nonce generation will fail). Before using +deterministic digital signature generation, please read RFC 6979 +Section 4 "Security Considerations". The default value for +"nonce\-type" is 0 and results in a random value being used for the +nonce \fBk\fR as defined in FIPS 186\-4 Section 6.3 "Secret Number +Generation". +.Sp +The FIPS provider does not support deterministic digital signature generation. +.IP """kat"" (\fBOSSL_SIGNATURE_PARAM_KAT\fR) " 4 +.IX Item """kat"" (OSSL_SIGNATURE_PARAM_KAT) " +Sets a flag to modify the sign operation to return an error if the initial +calculated signature is invalid. +In the normal mode of operation \- new random values are chosen until the +signature operation succeeds. +By default it retries until a signature is calculated. +Setting the value to 0 causes the sign operation to retry, +otherwise the sign operation is only tried once and returns whether or not it +was successful. +Known answer tests can be performed if the random generator is overridden to +supply known values that either pass or fail. +.PP +The following parameters are used by the OpenSSL FIPS provider: +.IP """fips\-indicator"" (\fBOSSL_SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling either the sign or verify final functions. It may +return 0 if either the "digest\-check", "key\-check", or "sign\-check" are set to 0. +.IP """verify\-message"" (\fBOSSL_SIGNATURE_PARAM_FIPS_VERIFY_MESSAGE\fR " 4 +.IX Item """verify-message"" (OSSL_SIGNATURE_PARAM_FIPS_VERIFY_MESSAGE " +A getter that returns 1 if a signature verification operation acted on +a raw message, or 0 if it verified a predigested message. A value of 0 +indicates likely non\-approved usage of the FIPS provider. This flag is +set when any signature verification initialisation function is called. +It is also set to 1 when any signing operation is performed to signify +compliance. See FIPS 140\-3 IG 2.4.B for further information. +.IP """key\-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK\fR) " 4 +.IX Item """key-check"" (OSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK) " +If required this parameter should be set early via an init function +(e.g. \fBOSSL_FUNC_signature_sign_init()\fR or \fBOSSL_FUNC_signature_verify_init()\fR). +The default value of 1 causes an error during the init if the key is not FIPS +approved (e.g. The key has a security strength of less than 112 bits). +Setting this to 0 will ignore the error and set the approved "indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.IP """digest\-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_DIGEST_CHECK\fR) " 4 +.IX Item """digest-check"" (OSSL_SIGNATURE_PARAM_FIPS_DIGEST_CHECK) " +If required this parameter should be set before the signature digest is set. +The default value of 1 causes an error when the digest is set if the digest is +not FIPS approved (e.g. SHA1 is used for signing). Setting this to 0 will ignore +the error and set the approved "fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.IP """sign\-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_SIGN_CHECK\fR) " 4 +.IX Item """sign-check"" (OSSL_SIGNATURE_PARAM_FIPS_SIGN_CHECK) " +If required this parameter should be set early via an init function. +The default value of 1 causes an error when a signing algorithm is used. (This +is triggered by deprecated signing algorithms). +Setting this to 0 will ignore the error and set the approved "fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" to +return 0. +.IP """sign\-x931\-pad\-check"" (\fBOSSL_SIGNATURE_PARAM_FIPS_SIGN_X931_PAD_CHECK\fR) " 4 +.IX Item """sign-x931-pad-check"" (OSSL_SIGNATURE_PARAM_FIPS_SIGN_X931_PAD_CHECK) " +If required this parameter should be set before the padding mode is set. +The default value of 1 causes an error if the padding mode is set to X9.31 padding +for a RSA signing operation. Setting this to 0 will ignore the error and set the +approved "fips\-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.PP +\&\fBOSSL_FUNC_signature_gettable_ctx_params()\fR and \fBOSSL_FUNC_signature_settable_ctx_params()\fR get a +constant \fBOSSL_PARAM\fR\|(3) array that describes the gettable and settable parameters, +i.e. parameters that can be used with \fBOSSL_FUNC_signature_get_ctx_params()\fR and +\&\fBOSSL_FUNC_signature_set_ctx_params()\fR respectively. +.SS "MD parameters" +.IX Subsection "MD parameters" +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by +the \fBOSSL_FUNC_signature_get_md_ctx_params()\fR and \fBOSSL_FUNC_signature_set_md_ctx_params()\fR +functions. +.PP +\&\fBOSSL_FUNC_signature_get_md_ctx_params()\fR gets digest parameters associated with the +given provider side digest signature context \fIctx\fR and stores them in \fIparams\fR. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_signature_set_ms_ctx_params()\fR sets the digest parameters associated with the +given provider side digest signature context \fIctx\fR to \fIparams\fR. +Any parameter settings are additional to any that were previously set. +Passing NULL for \fIparams\fR should return true. +.PP +Parameters currently recognised by built\-in signature algorithms are the same +as those for built\-in digest algorithms. See +"Digest Parameters" in \fBprovider\-digest\fR\|(7) for further information. +.PP +\&\fBOSSL_FUNC_signature_gettable_md_ctx_params()\fR and \fBOSSL_FUNC_signature_settable_md_ctx_params()\fR +get a constant \fBOSSL_PARAM\fR\|(3) array that describes the gettable and settable +digest parameters, i.e. parameters that can be used with +\&\fBOSSL_FUNC_signature_get_md_ctx_params()\fR and \fBOSSL_FUNC_signature_set_md_ctx_params()\fR +respectively. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_signature_newctx()\fR and \fBOSSL_FUNC_signature_dupctx()\fR should return the newly created +provider side signature context, or NULL on failure. +.PP +\&\fBOSSL_FUNC_signature_gettable_ctx_params()\fR, \fBOSSL_FUNC_signature_settable_ctx_params()\fR, +\&\fBOSSL_FUNC_signature_gettable_md_ctx_params()\fR and \fBOSSL_FUNC_signature_settable_md_ctx_params()\fR, +return the gettable or settable parameters in a constant \fBOSSL_PARAM\fR\|(3) array. +.PP +\&\fBOSSL_FUNC_signature_query_key_types()\fR should return a NULL\-terminated array of strings. +.PP +All verification functions should return 1 for success, +0 for a non\-matching signature, and a negative value for operation failure. +.PP +All other functions should return 1 for success +and 0 or a negative value for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), "Provider Functions" in \fBprovider\-base\fR\|(7), +\&\fBOSSL_PARAM\fR\|(3), \fBOSSL_DISPATCH\fR\|(3), \fBOSSL_ALGORITHM\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify\fR\|(3), \fBEVP_PKEY_verify_recover\fR\|(3), +\&\fBEVP_SIGNATURE_is_a\fR\|(3), \fBASN1_item_sign_ctx\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The provider SIGNATURE interface was introduced in OpenSSL 3.0. +.PP +The \fBOSSL_FUNC_signature_sign_message_init()\fR, \fBOSSL_FUNC_signature_sign_message_update()\fR, +\&\fBOSSL_FUNC_signature_sign_message_final()\fR, \fBOSSL_FUNC_signature_verify_message_init()\fR, +\&\fBOSSL_FUNC_signature_verify_message_update()\fR and \fBOSSL_FUNC_signature_verify_message_final()\fR +functions were added in OpenSSL 3.4. +.PP +The Signature Parameters "fips\-indicator", "key\-check" and "digest\-check" were added in +OpenSSL 3.4. +.PP +Deterministic digital signature generation for ECDSA was added to the FIPS provider in OpenSSL +3.6. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-skeymgmt.7 b/static/netbsd/man7/provider-skeymgmt.7 new file mode 100644 index 00000000..d5dd7cc5 --- /dev/null +++ b/static/netbsd/man7/provider-skeymgmt.7 @@ -0,0 +1,237 @@ +.\" $NetBSD: provider-skeymgmt.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-SKEYMGMT 7" +.TH PROVIDER-SKEYMGMT 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-skeymgmt \- The SKEYMGMT library <\-> provider functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& /* Key object destruction */ +\& void OSSL_FUNC_skeymgmt_free(void *keydata); +\& +\& /* Key object import and export functions */ +\& void *OSSL_FUNC_skeymgmt_import(void *provctx, int selection, +\& const OSSL_PARAM params[]); +\& int OSSL_FUNC_skeymgmt_export(void *keydata, int selection, +\& OSSL_CALLBACK *param_cb, void *cbarg); +\& void *OSSL_FUNC_skeymgmt_generate(void *provctx, +\& const OSSL_PARAM params[]); +\& const OSSL_PARAM *OSSL_FUNC_skeymgmt_gen_settable_params(void *provctx); +\& const OSSL_PARAM *OSSL_FUNC_skeymgmt_imp_settable_params(void *provctx); +\& const char *OSSL_FUNC_skeymgmt_get_key_id(void *keydata); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The SKEYMGMT operation doesn\*(Aqt have much public visibility in the OpenSSL +libraries, rather it is an internal operation that is designed to work +with operations that use opaque symmetric keys objects. +.PP +The SKEYMGMT operation shares knowledge with the operations it works with, +therefore the SKEYMGMT and the algorithms which use it must belong to the same +provider. The OpenSSL libraries will ensure that they do. +.PP +The primary responsibility of the SKEYMGMT operation is to hold the +provider side key data for the OpenSSL library EVP_SKEY structure. +.PP +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via +\&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider\*(Aqs +\&\fBprovider_query_operation()\fR function +(see "Provider Functions" in \fBprovider\-base\fR\|(7)). +.PP +All these "functions" have a corresponding function type definition +named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the +function pointer from a \fBOSSL_DISPATCH\fR\|(3) element named +\&\fBOSSL_FUNC_{name}\fR. +.PP +\&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as +macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 1 +\& OSSL_FUNC_skeymgmt_free OSSL_FUNC_SKEYMGMT_FREE +\& +\& OSSL_FUNC_skeymgmt_import OSSL_FUNC_SKEYMGMT_IMPORT +\& OSSL_FUNC_skeymgmt_export OSSL_FUNC_SKEYMGMT_EXPORT +\& +\& OSSL_FUNC_skeymgmt_generate OSSL_FUNC_SKEYMGMT_GENERATE +\& +\& OSSL_FUNC_skeymgmt_get_key_id OSSL_FUNC_SKEYMGMT_GET_KEY_ID +\& OSSL_FUNC_skeymgmt_imp_settable_params OSSL_FUNC_SKEYMGMT_IMP_SETTABLE_PARAMS +\& OSSL_FUNC_skeymgmt_gen_settable_params OSSL_FUNC_SKEYMGMT_GEN_SETTABLE_PARAMS +.Ve +.PP +The SKEYMGMT management is inspired by KEYMGMT but is simpler. +.SS "Key Objects" +.IX Subsection "Key Objects" +A key object is a collection of data for an symmetric key, and is +represented as \fIkeydata\fR in this manual. +.PP +The exact contents of a key object are defined by the provider, and it +is assumed that different operations in one and the same provider use +the exact same structure to represent this collection of data, so that +for example, a key object that has been created using the SKEYMGMT +interface can be passed as is to other algorithms from the same provider +operations, such as \fBOSSL_FUNC_mac_init_opaque()\fR (see +\&\fBprovider\-mac\fR\|(7)). +.PP +With the export SKEYMGMT function, it\*(Aqs possible to select a specific +subset of data to handle, governed by the bits in a \fIselection\fR +indicator. The bits are: +.IP \fBOSSL_SKEYMGMT_SELECT_SECRET_KEY\fR 4 +.IX Item "OSSL_SKEYMGMT_SELECT_SECRET_KEY" +Indicating that the secret key raw bytes in a key object should be +included. +.IP \fBOSSL_SKEYMGMT_SELECT_PARAMETERS\fR 4 +.IX Item "OSSL_SKEYMGMT_SELECT_PARAMETERS" +Indicating that the parameters in a key object should be +included. +.PP +Combined selector bits are also defined for easier use: +.IP \fBOSSL_SKEYMGMT_SELECT_ALL\fR 4 +.IX Item "OSSL_SKEYMGMT_SELECT_ALL" +Indicating that everything in a key object should be included. +.PP +The exact interpretation of those bits or how they combine is left to +each function where you can specify a selector. +.SS "Destructing Function" +.IX Subsection "Destructing Function" +\&\fBOSSL_FUNC_skeymgmt_free()\fR should free the passed \fIkeydata\fR. +.SS "Key Object Import and Export Functions" +.IX Subsection "Key Object Import and Export Functions" +\&\fBOSSL_FUNC_skeymgmt_import()\fR should import data into \fIkeydata\fR with values +taken from the \fBOSSL_PARAM\fR\|(3) array \fIparams\fR. It allocates the \fIkeydata\fR +object (there is no separate allocation function). +.PP +\&\fBOSSL_FUNC_skeymgmt_imp_settable_params()\fR returns a list of parameters that can +be provided to the \fBOSSL_FUNC_skeymgmt_import()\fR function. +.PP +\&\fBOSSL_FUNC_skeymgmt_export()\fR should extract values indicated by \fIselection\fR +from \fIkeydata\fR, create an \fBOSSL_PARAM\fR\|(3) array with them and call +\&\fIparam_cb\fR with that array as well as the given \fIcbarg\fR. +The passed \fBOSSL_PARAM\fR\|(3) array is transient and is freed upon the return from \fIparam_cb\fR. +.SS "Key Object Generation Functions" +.IX Subsection "Key Object Generation Functions" +\&\fBOSSL_FUNC_skeymgmt_generate()\fR creates a new key according to the values +taken from the \fBOSSL_PARAM\fR\|(3) array \fIparams\fR. It allocates the \fIkeydata\fR +object. +.PP +\&\fBOSSL_FUNC_skeymgmt_gen_settable_params()\fR returns a list of parameters that can +be provided to the \fBOSSL_FUNC_skeymgmt_generate()\fR function. +.SS "Key Object Information functions" +.IX Subsection "Key Object Information functions" +\&\fBOSSL_FUNC_skeymgmt_get_key_id()\fR returns a NUL\-terminated string identifying the +particular key. The returned string will be freed by a call to \fBEVP_SKEY_free()\fR +so callers need to copy it themselves if they want to preserve the value past +the key lifetime. The purpose of this function is providing a printable string +that can help users to access the specific key. The content of this string is +provider\-specific. +.SS "Common Import and Export Parameters" +.IX Subsection "Common Import and Export Parameters" +See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure. +.PP +Common information parameters currently recognised by built\-in +skeymgmt algorithms are as follows: +.IP """raw\-bytes"" (\fBSKEY_PARAM_RAW_BYTES\fR) " 4 +.IX Item """raw-bytes"" (SKEY_PARAM_RAW_BYTES) " +The value represents symmetric key as a byte array. +.IP """key\-length"" (\fBSKEY_PARAM_KEY_LENGTH\fR) " 4 +.IX Item """key-length"" (SKEY_PARAM_KEY_LENGTH) " +The value is the byte length of the given key. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_FUNC_skeymgmt_import()\fR and \fBOSSL_FUNC_skeymgmt_generate()\fR return a pointer +to an allocated object on success and NULL on error. +.PP +\&\fBOSSL_FUNC_skeymgmt_export()\fR returns 1 for success or 0 on error. +.PP +\&\fBOSSL_FUNC_skeymgmt_get_key_id()\fR returns a pointer to a 0\-terminated string or NULL. +.PP +\&\fBOSSL_FUNC_skeymgmt_gen_settable_params()\fR and \fBOSSL_FUNC_skeymgmt_imp_settable_params()\fR +return references to an array of \fBOSSL_PARAM\fR which can be NULL if there are +no settable parameters. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \fBEVP_SKEY\fR\|(3), \fBEVP_KEYMGMT\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The SKEYMGMT interface was introduced in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider-storemgmt.7 b/static/netbsd/man7/provider-storemgmt.7 new file mode 100644 index 00000000..154da798 --- /dev/null +++ b/static/netbsd/man7/provider-storemgmt.7 @@ -0,0 +1,274 @@ +.\" $NetBSD: provider-storemgmt.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER-STOREMGMT 7" +.TH PROVIDER-STOREMGMT 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider\-storemgmt \- The OSSL_STORE library <\-> provider functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& /* +\& * None of these are actual functions, but are displayed like this for +\& * the function signatures for functions that are offered as function +\& * pointers in OSSL_DISPATCH arrays. +\& */ +\& +\& void *OSSL_FUNC_store_open(void *provctx, const char *uri); +\& void *OSSL_FUNC_store_attach(void *provctx, OSSL_CORE_BIO *bio); +\& const OSSL_PARAM *store_settable_ctx_params(void *provctx); +\& int OSSL_FUNC_store_set_ctx_params(void *loaderctx, const OSSL_PARAM[]); +\& int OSSL_FUNC_store_load(void *loaderctx, +\& OSSL_CALLBACK *object_cb, void *object_cbarg, +\& OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg); +\& int OSSL_FUNC_store_eof(void *loaderctx); +\& int OSSL_FUNC_store_close(void *loaderctx); +\& +\& int OSSL_FUNC_store_export_object +\& (void *loaderctx, const void *objref, size_t objref_sz, +\& OSSL_CALLBACK *export_cb, void *export_cbarg); +\& void *OSSL_FUNC_store_open_ex(void *provctx, const char *uri, +\& const OSSL_PARAM params[], +\& OSSL_PASSPHRASE_CALLBACK *pw_cb, +\& void *pw_cbarg); +\& +\& int OSSL_FUNC_store_delete(void *provctx, const char *uri, +\& const OSSL_PARAM params[], +\& OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The STORE operation is the provider side of the \fBossl_store\fR\|(7) API. +.PP +The primary responsibility of the STORE operation is to load all sorts +of objects from a container indicated by URI. These objects are given +to the OpenSSL library in provider\-native object abstraction form (see +\&\fBprovider\-object\fR\|(7)). The OpenSSL library is then responsible for +passing on that abstraction to suitable provided functions. +.PP +Examples of functions that the OpenSSL library can pass the abstraction to +include \fBOSSL_FUNC_keymgmt_load()\fR (\fBprovider\-keymgmt\fR\|(7)), +\&\fBOSSL_FUNC_store_export_object()\fR (which exports the object in parameterized +form). +.PP +All "functions" mentioned here are passed as function pointers between +\&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via +\&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider\*(Aqs +\&\fBprovider_query_operation()\fR function +(see "Provider Functions" in \fBprovider\-base\fR\|(7)). +.PP +All these "functions" have a corresponding function type definition named +\&\fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the function pointer +from a \fBOSSL_DISPATCH\fR\|(3) element named \fBOSSL_get_{name}\fR. +For example, the "function" \fBOSSL_FUNC_store_attach()\fR has these: +.PP +.Vb 4 +\& typedef void *(OSSL_FUNC_store_attach_fn)(void *provctx, +\& OSSL_CORE_BIO * bio); +\& static ossl_inline OSSL_FUNC_store_attach_fn +\& OSSL_FUNC_store_attach(const OSSL_DISPATCH *opf); +.Ve +.PP +\&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as macros +in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: +.PP +.Vb 10 +\& OSSL_FUNC_store_open OSSL_FUNC_STORE_OPEN +\& OSSL_FUNC_store_attach OSSL_FUNC_STORE_ATTACH +\& OSSL_FUNC_store_settable_ctx_params OSSL_FUNC_STORE_SETTABLE_CTX_PARAMS +\& OSSL_FUNC_store_set_ctx_params OSSL_FUNC_STORE_SET_CTX_PARAMS +\& OSSL_FUNC_store_load OSSL_FUNC_STORE_LOAD +\& OSSL_FUNC_store_eof OSSL_FUNC_STORE_EOF +\& OSSL_FUNC_store_close OSSL_FUNC_STORE_CLOSE +\& OSSL_FUNC_store_export_object OSSL_FUNC_STORE_EXPORT_OBJECT +\& OSSL_FUNC_store_delete OSSL_FUNC_STORE_DELETE +\& OSSL_FUNC_store_open_ex OSSL_FUNC_STORE_OPEN_EX +.Ve +.SS Functions +.IX Subsection "Functions" +\&\fBOSSL_FUNC_store_open()\fR should create a provider side context with data based +on the input \fIuri\fR. The implementation is entirely responsible for the +interpretation of the URI. +.PP +\&\fBOSSL_FUNC_store_attach()\fR should create a provider side context with the core +\&\fBBIO\fR \fIbio\fR attached. This is an alternative to using a URI to find storage, +supporting \fBOSSL_STORE_attach\fR\|(3). +.PP +\&\fBOSSL_FUNC_store_settable_ctx_params()\fR should return a constant array of +descriptor \fBOSSL_PARAM\fR\|(3), for parameters that \fBOSSL_FUNC_store_set_ctx_params()\fR +can handle. +.PP +\&\fBOSSL_FUNC_store_set_ctx_params()\fR should set additional parameters, such as what +kind of data to expect, search criteria, and so on. More on those below, in +"Load Parameters". Whether unrecognised parameters are an error or simply +ignored is at the implementation\*(Aqs discretion. +Passing NULL for \fIparams\fR should return true. +.PP +\&\fBOSSL_FUNC_store_load()\fR loads the next object from the URI opened by +\&\fBOSSL_FUNC_store_open()\fR, creates an object abstraction for it (see +\&\fBprovider\-object\fR\|(7)), and calls \fIobject_cb\fR with it as well as +\&\fIobject_cbarg\fR. \fIobject_cb\fR will then interpret the object abstraction +and do what it can to wrap it or decode it into an OpenSSL structure. In +case a passphrase needs to be prompted to unlock an object, \fIpw_cb\fR should +be called. +.PP +\&\fBOSSL_FUNC_store_eof()\fR indicates if the end of the set of objects from the +URI has been reached. When that happens, there\*(Aqs no point trying to do any +further loading. +.PP +\&\fBOSSL_FUNC_store_close()\fR frees the provider side context \fIctx\fR. +.PP +When a provider\-native object is created by a store manager it would be unsuitable +for direct use with a foreign provider. The export function allows for +exporting the object to that foreign provider if the foreign provider +supports the type of the object and provides an import function. +.PP +\&\fBOSSL_FUNC_store_export_object()\fR should export the object of size \fIobjref_sz\fR +referenced by \fIobjref\fR as an \fBOSSL_PARAM\fR\|(3) array and pass that to the +\&\fIexport_cb\fR as well as the given \fIexport_cbarg\fR. +.PP +\&\fBOSSL_FUNC_store_delete()\fR deletes the object identified by the \fIuri\fR. The +implementation is entirely responsible for the interpretation of the URI. In +case a passphrase needs to be prompted to remove an object, \fIpw_cb\fR should be +called. +.PP +\&\fBOSSL_FUNC_store_open_ex()\fR is an extended variant of \fBOSSL_FUNC_store_open()\fR. If +the provider does not implement this function the code internally falls back to +use the original \fBOSSL_FUNC_store_open()\fR. +This variant additionally accepts an \fBOSSL_PARAM\fR\|(3) object and a \fIpw_cb\fR +callback that can be used to request a passphrase in cases where the whole +store needs to be unlocked before performing any load operation. +.SS "Load Parameters" +.IX Subsection "Load Parameters" +.IP """expect"" (\fBOSSL_STORE_PARAM_EXPECT\fR) " 4 +.IX Item """expect"" (OSSL_STORE_PARAM_EXPECT) " +Is a hint of what type of data the OpenSSL library expects to get. +This is only useful for optimization, as the library will check that the +object types match the expectation too. +.Sp +The number that can be given through this parameter is found in +\&\fI\fR, with the macros having names starting with +\&\f(CW\*(C`OSSL_STORE_INFO_\*(C'\fR. These are further described in +"SUPPORTED OBJECTS" in \fBOSSL_STORE_INFO\fR\|(3). +.IP """subject"" (\fBOSSL_STORE_PARAM_SUBJECT\fR) " 4 +.IX Item """subject"" (OSSL_STORE_PARAM_SUBJECT) " +Indicates that the caller wants to search for an object with the given +subject associated. This can be used to select specific certificates +by subject. +.Sp +The contents of the octet string is expected to be in DER form. +.IP """issuer"" (\fBOSSL_STORE_PARAM_ISSUER\fR) " 4 +.IX Item """issuer"" (OSSL_STORE_PARAM_ISSUER) " +Indicates that the caller wants to search for an object with the given +issuer associated. This can be used to select specific certificates +by issuer. +.Sp +The contents of the octet string is expected to be in DER form. +.IP """serial"" (\fBOSSL_STORE_PARAM_SERIAL\fR) " 4 +.IX Item """serial"" (OSSL_STORE_PARAM_SERIAL) " +Indicates that the caller wants to search for an object with the given +serial number associated. +.IP """digest"" (\fBOSSL_STORE_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_STORE_PARAM_DIGEST) " +.PD 0 +.IP """fingerprint"" (\fBOSSL_STORE_PARAM_FINGERPRINT\fR) " 4 +.IX Item """fingerprint"" (OSSL_STORE_PARAM_FINGERPRINT) " +.PD +Indicates that the caller wants to search for an object with the given +fingerprint, computed with the given digest. +.IP """alias"" (\fBOSSL_STORE_PARAM_ALIAS\fR) " 4 +.IX Item """alias"" (OSSL_STORE_PARAM_ALIAS) " +Indicates that the caller wants to search for an object with the given +alias (some call it a "friendly name"). +.IP """properties"" (\fBOSSL_STORE_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_STORE_PARAM_PROPERTIES) " +Property string to use when querying for algorithms such as the \fBOSSL_DECODER\fR +decoder implementations. +.IP """input\-type"" (\fBOSSL_STORE_PARAM_INPUT_TYPE\fR) " 4 +.IX Item """input-type"" (OSSL_STORE_PARAM_INPUT_TYPE) " +Type of the input format as a hint to use when decoding the objects in the +store. +.PP +Several of these search criteria may be combined. For example, to +search for a certificate by issuer+serial, both the "issuer" and the +"serial" parameters will be given. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The STORE interface was introduced in OpenSSL 3.0. +.PP +\&\fBOSSL_FUNC_store_delete()\fR callback was added in OpenSSL 3.2 +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/provider.7 b/static/netbsd/man7/provider.7 new file mode 100644 index 00000000..e0d57ac7 --- /dev/null +++ b/static/netbsd/man7/provider.7 @@ -0,0 +1,327 @@ +.\" $NetBSD: provider.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROVIDER 7" +.TH PROVIDER 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +provider \- OpenSSL operation implementation providers +.SH SYNOPSIS +.IX Header "SYNOPSIS" +#include +.SH DESCRIPTION +.IX Header "DESCRIPTION" +.SS General +.IX Subsection "General" +This page contains information useful to provider authors. +.PP +A \fIprovider\fR, in OpenSSL terms, is a unit of code that provides one +or more implementations for various operations for diverse algorithms +that one might want to perform. +.PP +An \fIoperation\fR is something one wants to do, such as encryption and +decryption, key derivation, MAC calculation, signing and verification, +etc. +.PP +An \fIalgorithm\fR is a named method to perform an operation. +Very often, the algorithms revolve around cryptographic operations, +but may also revolve around other types of operation, such as managing +certain types of objects. +.PP +See \fBcrypto\fR\|(7) for further details. +.SS Provider +.IX Subsection "Provider" +A \fIprovider\fR offers an initialization function, as a set of base +functions in the form of an \fBOSSL_DISPATCH\fR\|(3) array, and by extension, +a set of \fBOSSL_ALGORITHM\fR\|(3)s (see \fBopenssl\-core.h\fR\|(7)). +It may be a dynamically loadable module, or may be built\-in, in +OpenSSL libraries or in the application. +If it\*(Aqs a dynamically loadable module, the initialization function +must be named \f(CW\*(C`OSSL_provider_init\*(C'\fR and must be exported. +If it\*(Aqs built\-in, the initialization function may have any name. +.PP +The initialization function must have the following signature: +.PP +.Vb 3 +\& int NAME(const OSSL_CORE_HANDLE *handle, +\& const OSSL_DISPATCH *in, const OSSL_DISPATCH **out, +\& void **provctx); +.Ve +.PP +\&\fIhandle\fR is the OpenSSL library object for the provider, and works +as a handle for everything the OpenSSL libraries need to know about +the provider. +For the provider itself, it is passed to some of the functions given in the +dispatch array \fIin\fR. +.PP +\&\fIin\fR is a dispatch array of base functions offered by the OpenSSL +libraries, and the available functions are further described in +\&\fBprovider\-base\fR\|(7). +.PP +\&\fI*out\fR must be assigned a dispatch array of base functions that the +provider offers to the OpenSSL libraries. +The functions that may be offered are further described in +\&\fBprovider\-base\fR\|(7), and they are the central means of communication +between the OpenSSL libraries and the provider. +.PP +\&\fI*provctx\fR should be assigned a provider specific context to allow +the provider multiple simultaneous uses. +This pointer will be passed to various operation functions offered by +the provider. +.PP +Note that the provider will not be made available for applications to use until +the initialization function has completed and returned successfully. +.PP +One of the functions the provider offers to the OpenSSL libraries is +the central mechanism for the OpenSSL libraries to get access to +operation implementations for diverse algorithms. +Its referred to with the number \fBOSSL_FUNC_PROVIDER_QUERY_OPERATION\fR +and has the following signature: +.PP +.Vb 3 +\& const OSSL_ALGORITHM *provider_query_operation(void *provctx, +\& int operation_id, +\& const int *no_store); +.Ve +.PP +\&\fIprovctx\fR is the provider specific context that was passed back by +the initialization function. +.PP +\&\fIoperation_id\fR is an operation identity (see "Operations" below). +.PP +\&\fIno_store\fR is a flag back to the OpenSSL libraries which, when +nonzero, signifies that the OpenSSL libraries will not store a +reference to the returned data in their internal store of +implementations. +.PP +The returned \fBOSSL_ALGORITHM\fR\|(3) is the foundation of any OpenSSL +library API that uses providers for their implementation, most +commonly in the \fIfetching\fR type of functions +(see "ALGORITHM FETCHING" in \fBcrypto\fR\|(7)). +.SS Operations +.IX Subsection "Operations" +Operations are referred to with numbers, via macros with names +starting with \f(CW\*(C`OSSL_OP_\*(C'\fR. +.PP +With each operation comes a set of defined function types that a +provider may or may not offer, depending on its needs. +.PP +Currently available operations are: +.IP Digests 4 +.IX Item "Digests" +In the OpenSSL libraries, the corresponding method object is +\&\fBEVP_MD\fR. +The number for this operation is \fBOSSL_OP_DIGEST\fR. +The functions the provider can offer are described in +\&\fBprovider\-digest\fR\|(7). +.IP "Symmetric ciphers" 4 +.IX Item "Symmetric ciphers" +In the OpenSSL libraries, the corresponding method object is +\&\fBEVP_CIPHER\fR. +The number for this operation is \fBOSSL_OP_CIPHER\fR. +The functions the provider can offer are described in +\&\fBprovider\-cipher\fR\|(7). +.IP "Message Authentication Code (MAC)" 4 +.IX Item "Message Authentication Code (MAC)" +In the OpenSSL libraries, the corresponding method object is +\&\fBEVP_MAC\fR. +The number for this operation is \fBOSSL_OP_MAC\fR. +The functions the provider can offer are described in +\&\fBprovider\-mac\fR\|(7). +.IP "Key Derivation Function (KDF)" 4 +.IX Item "Key Derivation Function (KDF)" +In the OpenSSL libraries, the corresponding method object is +\&\fBEVP_KDF\fR. +The number for this operation is \fBOSSL_OP_KDF\fR. +The functions the provider can offer are described in +\&\fBprovider\-kdf\fR\|(7). +.IP "Key Exchange" 4 +.IX Item "Key Exchange" +In the OpenSSL libraries, the corresponding method object is +\&\fBEVP_KEYEXCH\fR. +The number for this operation is \fBOSSL_OP_KEYEXCH\fR. +The functions the provider can offer are described in +\&\fBprovider\-keyexch\fR\|(7). +.IP "Asymmetric Ciphers" 4 +.IX Item "Asymmetric Ciphers" +In the OpenSSL libraries, the corresponding method object is +\&\fBEVP_ASYM_CIPHER\fR. +The number for this operation is \fBOSSL_OP_ASYM_CIPHER\fR. +The functions the provider can offer are described in +\&\fBprovider\-asym_cipher\fR\|(7). +.IP "Asymmetric Key Encapsulation" 4 +.IX Item "Asymmetric Key Encapsulation" +In the OpenSSL libraries, the corresponding method object is \fBEVP_KEM\fR. +The number for this operation is \fBOSSL_OP_KEM\fR. +The functions the provider can offer are described in \fBprovider\-kem\fR\|(7). +.IP Encoding 4 +.IX Item "Encoding" +In the OpenSSL libraries, the corresponding method object is +\&\fBOSSL_ENCODER\fR. +The number for this operation is \fBOSSL_OP_ENCODER\fR. +The functions the provider can offer are described in +\&\fBprovider\-encoder\fR\|(7). +.IP Decoding 4 +.IX Item "Decoding" +In the OpenSSL libraries, the corresponding method object is +\&\fBOSSL_DECODER\fR. +The number for this operation is \fBOSSL_OP_DECODER\fR. +The functions the provider can offer are described in +\&\fBprovider\-decoder\fR\|(7). +.IP "Random Number Generation" 4 +.IX Item "Random Number Generation" +The number for this operation is \fBOSSL_OP_RAND\fR. +The functions the provider can offer for random number generation are described +in \fBprovider\-rand\fR\|(7). +.IP "Key Management" 4 +.IX Item "Key Management" +The number for this operation is \fBOSSL_OP_KEYMGMT\fR. +The functions the provider can offer for key management are described in +\&\fBprovider\-keymgmt\fR\|(7). +.IP "Signing and Signature Verification" 4 +.IX Item "Signing and Signature Verification" +The number for this operation is \fBOSSL_OP_SIGNATURE\fR. +The functions the provider can offer for digital signatures are described in +\&\fBprovider\-signature\fR\|(7). +.IP "Store Management" 4 +.IX Item "Store Management" +The number for this operation is \fBOSSL_OP_STORE\fR. +The functions the provider can offer for store management are described in +\&\fBprovider\-storemgmt\fR\|(7). +.PP +\fIAlgorithm naming\fR +.IX Subsection "Algorithm naming" +.PP +Algorithm names are case insensitive. Any particular algorithm can have multiple +aliases associated with it. The canonical OpenSSL naming scheme follows this +format: +.PP +ALGNAME[VERSION?][\-SUBNAME[VERSION?]?][\-SIZE?][\-MODE?] +.PP +VERSION is only present if there are multiple versions of an algorithm (e.g. +MD2, MD4, MD5). It may be omitted if there is only one version. +.PP +SUBNAME may be present where multiple algorithms are combined together, +e.g. MD5\-SHA1. +.PP +SIZE is only present if multiple versions of an algorithm exist with different +sizes (e.g. AES\-128\-CBC, AES\-256\-CBC) +.PP +MODE is only present where applicable. +.PP +Other aliases may exist for example where standards bodies or common practice +use alternative names or names that OpenSSL has used historically. +.PP +\fIProvider dependencies\fR +.IX Subsection "Provider dependencies" +.PP +Providers may depend for their proper operation on the availability of +(functionality implemented in) other providers. As there is no mechanism to +express such dependencies towards the OpenSSL core, provider authors must +take care that such dependencies are either completely avoided or made visible +to users, e.g., by documentation and/or defensive programming, e.g., +outputting error messages if required external dependencies are not available, +e.g., when no provider implementing the required functionality has been +activated. In particular, provider initialization should not depend on other +providers already having been initialized. +.PP +\fINote on naming clashes\fR +.IX Subsection "Note on naming clashes" +.PP +It is possible to register the same algorithm name from within different +providers. Users should note that if no property query is specified, or +more than one implementation matches the property query then it is +unspecified which implementation of a particular algorithm will be returned. +Such naming clashes may also occur if algorithms only differ in +capitalization as "Algorithm naming" is case insensitive. +.SH "OPENSSL PROVIDERS" +.IX Header "OPENSSL PROVIDERS" +OpenSSL provides a number of its own providers. These are the default, base, +fips, legacy and null providers. See \fBcrypto\fR\|(7) for an overview of these +providers. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_DigestInit_ex\fR\|(3), \fBEVP_EncryptInit_ex\fR\|(3), +\&\fBOSSL_LIB_CTX\fR\|(3), +\&\fBEVP_set_default_properties\fR\|(3), +\&\fBEVP_MD_fetch\fR\|(3), +\&\fBEVP_CIPHER_fetch\fR\|(3), +\&\fBEVP_KEYMGMT_fetch\fR\|(3), +\&\fBopenssl\-core.h\fR\|(7), +\&\fBprovider\-base\fR\|(7), +\&\fBprovider\-digest\fR\|(7), +\&\fBprovider\-cipher\fR\|(7), +\&\fBprovider\-keyexch\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The concept of providers and everything surrounding them was +introduced in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/proxy-certificates.7 b/static/netbsd/man7/proxy-certificates.7 new file mode 100644 index 00000000..750f216f --- /dev/null +++ b/static/netbsd/man7/proxy-certificates.7 @@ -0,0 +1,403 @@ +.\" $NetBSD: proxy-certificates.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PROXY-CERTIFICATES 7" +.TH PROXY-CERTIFICATES 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +proxy\-certificates \- Proxy certificates in OpenSSL +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Proxy certificates are defined in RFC 3820. They are used to +extend rights to some other entity (a computer process, typically, or +sometimes to the user itself). This allows the entity to perform +operations on behalf of the owner of the EE (End Entity) certificate. +.PP +The requirements for a valid proxy certificate are: +.IP \(bu 4 +They are issued by an End Entity, either a normal EE certificate, or +another proxy certificate. +.IP \(bu 4 +They must not have the \fBsubjectAltName\fR or \fBissuerAltName\fR +extensions. +.IP \(bu 4 +They must have the \fBproxyCertInfo\fR extension. +.IP \(bu 4 +They must have the subject of their issuer, with one \fBcommonName\fR +added. +.SS "Enabling proxy certificate verification" +.IX Subsection "Enabling proxy certificate verification" +OpenSSL expects applications that want to use proxy certificates to be +specially aware of them, and make that explicit. This is done by +setting an X509 verification flag: +.PP +.Vb 1 +\& X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS); +.Ve +.PP +or +.PP +.Vb 1 +\& X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_ALLOW_PROXY_CERTS); +.Ve +.PP +See "NOTES" for a discussion on this requirement. +.SS "Creating proxy certificates" +.IX Subsection "Creating proxy certificates" +Creating proxy certificates can be done using the \fBopenssl\-x509\fR\|(1) +command, with some extra extensions: +.PP +.Vb 7 +\& [ proxy ] +\& # A proxy certificate MUST NEVER be a CA certificate. +\& basicConstraints = CA:FALSE +\& # Usual authority key ID +\& authorityKeyIdentifier = keyid,issuer:always +\& # The extension which marks this certificate as a proxy +\& proxyCertInfo = critical,language:id\-ppl\-anyLanguage,pathlen:1,policy:text:AB +.Ve +.PP +It\*(Aqs also possible to specify the proxy extension in a separate section: +.PP +.Vb 1 +\& proxyCertInfo = critical,@proxy_ext +\& +\& [ proxy_ext ] +\& language = id\-ppl\-anyLanguage +\& pathlen = 0 +\& policy = text:BC +.Ve +.PP +The policy value has a specific syntax, \fIsyntag\fR:\fIstring\fR, where the +\&\fIsyntag\fR determines what will be done with the string. The following +\&\fIsyntag\fRs are recognised: +.IP \fBtext\fR 4 +.IX Item "text" +indicates that the string is a byte sequence, without any encoding: +.Sp +.Vb 1 +\& policy=text:räksmörgås +.Ve +.IP \fBhex\fR 4 +.IX Item "hex" +indicates the string is encoded hexadecimal encoded binary data, with +colons between each byte (every second hex digit): +.Sp +.Vb 1 +\& policy=hex:72:E4:6B:73:6D:F6:72:67:E5:73 +.Ve +.IP \fBfile\fR 4 +.IX Item "file" +indicates that the text of the policy should be taken from a file. +The string is then a filename. This is useful for policies that are +more than a few lines, such as XML or other markup. +.PP +Note that the proxy policy value is what determines the rights granted +to the process during the proxy certificate, and it is up to the +application to interpret and combine these policies.> +.PP +With a proxy extension, creating a proxy certificate is a matter of +two commands: +.PP +.Vb 3 +\& openssl req \-new \-config proxy.cnf \e +\& \-out proxy.req \-keyout proxy.key \e +\& \-subj "/DC=org/DC=openssl/DC=users/CN=proxy" +\& +\& openssl x509 \-req \-CAcreateserial \-in proxy.req \-out proxy.crt \e +\& \-CA user.crt \-CAkey user.key \-days 7 \e +\& \-extfile proxy.cnf \-extensions proxy +.Ve +.PP +You can also create a proxy certificate using another proxy +certificate as issuer. Note that this example uses a different +configuration section for the proxy extensions: +.PP +.Vb 3 +\& openssl req \-new \-config proxy.cnf \e +\& \-out proxy2.req \-keyout proxy2.key \e +\& \-subj "/DC=org/DC=openssl/DC=users/CN=proxy/CN=proxy 2" +\& +\& openssl x509 \-req \-CAcreateserial \-in proxy2.req \-out proxy2.crt \e +\& \-CA proxy.crt \-CAkey proxy.key \-days 7 \e +\& \-extfile proxy.cnf \-extensions proxy_2 +.Ve +.SS "Using proxy certs in applications" +.IX Subsection "Using proxy certs in applications" +To interpret proxy policies, the application would normally start with +some default rights (perhaps none at all), then compute the resulting +rights by checking the rights against the chain of proxy certificates, +user certificate and CA certificates. +.PP +The complicated part is figuring out how to pass data between your +application and the certificate validation procedure. +.PP +The following ingredients are needed for such processing: +.IP \(bu 4 +a callback function that will be called for every certificate being +validated. The callback is called several times for each certificate, +so you must be careful to do the proxy policy interpretation at the +right time. You also need to fill in the defaults when the EE +certificate is checked. +.IP \(bu 4 +a data structure that is shared between your application code and the +callback. +.IP \(bu 4 +a wrapper function that sets it all up. +.IP \(bu 4 +an ex_data index function that creates an index into the generic +ex_data store that is attached to an X509 validation context. +.PP +The following skeleton code can be used as a starting point: +.PP +.Vb 4 +\& #include +\& #include +\& #include +\& #include +\& +\& #define total_rights 25 +\& +\& /* +\& * In this example, I will use a view of granted rights as a bit +\& * array, one bit for each possible right. +\& */ +\& typedef struct your_rights { +\& unsigned char rights[(total_rights + 7) / 8]; +\& } YOUR_RIGHTS; +\& +\& /* +\& * The following procedure will create an index for the ex_data +\& * store in the X509 validation context the first time it\*(Aqs +\& * called. Subsequent calls will return the same index. +\& */ +\& static int get_proxy_auth_ex_data_idx(X509_STORE_CTX *ctx) +\& { +\& static volatile int idx = \-1; +\& +\& if (idx < 0) { +\& X509_STORE_lock(X509_STORE_CTX_get0_store(ctx)); +\& if (idx < 0) { +\& idx = X509_STORE_CTX_get_ex_new_index(0, +\& "for verify callback", +\& NULL,NULL,NULL); +\& } +\& X509_STORE_unlock(X509_STORE_CTX_get0_store(ctx)); +\& } +\& return idx; +\& } +\& +\& /* Callback to be given to the X509 validation procedure. */ +\& static int verify_callback(int ok, X509_STORE_CTX *ctx) +\& { +\& if (ok == 1) { +\& /* +\& * It\*(Aqs REALLY important you keep the proxy policy check +\& * within this section. It\*(Aqs important to know that when +\& * ok is 1, the certificates are checked from top to +\& * bottom. You get the CA root first, followed by the +\& * possible chain of intermediate CAs, followed by the EE +\& * certificate, followed by the possible proxy +\& * certificates. +\& */ +\& X509 *xs = X509_STORE_CTX_get_current_cert(ctx); +\& +\& if (X509_get_extension_flags(xs) & EXFLAG_PROXY) { +\& YOUR_RIGHTS *rights = +\& (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx, +\& get_proxy_auth_ex_data_idx(ctx)); +\& PROXY_CERT_INFO_EXTENSION *pci = +\& X509_get_ext_d2i(xs, NID_proxyCertInfo, NULL, NULL); +\& +\& switch (OBJ_obj2nid(pci\->proxyPolicy\->policyLanguage)) { +\& case NID_Independent: +\& /* +\& * Do whatever you need to grant explicit rights +\& * to this particular proxy certificate, usually +\& * by pulling them from some database. If there +\& * are none to be found, clear all rights (making +\& * this and any subsequent proxy certificate void +\& * of any rights). +\& */ +\& memset(rights\->rights, 0, sizeof(rights\->rights)); +\& break; +\& case NID_id_ppl_inheritAll: +\& /* +\& * This is basically a NOP, we simply let the +\& * current rights stand as they are. +\& */ +\& break; +\& default: +\& /* +\& * This is usually the most complex section of +\& * code. You really do whatever you want as long +\& * as you follow RFC 3820. In the example we use +\& * here, the simplest thing to do is to build +\& * another, temporary bit array and fill it with +\& * the rights granted by the current proxy +\& * certificate, then use it as a mask on the +\& * accumulated rights bit array, and voilà, you +\& * now have a new accumulated rights bit array. +\& */ +\& { +\& int i; +\& YOUR_RIGHTS tmp_rights; +\& memset(tmp_rights.rights, 0, +\& sizeof(tmp_rights.rights)); +\& +\& /* +\& * process_rights() is supposed to be a +\& * procedure that takes a string and its +\& * length, interprets it and sets the bits +\& * in the YOUR_RIGHTS pointed at by the +\& * third argument. +\& */ +\& process_rights((char *) pci\->proxyPolicy\->policy\->data, +\& pci\->proxyPolicy\->policy\->length, +\& &tmp_rights); +\& +\& for(i = 0; i < total_rights / 8; i++) +\& rights\->rights[i] &= tmp_rights.rights[i]; +\& } +\& break; +\& } +\& PROXY_CERT_INFO_EXTENSION_free(pci); +\& } else if (!(X509_get_extension_flags(xs) & EXFLAG_CA)) { +\& /* We have an EE certificate, let\*(Aqs use it to set default! */ +\& YOUR_RIGHTS *rights = +\& (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx, +\& get_proxy_auth_ex_data_idx(ctx)); +\& +\& /* +\& * The following procedure finds out what rights the +\& * owner of the current certificate has, and sets them +\& * in the YOUR_RIGHTS structure pointed at by the +\& * second argument. +\& */ +\& set_default_rights(xs, rights); +\& } +\& } +\& return ok; +\& } +\& +\& static int my_X509_verify_cert(X509_STORE_CTX *ctx, +\& YOUR_RIGHTS *needed_rights) +\& { +\& int ok; +\& int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) = +\& X509_STORE_CTX_get_verify_cb(ctx); +\& YOUR_RIGHTS rights; +\& +\& X509_STORE_CTX_set_verify_cb(ctx, verify_callback); +\& X509_STORE_CTX_set_ex_data(ctx, get_proxy_auth_ex_data_idx(ctx), +\& &rights); +\& X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS); +\& ok = X509_verify_cert(ctx); +\& +\& if (ok == 1) { +\& ok = check_needed_rights(rights, needed_rights); +\& } +\& +\& X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb); +\& +\& return ok; +\& } +.Ve +.PP +If you use SSL or TLS, you can easily set up a callback to have the +certificates checked properly, using the code above: +.PP +.Vb 2 +\& SSL_CTX_set_cert_verify_callback(s_ctx, my_X509_verify_cert, +\& &needed_rights); +.Ve +.SH NOTES +.IX Header "NOTES" +To this date, it seems that proxy certificates have only been used in +environments that are aware of them, and no one seems to have +investigated how they can be used or misused outside of such an +environment. +.PP +For that reason, OpenSSL requires that applications aware of proxy +certificates must also make that explicit. +.PP +\&\fBsubjectAltName\fR and \fBissuerAltName\fR are forbidden in proxy +certificates, and this is enforced in OpenSSL. The subject must be +the same as the issuer, with one commonName added on. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_STORE_CTX_set_flags\fR\|(3), +\&\fBX509_STORE_CTX_set_verify_cb\fR\|(3), +\&\fBX509_VERIFY_PARAM_set_flags\fR\|(3), +\&\fBSSL_CTX_set_cert_verify_callback\fR\|(3), +\&\fBopenssl\-req\fR\|(1), \fBopenssl\-x509\fR\|(1), +RFC 3820 +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/re_format.7 b/static/netbsd/man7/re_format.7 new file mode 100644 index 00000000..0c092871 --- /dev/null +++ b/static/netbsd/man7/re_format.7 @@ -0,0 +1,756 @@ +.\" $OpenBSD: re_format.7,v 1.14 2007/05/31 19:19:30 jmc Exp $ +.\" +.\" Copyright (c) 1997, Phillip F Knaack. All rights reserved. +.\" +.\" Copyright (c) 1992, 1993, 1994 Henry Spencer. +.\" Copyright (c) 1992, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Henry Spencer. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)re_format.7 8.3 (Berkeley) 3/20/94 +.\" +.Dd $Mdocdate: May 31 2007 $ +.Dt RE_FORMAT 7 +.Os +.Sh NAME +.Nm re_format +.Nd POSIX regular expressions +.Sh DESCRIPTION +Regular expressions (REs), +as defined in +.St -p1003.1-2004 , +come in two forms: +basic regular expressions +(BREs) +and extended regular expressions +(EREs). +Both forms of regular expressions are supported +by the interfaces described in +.Xr regex 3 . +Applications dealing with regular expressions +may use one or the other form +(or indeed both). +For example, +.Xr ed 1 +uses BREs, +whilst +.Xr egrep 1 +talks EREs. +Consult the manual page for the specific application to find out which +it uses. +.Pp +POSIX leaves some aspects of RE syntax and semantics open; +.Sq ** +marks decisions on these aspects that +may not be fully portable to other POSIX implementations. +.Pp +This manual page first describes regular expressions in general, +specifically extended regular expressions, +and then discusses differences between them and basic regular expressions. +.Sh EXTENDED REGULAR EXPRESSIONS +An ERE is one** or more non-empty** +.Em branches , +separated by +.Sq \*(Ba . +It matches anything that matches one of the branches. +.Pp +A branch is one** or more +.Em pieces , +concatenated. +It matches a match for the first, followed by a match for the second, etc. +.Pp +A piece is an +.Em atom +possibly followed by a single** +.Sq * , +.Sq + , +.Sq ?\& , +or +.Em bound . +An atom followed by +.Sq * +matches a sequence of 0 or more matches of the atom. +An atom followed by +.Sq + +matches a sequence of 1 or more matches of the atom. +An atom followed by +.Sq ?\& +matches a sequence of 0 or 1 matches of the atom. +.Pp +A bound is +.Sq { +followed by an unsigned decimal integer, +possibly followed by +.Sq ,\& +possibly followed by another unsigned decimal integer, +always followed by +.Sq } . +The integers must lie between 0 and +.Dv RE_DUP_MAX +(255**) inclusive, +and if there are two of them, the first may not exceed the second. +An atom followed by a bound containing one integer +.Ar i +and no comma matches +a sequence of exactly +.Ar i +matches of the atom. +An atom followed by a bound +containing one integer +.Ar i +and a comma matches +a sequence of +.Ar i +or more matches of the atom. +An atom followed by a bound +containing two integers +.Ar i +and +.Ar j +matches a sequence of +.Ar i +through +.Ar j +(inclusive) matches of the atom. +.Pp +An atom is a regular expression enclosed in +.Sq () +(matching a part of the regular expression), +an empty set of +.Sq () +(matching the null string)**, +a +.Em bracket expression +(see below), +.Sq .\& +(matching any single character), +.Sq ^ +(matching the null string at the beginning of a line), +.Sq $ +(matching the null string at the end of a line), +a +.Sq \e +followed by one of the characters +.Sq ^.[$()|*+?{\e +(matching that character taken as an ordinary character), +a +.Sq \e +followed by any other character** +(matching that character taken as an ordinary character, +as if the +.Sq \e +had not been present**), +or a single character with no other significance (matching that character). +A +.Sq { +followed by a character other than a digit is an ordinary character, +not the beginning of a bound**. +It is illegal to end an RE with +.Sq \e . +.Pp +A bracket expression is a list of characters enclosed in +.Sq [] . +It normally matches any single character from the list (but see below). +If the list begins with +.Sq ^ , +it matches any single character +.Em not +from the rest of the list +(but see below). +If two characters in the list are separated by +.Sq - , +this is shorthand for the full +.Em range +of characters between those two (inclusive) in the +collating sequence, e.g.\& +.Sq [0-9] +in ASCII matches any decimal digit. +It is illegal** for two ranges to share an endpoint, e.g.\& +.Sq a-c-e . +Ranges are very collating-sequence-dependent, +and portable programs should avoid relying on them. +.Pp +To include a literal +.Sq ]\& +in the list, make it the first character +(following a possible +.Sq ^ ) . +To include a literal +.Sq - , +make it the first or last character, +or the second endpoint of a range. +To use a literal +.Sq - +as the first endpoint of a range, +enclose it in +.Sq [. +and +.Sq .] +to make it a collating element (see below). +With the exception of these and some combinations using +.Sq [ +(see next paragraphs), +all other special characters, including +.Sq \e , +lose their special significance within a bracket expression. +.Pp +Within a bracket expression, a collating element +(a character, +a multi-character sequence that collates as if it were a single character, +or a collating-sequence name for either) +enclosed in +.Sq [. +and +.Sq .] +stands for the sequence of characters of that collating element. +The sequence is a single element of the bracket expression's list. +A bracket expression containing a multi-character collating element +can thus match more than one character, +e.g. if the collating sequence includes a +.Sq ch +collating element, +then the RE +.Sq [[.ch.]]*c +matches the first five characters of +.Sq chchcc . +.Pp +Within a bracket expression, a collating element enclosed in +.Sq [= +and +.Sq =] +is an equivalence class, standing for the sequences of characters +of all collating elements equivalent to that one, including itself. +(If there are no other equivalent collating elements, +the treatment is as if the enclosing delimiters were +.Sq [. +and +.Sq .] . ) +For example, if +.Sq x +and +.Sq y +are the members of an equivalence class, +then +.Sq [[=x=]] , +.Sq [[=y=]] , +and +.Sq [xy] +are all synonymous. +An equivalence class may not** be an endpoint of a range. +.Pp +Within a bracket expression, the name of a +.Em character class +enclosed +in +.Sq [: +and +.Sq :] +stands for the list of all characters belonging to that class. +Standard character class names are: +.Bd -literal -offset indent +alnum digit punct +alpha graph space +blank lower upper +cntrl print xdigit +.Ed +.Pp +These stand for the character classes defined in +.Xr ctype 3 . +A locale may provide others. +A character class may not be used as an endpoint of a range. +.Pp +There are two special cases** of bracket expressions: +the bracket expressions +.Sq [[:<:]] +and +.Sq [[:>:]] +match the null string at the beginning and end of a word, respectively. +A word is defined as a sequence of +characters starting and ending with a word character +which is neither preceded nor followed by +word characters. +A word character is an +.Em alnum +character (as defined by +.Xr ctype 3 ) +or an underscore. +This is an extension, +compatible with but not specified by POSIX, +and should be used with +caution in software intended to be portable to other systems. +.Pp +In the event that an RE could match more than one substring of a given +string, +the RE matches the one starting earliest in the string. +If the RE could match more than one substring starting at that point, +it matches the longest. +Subexpressions also match the longest possible substrings, subject to +the constraint that the whole match be as long as possible, +with subexpressions starting earlier in the RE taking priority over +ones starting later. +Note that higher-level subexpressions thus take priority over +their lower-level component subexpressions. +.Pp +Match lengths are measured in characters, not collating elements. +A null string is considered longer than no match at all. +For example, +.Sq bb* +matches the three middle characters of +.Sq abbbc ; +.Sq (wee|week)(knights|nights) +matches all ten characters of +.Sq weeknights ; +when +.Sq (.*).* +is matched against +.Sq abc , +the parenthesized subexpression matches all three characters; +and when +.Sq (a*)* +is matched against +.Sq bc , +both the whole RE and the parenthesized subexpression match the null string. +.Pp +If case-independent matching is specified, +the effect is much as if all case distinctions had vanished from the +alphabet. +When an alphabetic that exists in multiple cases appears as an +ordinary character outside a bracket expression, it is effectively +transformed into a bracket expression containing both cases, +e.g.\& +.Sq x +becomes +.Sq [xX] . +When it appears inside a bracket expression, +all case counterparts of it are added to the bracket expression, +so that, for example, +.Sq [x] +becomes +.Sq [xX] +and +.Sq [^x] +becomes +.Sq [^xX] . +.Pp +No particular limit is imposed on the length of REs**. +Programs intended to be portable should not employ REs longer +than 256 bytes, +as an implementation can refuse to accept such REs and remain +POSIX-compliant. +.Pp +The following is a list of extended regular expressions: +.Bl -tag -width Ds +.It Ar c +Any character +.Ar c +not listed below matches itself. +.It \e Ns Ar c +Any backslash-escaped character +.Ar c +matches itself. +.It \&. +Matches any single character that is not a newline +.Pq Sq \en . +.It Bq Ar char-class +Matches any single character in +.Ar char-class . +To include a +.Ql \&] +in +.Ar char-class , +it must be the first character. +A range of characters may be specified by separating the end characters +of the range with a +.Ql - ; +e.g.\& +.Ar a-z +specifies the lower case characters. +The following literal expressions can also be used in +.Ar char-class +to specify sets of characters: +.Bd -unfilled -offset indent +[:alnum:] [:cntrl:] [:lower:] [:space:] +[:alpha:] [:digit:] [:print:] [:upper:] +[:blank:] [:graph:] [:punct:] [:xdigit:] +.Ed +.Pp +If +.Ql - +appears as the first or last character of +.Ar char-class , +then it matches itself. +All other characters in +.Ar char-class +match themselves. +.Pp +Patterns in +.Ar char-class +of the form +.Eo [. +.Ar col-elm +.Ec .]\& +or +.Eo [= +.Ar col-elm +.Ec =]\& , +where +.Ar col-elm +is a collating element, are interpreted according to +.Xr setlocale 3 +.Pq not currently supported . +.It Bq ^ Ns Ar char-class +Matches any single character, other than newline, not in +.Ar char-class . +.Ar char-class +is defined as above. +.It ^ +If +.Sq ^ +is the first character of a regular expression, then it +anchors the regular expression to the beginning of a line. +Otherwise, it matches itself. +.It $ +If +.Sq $ +is the last character of a regular expression, +it anchors the regular expression to the end of a line. +Otherwise, it matches itself. +.It [[:<:]] +Anchors the single character regular expression or subexpression +immediately following it to the beginning of a word. +.It [[:>:]] +Anchors the single character regular expression or subexpression +immediately following it to the end of a word. +.It Pq Ar re +Defines a subexpression +.Ar re . +Any set of characters enclosed in parentheses +matches whatever the set of characters without parentheses matches +(that is a long-winded way of saying the constructs +.Sq (re) +and +.Sq re +match identically). +.It * +Matches the single character regular expression or subexpression +immediately preceding it zero or more times. +If +.Sq * +is the first character of a regular expression or subexpression, +then it matches itself. +The +.Sq * +operator sometimes yields unexpected results. +For example, the regular expression +.Ar b* +matches the beginning of the string +.Qq abbb +(as opposed to the substring +.Qq bbb ) , +since a null match is the only leftmost match. +.It + +Matches the singular character regular expression +or subexpression immediately preceding it +one or more times. +.It ? +Matches the singular character regular expression +or subexpression immediately preceding it +0 or 1 times. +.Sm off +.It Xo +.Pf { Ar n , m No }\ \& +.Pf { Ar n , No }\ \& +.Pf { Ar n No } +.Xc +.Sm on +Matches the single character regular expression or subexpression +immediately preceding it at least +.Ar n +and at most +.Ar m +times. +If +.Ar m +is omitted, then it matches at least +.Ar n +times. +If the comma is also omitted, then it matches exactly +.Ar n +times. +.It \*(Ba +Used to separate patterns. +For example, +the pattern +.Sq cat\*(Badog +matches either +.Sq cat +or +.Sq dog . +.El +.Sh BASIC REGULAR EXPRESSIONS +Basic regular expressions differ in several respects: +.Bl -bullet -offset 3n +.It +.Sq \*(Ba , +.Sq + , +and +.Sq ?\& +are ordinary characters and there is no equivalent +for their functionality. +.It +The delimiters for bounds are +.Sq \e{ +and +.Sq \e} , +with +.Sq { +and +.Sq } +by themselves ordinary characters. +.It +The parentheses for nested subexpressions are +.Sq \e( +and +.Sq \e) , +with +.Sq ( +and +.Sq )\& +by themselves ordinary characters. +.It +.Sq ^ +is an ordinary character except at the beginning of the +RE or** the beginning of a parenthesized subexpression. +.It +.Sq $ +is an ordinary character except at the end of the +RE or** the end of a parenthesized subexpression. +.It +.Sq * +is an ordinary character if it appears at the beginning of the +RE or the beginning of a parenthesized subexpression +(after a possible leading +.Sq ^ ) . +.It +Finally, there is one new type of atom, a +.Em back-reference : +.Sq \e +followed by a non-zero decimal digit +.Ar d +matches the same sequence of characters matched by the +.Ar d Ns th +parenthesized subexpression +(numbering subexpressions by the positions of their opening parentheses, +left to right), +so that, for example, +.Sq \e([bc]\e)\e1 +matches +.Sq bb\& +or +.Sq cc +but not +.Sq bc . +.El +.Pp +The following is a list of basic regular expressions: +.Bl -tag -width Ds +.It Ar c +Any character +.Ar c +not listed below matches itself. +.It \e Ns Ar c +Any backslash-escaped character +.Ar c , +except for +.Sq { , +.Sq } , +.Sq \&( , +and +.Sq \&) , +matches itself. +.It \&. +Matches any single character that is not a newline +.Pq Sq \en . +.It Bq Ar char-class +Matches any single character in +.Ar char-class . +To include a +.Ql \&] +in +.Ar char-class , +it must be the first character. +A range of characters may be specified by separating the end characters +of the range with a +.Ql - ; +e.g.\& +.Ar a-z +specifies the lower case characters. +The following literal expressions can also be used in +.Ar char-class +to specify sets of characters: +.Bd -unfilled -offset indent +[:alnum:] [:cntrl:] [:lower:] [:space:] +[:alpha:] [:digit:] [:print:] [:upper:] +[:blank:] [:graph:] [:punct:] [:xdigit:] +.Ed +.Pp +If +.Ql - +appears as the first or last character of +.Ar char-class , +then it matches itself. +All other characters in +.Ar char-class +match themselves. +.Pp +Patterns in +.Ar char-class +of the form +.Eo [. +.Ar col-elm +.Ec .]\& +or +.Eo [= +.Ar col-elm +.Ec =]\& , +where +.Ar col-elm +is a collating element, are interpreted according to +.Xr setlocale 3 +.Pq not currently supported . +.It Bq ^ Ns Ar char-class +Matches any single character, other than newline, not in +.Ar char-class . +.Ar char-class +is defined as above. +.It ^ +If +.Sq ^ +is the first character of a regular expression, then it +anchors the regular expression to the beginning of a line. +Otherwise, it matches itself. +.It $ +If +.Sq $ +is the last character of a regular expression, +it anchors the regular expression to the end of a line. +Otherwise, it matches itself. +.It [[:<:]] +Anchors the single character regular expression or subexpression +immediately following it to the beginning of a word. +.It [[:>:]] +Anchors the single character regular expression or subexpression +immediately following it to the end of a word. +.It \e( Ns Ar re Ns \e) +Defines a subexpression +.Ar re . +Subexpressions may be nested. +A subsequent backreference of the form +.Pf \e Ns Ar n , +where +.Ar n +is a number in the range [1,9], expands to the text matched by the +.Ar n Ns th +subexpression. +For example, the regular expression +.Ar \e(.*\e)\e1 +matches any string consisting of identical adjacent substrings. +Subexpressions are ordered relative to their left delimiter. +.It * +Matches the single character regular expression or subexpression +immediately preceding it zero or more times. +If +.Sq * +is the first character of a regular expression or subexpression, +then it matches itself. +The +.Sq * +operator sometimes yields unexpected results. +For example, the regular expression +.Ar b* +matches the beginning of the string +.Qq abbb +(as opposed to the substring +.Qq bbb ) , +since a null match is the only leftmost match. +.Sm off +.It Xo +.Pf \e{ Ar n , m No \e}\ \& +.Pf \e{ Ar n , No \e}\ \& +.Pf \e{ Ar n No \e} +.Xc +.Sm on +Matches the single character regular expression or subexpression +immediately preceding it at least +.Ar n +and at most +.Ar m +times. +If +.Ar m +is omitted, then it matches at least +.Ar n +times. +If the comma is also omitted, then it matches exactly +.Ar n +times. +.El +.Sh SEE ALSO +.Xr ctype 3 , +.Xr regex 3 +.Sh STANDARDS +.St -p1003.1-2004 : +Base Definitions, Chapter 9 (Regular Expressions). +.Sh BUGS +Having two kinds of REs is a botch. +.Pp +The current POSIX spec says that +.Sq )\& +is an ordinary character in the absence of an unmatched +.Sq ( ; +this was an unintentional result of a wording error, +and change is likely. +Avoid relying on it. +.Pp +Back-references are a dreadful botch, +posing major problems for efficient implementations. +They are also somewhat vaguely defined +(does +.Sq a\e(\e(b\e)*\e2\e)*d +match +.Sq abbbd ? ) . +Avoid using them. +.Pp +POSIX's specification of case-independent matching is vague. +The +.Dq one case implies all cases +definition given above +is the current consensus among implementors as to the right interpretation. +.Pp +The syntax for word boundaries is incredibly ugly. diff --git a/static/netbsd/man7/roff.7 b/static/netbsd/man7/roff.7 new file mode 100644 index 00000000..da12d0e9 --- /dev/null +++ b/static/netbsd/man7/roff.7 @@ -0,0 +1,2342 @@ +.\" Id: roff.7,v 1.116 2021/09/18 12:23:06 schwarze Exp +.\" +.\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons +.\" Copyright (c) 2010-2019 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd September 18, 2021 +.Dt ROFF 7 +.Os +.Sh NAME +.Nm roff +.Nd roff language reference for mandoc +.Sh DESCRIPTION +The +.Nm roff +language is a general purpose text formatting language. +Since traditional implementations of the +.Xr mdoc 7 +and +.Xr man 7 +manual formatting languages are based on it, +many real-world manuals use small numbers of +.Nm +requests and escape sequences intermixed with their +.Xr mdoc 7 +or +.Xr man 7 +code. +To properly format such manuals, the +.Xr mandoc 1 +utility supports a subset of +.Nm +requests and escapes. +Even though this manual page lists all +.Nm +requests and escape sequences, it only contains partial information +about requests not supported by +.Xr mandoc 1 +and about language features that do not matter for manual pages. +For complete +.Nm +manuals, consult the +.Sx SEE ALSO +section. +.Pp +Input lines beginning with the control character +.Sq \&. +are parsed for requests and macros. +Such lines are called +.Dq request lines +or +.Dq macro lines , +respectively. +Requests change the processing state and manipulate the formatting; +some macros also define the document structure and produce formatted +output. +The single quote +.Pq Qq \(aq +is accepted as an alternative control character, +treated by +.Xr mandoc 1 +just like +.Ql \&. +.Pp +Lines not beginning with control characters are called +.Dq text lines . +They provide free-form text to be printed; the formatting of the text +depends on the respective processing context. +.Sh LANGUAGE SYNTAX +.Nm +documents may contain only graphable 7-bit ASCII characters, the space +character, and, in certain circumstances, the tab character. +The backslash character +.Sq \e +indicates the start of an escape sequence, used for example for +.Sx Comments +and +.Sx Special Characters . +For a complete listing of escape sequences, consult the +.Sx ESCAPE SEQUENCE REFERENCE +below. +.Ss Comments +Text following an escaped double-quote +.Sq \e\(dq , +whether in a request, macro, or text line, is ignored to the end of the line. +A request line beginning with a control character and comment escape +.Sq \&.\e\(dq +is also ignored. +Furthermore, request lines with only a control character and optional +trailing whitespace are stripped from input. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.\e\(dq This is a comment line. +\&.\e\(dq The next line is ignored: +\&. +\&.Sh EXAMPLES \e\(dq This is a comment, too. +\&example text \e\(dq And so is this. +.Ed +.Ss Special Characters +Special characters are used to encode special glyphs and are rendered +differently across output media. +They may occur in request, macro, and text lines. +Sequences begin with the escape character +.Sq \e +followed by either an open-parenthesis +.Sq \&( +for two-character sequences; an open-bracket +.Sq \&[ +for n-character sequences (terminated at a close-bracket +.Sq \&] ) ; +or a single one character sequence. +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li \e(em +Two-letter em dash escape. +.It Li \ee +One-letter backslash escape. +.El +.Pp +See +.Xr mandoc_char 7 +for a complete list. +.Ss Font Selection +In +.Xr mdoc 7 +and +.Xr man 7 +documents, fonts are usually selected with macros. +The +.Ic \ef +escape sequence and the +.Ic \&ft +request can be used to manually change the font, +but this is not recommended in +.Xr mdoc 7 +documents. +Such manual font changes are overridden by many subsequent macros. +.Pp +The following fonts are supported: +.Pp +.Bl -tag -width CW -offset indent -compact +.It Cm B +Bold font. +.It Cm BI +A font that is both bold and italic. +.It Cm CB +Bold constant width font. +Same as +.Cm B +in terminal output. +.It Cm CI +Italic constant width font. +Same as +.Cm I +in terminal output. +.It Cm CR +Regular constant width font. +Same as +.Cm R +in terminal output. +.It Cm CW +An alias for +.Cm CR . +.It Cm I +Italic font. +.It Cm P +Return to the previous font. +If a macro caused a font change since the last +.Ic \ef +eascape sequence or +.Ic \&ft +request, this returns to the font before the last font change in +the macro rather than to the font before the last manual font change. +.It Cm R +Roman font. +This is the default font. +.It Cm 1 +An alias for +.Cm R . +.It Cm 2 +An alias for +.Cm I . +.It Cm 3 +An alias for +.Cm B . +.It Cm 4 +An alias for +.Cm BI . +.El +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li \efBbold\efR +Write in \fBbold\fP, then switch to regular font mode. +.It Li \efIitalic\efP +Write in \fIitalic\fP, then return to previous font mode. +.It Li \ef(BIbold italic\efP +Write in \f(BIbold italic\fP, then return to previous font mode. +.El +.Ss Whitespace +Whitespace consists of the space character. +In text lines, whitespace is preserved within a line. +In request and macro lines, whitespace delimits arguments and is discarded. +.Pp +Unescaped trailing spaces are stripped from text line input unless in a +literal context. +In general, trailing whitespace on any input line is discouraged for +reasons of portability. +In the rare case that a space character is needed at the end of an +input line, it may be forced by +.Sq \e\ \e& . +.Pp +Literal space characters can be produced in the output +using escape sequences. +In macro lines, they can also be included in arguments using quotation; see +.Sx MACRO SYNTAX +for details. +.Pp +Blank text lines, which may include whitespace, are only permitted +within literal contexts. +If the first character of a text line is a space, that line is printed +with a leading newline. +.Ss Scaling Widths +Many requests and macros support scaled widths for their arguments. +The syntax for a scaled width is +.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , +where a decimal must be preceded or followed by at least one digit. +.Pp +The following scaling units are accepted: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It c +centimetre +.It i +inch +.It P +pica (1/6 inch) +.It p +point (1/72 inch) +.It f +scale +.Sq u +by 65536 +.It v +default vertical span +.It m +width of rendered +.Sq m +.Pq em +character +.It n +width of rendered +.Sq n +.Pq en +character +.It u +default horizontal span for the terminal +.It M +mini-em (1/100 em) +.El +.Pp +Using anything other than +.Sq m , +.Sq n , +or +.Sq v +is necessarily non-portable across output media. +See +.Sx COMPATIBILITY . +.Pp +If a scaling unit is not provided, the numerical value is interpreted +under the default rules of +.Sq v +for vertical spaces and +.Sq u +for horizontal ones. +.Pp +Examples: +.Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact +.It Li \&.Bl -tag -width 2i +two-inch tagged list indentation in +.Xr mdoc 7 +.It Li \&.HP 2i +two-inch tagged list indentation in +.Xr man 7 +.It Li \&.sp 2v +two vertical spaces +.El +.Ss Sentence Spacing +Each sentence should terminate at the end of an input line. +By doing this, a formatter will be able to apply the proper amount of +spacing after the end of sentence (unescaped) period, exclamation mark, +or question mark followed by zero or more non-sentence closing +delimiters +.Po +.Sq \&) , +.Sq \&] , +.Sq \&' , +.Sq \&" +.Pc . +.Pp +The proper spacing is also intelligently preserved if a sentence ends at +the boundary of a macro line. +.Pp +If an input line happens to end with a period, exclamation or question +mark that isn't the end of a sentence, append a zero-width space +.Pq Sq \e& . +.Pp +Examples: +.Bd -literal -offset indent -compact +Do not end sentences mid-line like this. Instead, +end a sentence like this. +A macro would end like this: +\&.Xr mandoc 1 \&. +An abbreviation at the end of an input line needs escaping, e.g.\e& +like this. +.Ed +.Sh REQUEST SYNTAX +A request or macro line consists of: +.Pp +.Bl -enum -compact +.It +the control character +.Sq \&. +or +.Sq \(aq +at the beginning of the line, +.It +optionally an arbitrary amount of whitespace, +.It +the name of the request or the macro, which is one word of arbitrary +length, terminated by whitespace, +.It +and zero or more arguments delimited by whitespace. +.El +.Pp +Thus, the following request lines are all equivalent: +.Bd -literal -offset indent +\&.ig end +\&.ig end +\&. ig end +.Ed +.Sh MACRO SYNTAX +Macros are provided by the +.Xr mdoc 7 +and +.Xr man 7 +languages and can be defined by the +.Ic \&de +request. +When called, they follow the same syntax as requests, except that +macro arguments may optionally be quoted by enclosing them +in double quote characters +.Pq Sq \(dq . +Quoted text, even if it contains whitespace or would cause +a macro invocation when unquoted, is always considered literal text. +Inside quoted text, pairs of double quote characters +.Pq Sq Qq +resolve to single double quote characters. +.Pp +To be recognised as the beginning of a quoted argument, the opening +quote character must be preceded by a space character. +A quoted argument extends to the next double quote character that is not +part of a pair, or to the end of the input line, whichever comes earlier. +Leaving out the terminating double quote character at the end of the line +is discouraged. +For clarity, if more arguments follow on the same input line, +it is recommended to follow the terminating double quote character +by a space character; in case the next character after the terminating +double quote character is anything else, it is regarded as the beginning +of the next, unquoted argument. +.Pp +Both in quoted and unquoted arguments, pairs of backslashes +.Pq Sq \e\e +resolve to single backslashes. +In unquoted arguments, space characters can alternatively be included +by preceding them with a backslash +.Pq Sq \e\~ , +but quoting is usually better for clarity. +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li .Fn strlen \(dqconst char *s\(dq +Group arguments +.Qq const char *s +into one function argument. +If unspecified, +.Qq const , +.Qq char , +and +.Qq *s +would be considered separate arguments. +.It Li .Op \(dqFl a\(dq +Consider +.Qq \&Fl a +as literal text instead of a flag macro. +.El +.Sh REQUEST REFERENCE +The +.Xr mandoc 1 +.Nm +parser recognises the following requests. +For requests marked as "ignored" or "unsupported", any arguments are +ignored, and the number of arguments is not checked. +.Bl -tag -width Ds +.It Ic \&ab Op Ar message +Abort processing. +Currently unsupported. +.It Ic \&ad Op Cm b | c | l | n | r +Set line adjustment mode for subsequent text. +Currently ignored. +.It Ic \&af Ar registername format +Assign an output format to a number register. +Currently ignored. +.It Ic \&aln Ar newname oldname +Create an alias for a number register. +Currently unsupported. +.It Ic \&als Ar newname oldname +Create an alias for a request, string, macro, or diversion. +.It Ic \&am Ar macroname Op Ar endmacro +Append to a macro definition. +The syntax of this request is the same as that of +.Ic \&de . +.It Ic \&am1 Ar macroname Op Ar endmacro +Append to a macro definition, switching roff compatibility mode off +during macro execution (groff extension). +The syntax of this request is the same as that of +.Ic \&de1 . +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&am . +.It Ic \&ami Ar macrostring Op Ar endstring +Append to a macro definition, specifying the macro name indirectly +(groff extension). +The syntax of this request is the same as that of +.Ic \&dei . +.It Ic \&ami1 Ar macrostring Op Ar endstring +Append to a macro definition, specifying the macro name indirectly +and switching roff compatibility mode off during macro execution +(groff extension). +The syntax of this request is the same as that of +.Ic \&dei1 . +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&ami . +.It Ic \&as Ar stringname Op Ar string +Append to a user-defined string. +The syntax of this request is the same as that of +.Ic \&ds . +If a user-defined string with the specified name does not yet exist, +it is set to the empty string before appending. +.It Ic \&as1 Ar stringname Op Ar string +Append to a user-defined string, switching roff compatibility mode off +during macro execution (groff extension). +The syntax of this request is the same as that of +.Ic \&ds1 . +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&as . +.It Ic \&asciify Ar divname +Fully unformat a diversion. +Currently unsupported. +.It Ic \&backtrace +Print a backtrace of the input stack. +This is a groff extension and currently ignored. +.It Ic \&bd Ar font Oo Ar curfont Oc Op Ar offset +Artificially embolden by repeated printing with small shifts. +Currently ignored. +.It Ic \&bleedat Ar left top width height +Set the BleedBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.It Ic \&blm Ar macroname +Set a blank line trap. +Currently unsupported. +.It Ic \&box Ar divname +Begin a diversion without including a partially filled line. +Currently unsupported. +.It Ic \&boxa Ar divname +Add to a diversion without including a partially filled line. +Currently unsupported. +.It Ic \&bp Oo Cm + Ns | Ns Cm - Oc Ns Ar pagenumber +Begin a new page. +Currently ignored. +.It Ic \&BP Ar source height width position offset flags label +Define a frame and place a picture in it. +This is a Heirloom extension and currently unsupported. +.It Ic \&br +Break the output line. +.It Ic \&break +Break out of the innermost +.Ic \&while +loop. +.It Ic \&breakchar Ar char ... +Optional line break characters. +This is a Heirloom extension and currently ignored. +.It Ic \&brnl Ar N +Break output line after the next +.Ar N +input lines. +This is a Heirloom extension and currently ignored. +.It Ic \&brp +Break and spread output line. +Currently, this is implemented as an alias for +.Ic \&br . +.It Ic \&brpnl Ar N +Break and spread output line after the next +.Ar N +input lines. +This is a Heirloom extension and currently ignored. +.It Ic \&c2 Op Ar char +Change the no-break control character. +Currently unsupported. +.It Ic \&cc Op Ar char +Change the control character. +If +.Ar char +is not specified, the control character is reset to +.Sq \&. . +Trailing characters are ignored. +.It Ic \&ce Op Ar N +Center the next +.Ar N +input lines without filling. +.Ar N +defaults to 1. +An argument of 0 or less ends centering. +Currently, high level macros abort centering. +.It Ic \&cf Ar filename +Output the contents of a file. +Ignored because insecure. +.It Ic \&cflags Ar flags char ... +Set character flags. +This is a groff extension and currently ignored. +.It Ic \&ch Ar macroname Op Ar dist +Change a trap location. +Currently ignored. +.It Ic \&char Ar glyph Op Ar string +Define or redefine the ASCII character or character escape sequence +.Ar glyph +to be rendered as +.Ar string , +which can be empty. +Only partially supported in +.Xr mandoc 1 ; +may interact incorrectly with +.Ic \&tr . +.It Ic \&chop Ar stringname +Remove the last character from a macro, string, or diversion. +Currently unsupported. +.It Ic \&class Ar classname char ... +Define a character class. +This is a groff extension and currently ignored. +.It Ic \&close Ar streamname +Close an open file. +Ignored because insecure. +.It Ic \&CL Ar color text +Print text in color. +This is a Heirloom extension and currently unsupported. +.It Ic \&color Op Cm 1 | 0 +Activate or deactivate colors. +This is a groff extension and currently ignored. +.It Ic \&composite Ar from to +Define a name component for composite glyph names. +This is a groff extension and currently unsupported. +.It Ic \&continue +Immediately start the next iteration of a +.Ic \&while +loop. +Currently unsupported. +.It Ic \&cp Op Cm 1 | 0 +Switch +.Nm +compatibility mode on or off. +Currently ignored. +.It Ic \&cropat Ar left top width height +Set the CropBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.It Ic \&cs Ar font Op Ar width Op Ar emsize +Constant character spacing mode. +Currently ignored. +.It Ic \&cu Op Ar N +Underline next +.Ar N +input lines including whitespace. +Currently ignored. +.It Ic \&da Ar divname +Append to a diversion. +Currently unsupported. +.It Ic \&dch Ar macroname Op Ar dist +Change a trap location in the current diversion. +This is a Heirloom extension and currently unsupported. +.It Ic \&de Ar macroname Op Ar endmacro +Define a +.Nm +macro. +Its syntax can be either +.Bd -literal -offset indent +.Pf . Ic \&de Ar macroname +.Ar definition +\&.. +.Ed +.Pp +or +.Bd -literal -offset indent +.Pf . Ic \&de Ar macroname endmacro +.Ar definition +.Pf . Ar endmacro +.Ed +.Pp +Both forms define or redefine the macro +.Ar macroname +to represent the +.Ar definition , +which may consist of one or more input lines, including the newline +characters terminating each line, optionally containing calls to +.Nm +requests, +.Nm +macros or high-level macros like +.Xr man 7 +or +.Xr mdoc 7 +macros, whichever applies to the document in question. +.Pp +Specifying a custom +.Ar endmacro +works in the same way as for +.Ic \&ig ; +namely, the call to +.Sq Pf . Ar endmacro +first ends the +.Ar definition , +and after that, it is also evaluated as a +.Nm +request or +.Nm +macro, but not as a high-level macro. +.Pp +The macro can be invoked later using the syntax +.Pp +.D1 Pf . Ar macroname Op Ar argument Op Ar argument ... +.Pp +Regarding argument parsing, see +.Sx MACRO SYNTAX +above. +.Pp +The line invoking the macro will be replaced +in the input stream by the +.Ar definition , +replacing all occurrences of +.No \e\e$ Ns Ar N , +where +.Ar N +is a digit, by the +.Ar N Ns th Ar argument . +For example, +.Bd -literal -offset indent +\&.de ZN +\efI\e^\e\e$1\e^\efP\e\e$2 +\&.. +\&.ZN XtFree . +.Ed +.Pp +produces +.Pp +.D1 \efI\e^XtFree\e^\efP. +.Pp +in the input stream, and thus in the output: \fI\^XtFree\^\fP. +Each occurrence of \e\e$* is replaced with all the arguments, +joined together with single space characters. +The variant \e\e$@ is similar, except that each argument is +individually quoted. +.Pp +Since macros and user-defined strings share a common string table, +defining a macro +.Ar macroname +clobbers the user-defined string +.Ar macroname , +and the +.Ar definition +can also be printed using the +.Sq \e* +string interpolation syntax described below +.Ic ds , +but this is rarely useful because every macro definition contains at least +one explicit newline character. +.Pp +In order to prevent endless recursion, both groff and +.Xr mandoc 1 +limit the stack depth for expanding macros and strings +to a large, but finite number, and +.Xr mandoc 1 +also limits the length of the expanded input line. +Do not rely on the exact values of these limits. +.It Ic \&de1 Ar macroname Op Ar endmacro +Define a +.Nm +macro that will be executed with +.Nm +compatibility mode switched off during macro execution. +This is a groff extension. +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&de . +.It Ic \&defcolor Ar newname scheme component ... +Define a color name. +This is a groff extension and currently ignored. +.It Ic \&dei Ar macrostring Op Ar endstring +Define a +.Nm +macro, specifying the macro name indirectly (groff extension). +The syntax of this request is the same as that of +.Ic \&de . +The effect is the same as: +.Pp +.D1 Pf . Cm \&de No \e* Ns Bo Ar macrostring Bc Op \e* Ns Bq Ar endstring +.It Ic \&dei1 Ar macrostring Op Ar endstring +Define a +.Nm +macro that will be executed with +.Nm +compatibility mode switched off during macro execution, +specifying the macro name indirectly (groff extension). +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&dei . +.It Ic \&device Ar string ... +.It Ic \&devicem Ar stringname +These two requests only make sense with the groff-specific intermediate +output format and are unsupported. +.It Ic \&di Ar divname +Begin a diversion. +Currently unsupported. +.It Ic \&do Ar command Op Ar argument ... +Execute +.Nm +request or macro line with compatibility mode disabled. +Currently unsupported. +.It Ic \&ds Ar stringname Op Oo \(dq Oc Ns Ar string +Define a user-defined string. +The +.Ar stringname +and +.Ar string +arguments are space-separated. +If the +.Ar string +begins with a double-quote character, that character will not be part +of the string. +All remaining characters on the input line form the +.Ar string , +including whitespace and double-quote characters, even trailing ones. +.Pp +The +.Ar string +can be interpolated into subsequent text by using +.No \e* Ns Bq Ar stringname +for a +.Ar stringname +of arbitrary length, or \e*(NN or \e*N if the length of +.Ar stringname +is two or one characters, respectively. +Interpolation can be prevented by escaping the leading backslash; +that is, an asterisk preceded by an even number of backslashes +does not trigger string interpolation. +.Pp +Since user-defined strings and macros share a common string table, +defining a string +.Ar stringname +clobbers the macro +.Ar stringname , +and the +.Ar stringname +used for defining a string can also be invoked as a macro, +in which case the following input line will be appended to the +.Ar string , +forming a new input line passed to the +.Nm +parser. +For example, +.Bd -literal -offset indent +\&.ds badidea .S +\&.badidea +H SYNOPSIS +.Ed +.Pp +invokes the +.Ic SH +macro when used in a +.Xr man 7 +document. +Such abuse is of course strongly discouraged. +.It Ic \&ds1 Ar stringname Op Oo \(dq Oc Ns Ar string +Define a user-defined string that will be expanded with +.Nm +compatibility mode switched off during string expansion. +This is a groff extension. +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&ds . +.It Ic \&dwh Ar dist macroname +Set a location trap in the current diversion. +This is a Heirloom extension and currently unsupported. +.It Ic \&dt Op Ar dist macroname +Set a trap within a diversion. +Currently unsupported. +.It Ic \&ec Op Ar char +Enable the escape mechanism and change the escape character. +The +.Ar char +argument defaults to the backslash +.Pq Sq \e . +.It Ic \&ecr +Restore the escape character. +Currently unsupported. +.It Ic \&ecs +Save the escape character. +Currently unsupported. +.It Ic \&el Ar body +The +.Dq else +half of an if/else conditional. +Pops a result off the stack of conditional evaluations pushed by +.Ic \&ie +and uses it as its conditional. +If no stack entries are present (e.g., due to no prior +.Ic \&ie +calls) +then false is assumed. +The syntax of this request is similar to +.Ic \&if +except that the conditional is missing. +.It Ic \&em Ar macroname +Set a trap at the end of input. +Currently unsupported. +.It Ic \&EN +End an equation block. +See +.Ic \&EQ . +.It Ic \&eo +Disable the escape mechanism completely. +.It Ic \&EP +End a picture started by +.Ic \&BP . +This is a Heirloom extension and currently unsupported. +.It Ic \&EQ +Begin an equation block. +See +.Xr eqn 7 +for a description of the equation language. +.It Ic \&errprint Ar message +Print a string like an error message. +This is a Heirloom extension and currently ignored. +.It Ic \&ev Op Ar envname +Switch to another environment. +Currently unsupported. +.It Ic \&evc Op Ar envname +Copy an environment into the current environment. +Currently unsupported. +.It Ic \&ex +Abort processing and exit. +Currently unsupported. +.It Ic \&fallback Ar curfont font ... +Select the fallback sequence for a font. +This is a Heirloom extension and currently ignored. +.It Ic \&fam Op Ar familyname +Change the font family. +This is a groff extension and currently ignored. +.It Ic \&fc Op Ar delimchar Op Ar padchar +Define a delimiting and a padding character for fields. +Currently unsupported. +.It Ic \&fchar Ar glyphname Op Ar string +Define a fallback glyph. +Currently unsupported. +.It Ic \&fcolor Ar colorname +Set the fill color for \eD objects. +This is a groff extension and currently ignored. +.It Ic \&fdeferlig Ar font string ... +Defer ligature building. +This is a Heirloom extension and currently ignored. +.It Ic \&feature Cm + Ns | Ns Cm - Ns Ar name +Enable or disable an OpenType feature. +This is a Heirloom extension and currently ignored. +.It Ic \&fi +Break the output line and switch to fill mode, +which is active by default but can be ended with the +.Ic \&nf +request. +In fill mode, input from subsequent input lines is added to +the same output line until the next word no longer fits, +at which point the output line is broken. +This request is implied by the +.Xr mdoc 7 +.Ic \&Sh +macro and by the +.Xr man 7 +.Ic \&SH , +.Ic \&SS , +and +.Ic \&EE +macros. +.It Ic \&fkern Ar font minkern +Control the use of kerning tables for a font. +This is a Heirloom extension and currently ignored. +.It Ic \&fl +Flush output. +Currently ignored. +.It Ic \&flig Ar font string char ... +Define ligatures. +This is a Heirloom extension and currently ignored. +.It Ic \&fp Ar position font Op Ar filename +Assign font position. +Currently ignored. +.It Ic \&fps Ar mapname ... +Mount a font with a special character map. +This is a Heirloom extension and currently ignored. +.It Ic \&fschar Ar font glyphname Op Ar string +Define a font-specific fallback glyph. +This is a groff extension and currently unsupported. +.It Ic \&fspacewidth Ar font Op Ar afmunits +Set a font-specific width for the space character. +This is a Heirloom extension and currently ignored. +.It Ic \&fspecial Ar curfont Op Ar font ... +Conditionally define a special font. +This is a groff extension and currently ignored. +.It Ic \&ft Op Ar font +Change the font; see +.Sx Font Selection . +The +.Ar font +argument defaults to +.Cm P . +.It Ic \&ftr Ar newname Op Ar oldname +Translate font name. +This is a groff extension and currently ignored. +.It Ic \&fzoom Ar font Op Ar permille +Zoom font size. +Currently ignored. +.It Ic \&gcolor Op Ar colorname +Set glyph color. +This is a groff extension and currently ignored. +.It Ic \&hc Op Ar char +Set the hyphenation character. +Currently ignored. +.It Ic \&hcode Ar char code ... +Set hyphenation codes of characters. +Currently ignored. +.It Ic \&hidechar Ar font char ... +Hide characters in a font. +This is a Heirloom extension and currently ignored. +.It Ic \&hla Ar language +Set hyphenation language. +This is a groff extension and currently ignored. +.It Ic \&hlm Op Ar number +Set maximum number of consecutive hyphenated lines. +Currently ignored. +.It Ic \&hpf Ar filename +Load hyphenation pattern file. +This is a groff extension and currently ignored. +.It Ic \&hpfa Ar filename +Load hyphenation pattern file, appending to the current patterns. +This is a groff extension and currently ignored. +.It Ic \&hpfcode Ar code code ... +Define mapping values for character codes in hyphenation patterns. +This is a groff extension and currently ignored. +.It Ic \&hw Ar word ... +Specify hyphenation points in words. +Currently ignored. +.It Ic \&hy Op Ar mode +Set automatic hyphenation mode. +Currently ignored. +.It Ic \&hylang Ar language +Set hyphenation language. +This is a Heirloom extension and currently ignored. +.It Ic \&hylen Ar nchar +Minimum word length for hyphenation. +This is a Heirloom extension and currently ignored. +.It Ic \&hym Op Ar length +Set hyphenation margin. +This is a groff extension and currently ignored. +.It Ic \&hypp Ar penalty ... +Define hyphenation penalties. +This is a Heirloom extension and currently ignored. +.It Ic \&hys Op Ar length +Set hyphenation space. +This is a groff extension and currently ignored. +.It Ic \&ie Ar condition body +The +.Dq if +half of an if/else conditional. +The result of the conditional is pushed into a stack used by subsequent +invocations of +.Ic \&el , +which may be separated by any intervening input (or not exist at all). +Its syntax is equivalent to +.Ic \&if . +.It Ic \&if Ar condition body +Begin a conditional. +This request can also be written as follows: +.Bd -unfilled -offset indent +.Pf . Ic \&if Ar condition No \e{ Ns Ar body +.Ar body ... Ns \e} +.Ed +.Bd -unfilled -offset indent +.Pf . Ic \&if Ar condition No \e{\e +.Ar body ... +.Pf . No \e} +.Ed +.Pp +The +.Ar condition +is a boolean expression. +Currently, +.Xr mandoc 1 +supports the following subset of roff conditionals: +.Bl -bullet +.It +If +.Sq \&! +is prefixed to +.Ar condition , +it is logically inverted. +.It +If the first character of +.Ar condition +is +.Sq n +.Pq nroff mode +or +.Sq o +.Pq odd page , +it evaluates to true, and the +.Ar body +starts with the next character. +.It +If the first character of +.Ar condition +is +.Sq e +.Pq even page , +.Sq t +.Pq troff mode , +or +.Sq v +.Pq vroff mode , +it evaluates to false, and the +.Ar body +starts with the next character. +.It +If the first character of +.Ar condition +is +.Sq c +.Pq character available , +it evaluates to true if the following character is an ASCII character +or a valid character escape sequence, or to false otherwise. +The +.Ar body +starts with the character following that next character. +.It +If the first character of +.Ar condition +is +.Sq d , +it evaluates to true if the rest of +.Ar condition +is the name of an existing user defined macro or string; +otherwise, it evaluates to false. +.It +If the first character of +.Ar condition +is +.Sq r , +it evaluates to true if the rest of +.Ar condition +is the name of an existing number register; +otherwise, it evaluates to false. +.It +If the +.Ar condition +starts with a parenthesis or with an optionally signed +integer number, it is evaluated according to the rules of +.Sx Numerical expressions +explained below. +It evaluates to true if the result is positive, +or to false if the result is zero or negative. +.It +Otherwise, the first character of +.Ar condition +is regarded as a delimiter and it evaluates to true if the string +extending from its first to its second occurrence is equal to the +string extending from its second to its third occurrence. +.It +If +.Ar condition +cannot be parsed, it evaluates to false. +.El +.Pp +If a conditional is false, its children are not processed, but are +syntactically interpreted to preserve the integrity of the input +document. +Thus, +.Pp +.D1 \&.if t .ig +.Pp +will discard the +.Sq \&.ig , +which may lead to interesting results, but +.Pp +.D1 \&.if t .if t \e{\e +.Pp +will continue to syntactically interpret to the block close of the final +conditional. +Sub-conditionals, in this case, obviously inherit the truth value of +the parent. +.Pp +If the +.Ar body +section is begun by an escaped brace +.Sq \e{ , +scope continues until the end of the input line containing the +matching closing-brace escape sequence +.Sq \e} . +If the +.Ar body +is not enclosed in braces, scope continues until the end of the line. +If the +.Ar condition +is followed by a +.Ar body +on the same line, whether after a brace or not, then requests and macros +.Em must +begin with a control character. +It is generally more intuitive, in this case, to write +.Bd -unfilled -offset indent +.Pf . Ic \&if Ar condition No \e{\e +.Pf . Ar request +.Pf . No \e} +.Ed +.Pp +than having the request or macro follow as +.Pp +.D1 Pf . Ic \&if Ar condition Pf \e{. Ar request +.Pp +The scope of a conditional is always parsed, but only executed if the +conditional evaluates to true. +.Pp +Note that the +.Sq \e} +is converted into a zero-width escape sequence if not passed as a +standalone macro +.Sq \&.\e} . +For example, +.Pp +.D1 \&.Fl a \e} b +.Pp +will result in +.Sq \e} +being considered an argument of the +.Sq \&Fl +macro. +.It Ic \&ig Op Ar endmacro +Ignore input. +Its syntax can be either +.Bd -literal -offset indent +.Pf . Cm \&ig +.Ar ignored text +\&.. +.Ed +.Pp +or +.Bd -literal -offset indent +.Pf . Cm \&ig Ar endmacro +.Ar ignored text +.Pf . Ar endmacro +.Ed +.Pp +In the first case, input is ignored until a +.Sq \&.. +request is encountered on its own line. +In the second case, input is ignored until the specified +.Sq Pf . Ar endmacro +is encountered. +Do not use the escape character +.Sq \e +anywhere in the definition of +.Ar endmacro ; +it would cause very strange behaviour. +.Pp +When the +.Ar endmacro +is a roff request or a roff macro, like in +.Pp +.D1 \&.ig if +.Pp +the subsequent invocation of +.Ic \&if +will first terminate the +.Ar ignored text , +then be invoked as usual. +Otherwise, it only terminates the +.Ar ignored text , +and arguments following it or the +.Sq \&.. +request are discarded. +.It Ic \&in Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width +Change indentation. +See +.Xr man 7 . +Ignored in +.Xr mdoc 7 . +.It Ic \&index Ar register stringname substring +Find a substring in a string. +This is a Heirloom extension and currently unsupported. +.It Ic \&it Ar expression macro +Set an input line trap. +The named +.Ar macro +will be invoked after processing the number of input text lines +specified by the numerical +.Ar expression . +While evaluating the +.Ar expression , +the unit suffixes described below +.Sx Scaling Widths +are ignored. +.It Ic \&itc Ar expression macro +Set an input line trap, not counting lines ending with \ec. +Currently unsupported. +.It Ic \&IX Ar class keystring +To support the generation of a table of contents, +.Xr pod2man 1 +emits this user-defined macro, usually without defining it. +To avoid reporting large numbers of spurious errors, +.Xr mandoc 1 +ignores it. +.It Ic \&kern Op Cm 1 | 0 +Switch kerning on or off. +Currently ignored. +.It Ic \&kernafter Ar font char ... afmunits ... +Increase kerning after some characters. +This is a Heirloom extension and currently ignored. +.It Ic \&kernbefore Ar font char ... afmunits ... +Increase kerning before some characters. +This is a Heirloom extension and currently ignored. +.It Ic \&kernpair Ar font char ... font char ... afmunits +Add a kerning pair to the kerning table. +This is a Heirloom extension and currently ignored. +.It Ic \&lc Op Ar glyph +Define a leader repetition character. +Currently unsupported. +.It Ic \&lc_ctype Ar localename +Set the +.Dv LC_CTYPE +locale. +This is a Heirloom extension and currently unsupported. +.It Ic \&lds Ar macroname string +Define a local string. +This is a Heirloom extension and currently unsupported. +.It Ic \&length Ar register string +Count the number of input characters in a string. +Currently unsupported. +.It Ic \&letadj Ar lspmin lshmin letss lspmax lshmax +Dynamic letter spacing and reshaping. +This is a Heirloom extension and currently ignored. +.It Ic \&lf Ar lineno Op Ar filename +Change the line number for error messages. +Ignored because insecure. +.It Ic \&lg Op Cm 1 | 0 +Switch the ligature mechanism on or off. +Currently ignored. +.It Ic \&lhang Ar font char ... afmunits +Hang characters at left margin. +This is a Heirloom extension and currently ignored. +.It Ic \&linetabs Op Cm 1 | 0 +Enable or disable line-tabs mode. +This is a groff extension and currently unsupported. +.It Ic \&ll Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width +Change the output line length. +If the +.Ar width +argument is omitted, the line length is reset to its previous value. +The default setting for terminal output is 78n. +If a sign is given, the line length is added to or subtracted from; +otherwise, it is set to the provided value. +Using this request in new manuals is discouraged for several reasons, +among others because it overrides the +.Xr mandoc 1 +.Fl O Cm width +command line option. +.It Ic \&lnr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar value Op Ar increment +Set local number register. +This is a Heirloom extension and currently unsupported. +.It Ic \&lnrf Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar value Op Ar increment +Set local floating-point register. +This is a Heirloom extension and currently unsupported. +.It Ic \&lpfx Ar string +Set a line prefix. +This is a Heirloom extension and currently unsupported. +.It Ic \&ls Op Ar factor +Set line spacing. +It takes one integer argument specifying the vertical distance of +subsequent output text lines measured in v units. +Currently ignored. +.It Ic \&lsm Ar macroname +Set a leading spaces trap. +This is a groff extension and currently unsupported. +.It Ic \< Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width +Set title line length. +Currently ignored. +.It Ic \&mc Ar glyph Op Ar dist +Print margin character in the right margin. +The +.Ar dist +is currently ignored; instead, 1n is used. +.It Ic \&mediasize Ar media +Set the device media size. +This is a Heirloom extension and currently ignored. +.It Ic \&minss Ar width +Set minimum word space. +This is a Heirloom extension and currently ignored. +.It Ic \&mk Op Ar register +Mark vertical position. +Currently ignored. +.It Ic \&mso Ar filename +Load a macro file using the search path. +Ignored because insecure. +.It Ic \&na +Disable adjusting without changing the adjustment mode. +Currently ignored. +.It Ic \&ne Op Ar height +Declare the need for the specified minimum vertical space +before the next trap or the bottom of the page. +Currently ignored. +.It Ic \&nf +Break the output line and switch to no-fill mode. +Subsequent input lines are kept together on the same output line +even when exceeding the right margin, +and line breaks in subsequent input cause output line breaks. +This request is implied by the +.Xr mdoc 7 +.Ic \&Bd Fl unfilled +and +.Ic \&Bd Fl literal +macros and by the +.Xr man 7 +.Ic \&EX +macro. +The +.Ic \&fi +request switches back to the default fill mode. +.It Ic \&nh +Turn off automatic hyphenation mode. +Currently ignored. +.It Ic \&nhychar Ar char ... +Define hyphenation-inhibiting characters. +This is a Heirloom extension and currently ignored. +.It Ic \&nm Op Ar start Op Ar inc Op Ar space Op Ar indent +Print line numbers. +Currently unsupported. +.It Ic \&nn Op Ar number +Temporarily turn off line numbering. +Currently unsupported. +.It Ic \&nop Ar body +Execute the rest of the input line as a request, macro, or text line, +skipping the +.Ic \&nop +request and any space characters immediately following it. +This is mostly used to indent text lines inside macro definitions. +.It Ic \&nr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression Op Ar stepsize +Define or change a register. +A register is an arbitrary string value that defines some sort of state, +which influences parsing and/or formatting. +For the syntax of +.Ar expression , +see +.Sx Numerical expressions +below. +If it is prefixed by a sign, the register will be +incremented or decremented instead of assigned to. +.Pp +The +.Ar stepsize +is used by the +.Ic \en+ +auto-increment feature. +It remains unchanged when omitted while changing an existing register, +and it defaults to 0 when defining a new register. +.Pp +The following +.Ar register +is handled specially: +.Bl -tag -width Ds +.It Cm nS +If set to a positive integer value, certain +.Xr mdoc 7 +macros will behave in the same way as in the +.Em SYNOPSIS +section. +If set to 0, these macros will behave in the same way as outside the +.Em SYNOPSIS +section, even when called within the +.Em SYNOPSIS +section itself. +Note that starting a new +.Xr mdoc 7 +section with the +.Ic \&Sh +macro will reset this register. +.El +.It Xo +.Ic \&nrf Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression +.Op Ar increment +.Xc +Define or change a floating-point register. +This is a Heirloom extension and currently unsupported. +.It Ic \&nroff +Force nroff mode. +This is a groff extension and currently ignored. +.It Ic \&ns +Turn on no-space mode. +Currently ignored. +.It Ic \&nx Op Ar filename +Abort processing of the current input file and process another one. +Ignored because insecure. +.It Ic \&open Ar stream file +Open a file for writing. +Ignored because insecure. +.It Ic \&opena Ar stream file +Open a file for appending. +Ignored because insecure. +.It Ic \&os +Output saved vertical space. +Currently ignored. +.It Ic \&output Ar string +Output directly to intermediate output. +Not supported. +.It Ic \&padj Op Cm 1 | 0 +Globally control paragraph-at-once adjustment. +This is a Heirloom extension and currently ignored. +.It Ic \&papersize Ar media +Set the paper size. +This is a Heirloom extension and currently ignored. +.It Ic \&pc Op Ar char +Change the page number character. +Currently ignored. +.It Ic \&pev +Print environments. +This is a groff extension and currently ignored. +.It Ic \&pi Ar command +Pipe output to a shell command. +Ignored because insecure. +.It Ic \&PI +Low-level request used by +.Ic \&BP . +This is a Heirloom extension and currently unsupported. +.It Ic \&pl Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height +Change page length. +Currently ignored. +.It Ic \&pm +Print names and sizes of macros, strings, and diversions +to standard error output. +Currently ignored. +.It Ic \&pn Oo Cm + Ns | Ns Cm - Oc Ns Ar number +Change the page number of the next page. +Currently ignored. +.It Ic \&pnr +Print all number registers on standard error output. +Currently ignored. +.It Ic \&po Op Oo Cm + Ns | Ns Cm - Oc Ns Ar offset +Set a horizontal page offset. +If no argument is specified, the page offset is reverted to its +previous value. +If a sign is specified, the new page offset is calculated relative +to the current one; otherwise, it is absolute. +The argument follows the syntax of +.Sx Scaling Widths +and the default scaling unit is +.Cm m . +.It Ic \&ps Op Oo Cm + Ns | Ns Cm - Oc Ns size +Change point size. +Currently ignored. +.It Ic \&psbb Ar filename +Retrieve the bounding box of a PostScript file. +Currently unsupported. +.It Ic \&pshape Ar indent length ... +Set a special shape for the current paragraph. +This is a Heirloom extension and currently unsupported. +.It Ic \&pso Ar command +Include output of a shell command. +Ignored because insecure. +.It Ic \&ptr +Print the names and positions of all traps on standard error output. +This is a groff extension and currently ignored. +.It Ic \&pvs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height +Change post-vertical spacing. +This is a groff extension and currently ignored. +.It Ic \&rchar Ar glyph ... +Remove glyph definitions. +Currently unsupported. +.It Ic \&rd Op Ar prompt Op Ar argument ... +Read from standard input. +Currently ignored. +.It Ic \&recursionlimit Ar maxrec maxtail +Set the maximum stack depth for recursive macros. +This is a Heirloom extension and currently ignored. +.It Ic \&return Op Ar twice +Exit the presently executed macro and return to the caller. +The argument is currently ignored. +.It Ic \&rfschar Ar font glyph ... +Remove font-specific fallback glyph definitions. +Currently unsupported. +.It Ic \&rhang Ar font char ... afmunits +Hang characters at right margin. +This is a Heirloom extension and currently ignored. +.It Ic \&rj Op Ar N +Justify the next +.Ar N +input lines to the right margin without filling. +.Ar N +defaults to 1. +An argument of 0 or less ends right adjustment. +.It Ic \&rm Ar macroname +Remove a request, macro or string. +.It Ic \&rn Ar oldname newname +Rename a request, macro, diversion, or string. +In +.Xr mandoc 1 , +user-defined macros, +.Xr mdoc 7 +and +.Xr man 7 +macros, and user-defined strings can be renamed, but renaming of +predefined strings and of +.Nm +requests is not supported, and diversions are not implemented at all. +.It Ic \&rnn Ar oldname newname +Rename a number register. +Currently unsupported. +.It Ic \&rr Ar register +Remove a register. +.It Ic \&rs +End no-space mode. +Currently ignored. +.It Ic \&rt Op Ar dist +Return to marked vertical position. +Currently ignored. +.It Ic \&schar Ar glyph Op Ar string +Define global fallback glyph. +This is a groff extension and currently unsupported. +.It Ic \&sentchar Ar char ... +Define sentence-ending characters. +This is a Heirloom extension and currently ignored. +.It Ic \&shc Op Ar glyph +Change the soft hyphen character. +Currently ignored. +.It Ic \&shift Op Ar number +Shift macro arguments +.Ar number +times, by default once: \e\e$i becomes what \e\e$i+number was. +Also decrement \en(.$ by +.Ar number . +.It Ic \&sizes Ar size ... +Define permissible point sizes. +This is a groff extension and currently ignored. +.It Ic \&so Ar filename +Include a source file. +The file is read and its contents processed as input in place of the +.Ic \&so +request line. +To avoid inadvertent inclusion of unrelated files, +.Xr mandoc 1 +only accepts relative paths not containing the strings +.Qq ../ +and +.Qq /.. . +.Pp +This request requires +.Xr man 1 +to change to the right directory before calling +.Xr mandoc 1 , +per convention to the root of the manual tree. +Typical usage looks like: +.Pp +.Dl \&.so man3/Xcursor.3 +.Pp +As the whole concept is rather fragile, the use of +.Ic \&so +is discouraged. +Use +.Xr ln 1 +instead. +.It Ic \&sp Op Ar height +Break the output line and emit vertical space. +The argument follows the syntax of +.Sx Scaling Widths +and defaults to one blank line +.Pq Li 1v . +.It Ic \&spacewidth Op Cm 1 | 0 +Set the space width from the font metrics file. +This is a Heirloom extension and currently ignored. +.It Ic \&special Op Ar font ... +Define a special font. +This is a groff extension and currently ignored. +.It Ic \&spreadwarn Op Ar width +Warn about wide spacing between words. +Currently ignored. +.It Ic \&ss Ar wordspace Op Ar sentencespace +Set space character size. +Currently ignored. +.It Ic \&sty Ar position style +Associate style with a font position. +This is a groff extension and currently ignored. +.It Ic \&substring Ar stringname startpos Op Ar endpos +Replace a user-defined string with a substring. +Currently unsupported. +.It Ic \&sv Op Ar height +Save vertical space. +Currently ignored. +.It Ic \&sy Ar command +Execute shell command. +Ignored because insecure. +.It Ic \&T& +Re-start a table layout, retaining the options of the prior table +invocation. +See +.Ic \&TS . +.It Ic \&ta Op Ar width ... Op Cm T Ar width ... +Set tab stops. +Each +.Ar width +argument follows the syntax of +.Sx Scaling Widths . +If prefixed by a plus sign, it is relative to the previous tab stop. +The arguments after the +.Cm T +marker are used repeatedly as often as needed; for each reuse, +they are taken relative to the last previously established tab stop. +When +.Ic \&ta +is called without arguments, all tab stops are cleared. +.It Ic \&tc Op Ar glyph +Change tab repetition character. +Currently unsupported. +.It Ic \&TE +End a table context. +See +.Ic \&TS . +.It Ic \&ti Oo Cm + Ns | Ns Cm - Oc Ns Ar width +Break the output line and indent the next output line by +.Ar width . +If a sign is specified, the temporary indentation is calculated +relative to the current indentation; otherwise, it is absolute. +The argument follows the syntax of +.Sx Scaling Widths +and the default scaling unit is +.Cm m . +.It Ic \&tkf Ar font minps width1 maxps width2 +Enable track kerning for a font. +Currently ignored. +.It Ic \&tl No \& Ap Ar left Ap Ar center Ap Ar right Ap +Print a title line. +Currently unsupported. +.It Ic \&tm Ar string +Print to standard error output. +Currently ignored. +.It Ic \&tm1 Ar string +Print to standard error output, allowing leading blanks. +This is a groff extension and currently ignored. +.It Ic \&tmc Ar string +Print to standard error output without a trailing newline. +This is a groff extension and currently ignored. +.It Ic \&tr Ar glyph glyph ... +Output character translation. +The first glyph in each pair is replaced by the second one. +Character escapes can be used; for example, +.Pp +.Dl tr \e(xx\e(yy +.Pp +replaces all invocations of \e(xx with \e(yy. +.It Ic \&track Ar font minps width1 maxps width2 +Static letter space tracking. +This is a Heirloom extension and currently ignored. +.It Ic \&transchar Ar char ... +Define transparent characters for sentence-ending. +This is a Heirloom extension and currently ignored. +.It Ic \&trf Ar filename +Output the contents of a file, disallowing invalid characters. +This is a groff extension and ignored because insecure. +.It Ic \&trimat Ar left top width height +Set the TrimBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.It Ic \&trin Ar glyph glyph ... +Output character translation, ignored by +.Ic \&asciify . +Currently unsupported. +.It Ic \&trnt Ar glyph glyph ... +Output character translation, ignored by \e!. +Currently unsupported. +.It Ic \&troff +Force troff mode. +This is a groff extension and currently ignored. +.It Ic \&TS +Begin a table, which formats input in aligned rows and columns. +See +.Xr tbl 7 +for a description of the tbl language. +.It Ic \&uf Ar font +Globally set the underline font. +Currently ignored. +.It Ic \&ul Op Ar N +Underline next +.Ar N +input lines. +Currently ignored. +.It Ic \&unformat Ar divname +Unformat spaces and tabs in a diversion. +Currently unsupported. +.It Ic \&unwatch Ar macroname +Disable notification for string or macro. +This is a Heirloom extension and currently ignored. +.It Ic \&unwatchn Ar register +Disable notification for register. +This is a Heirloom extension and currently ignored. +.It Ic \&vpt Op Cm 1 | 0 +Enable or disable vertical position traps. +This is a groff extension and currently ignored. +.It Ic \&vs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height +Change vertical spacing. +Currently ignored. +.It Ic \&warn Ar flags +Set warning level. +Currently ignored. +.It Ic \&warnscale Ar si +Set the scaling indicator used in warnings. +This is a groff extension and currently ignored. +.It Ic \&watch Ar macroname +Notify on change of string or macro. +This is a Heirloom extension and currently ignored. +.It Ic \&watchlength Ar maxlength +On change, report the contents of macros and strings +up to the specified length. +This is a Heirloom extension and currently ignored. +.It Ic \&watchn Ar register +Notify on change of register. +This is a Heirloom extension and currently ignored. +.It Ic \&wh Ar dist Op Ar macroname +Set a page location trap. +Currently unsupported. +.It Ic \&while Ar condition body +Repeated execution while a +.Ar condition +is true, with syntax similar to +.Ic \&if . +Currently implemented with two restrictions: cannot nest, +and each loop must start and end in the same scope. +.It Ic \&write Oo \(dq Oc Ns Ar string +Write to an open file. +Ignored because insecure. +.It Ic \&writec Oo \(dq Oc Ns Ar string +Write to an open file without appending a newline. +Ignored because insecure. +.It Ic \&writem Ar macroname +Write macro or string to an open file. +Ignored because insecure. +.It Ic \&xflag Ar level +Set the extension level. +This is a Heirloom extension and currently ignored. +.El +.Ss Numerical expressions +The +.Ic \&nr , +.Ic \&if , +and +.Ic \&ie +requests accept integer numerical expressions as arguments. +These are always evaluated using the C +.Vt int +type; integer overflow works the same way as in the C language. +Numbers consist of an arbitrary number of digits +.Sq 0 +to +.Sq 9 +prefixed by an optional sign +.Sq + +or +.Sq - . +Each number may be followed by one optional scaling unit described below +.Sx Scaling Widths . +The following equations hold: +.Bd -literal -offset indent +1i = 6v = 6P = 10m = 10n = 72p = 1000M = 240u = 240 +254c = 100i = 24000u = 24000 +1f = 65536u = 65536 +.Ed +.Pp +The following binary operators are implemented. +Unless otherwise stated, they behave as in the C language: +.Pp +.Bl -tag -width 2n -compact +.It Ic + +addition +.It Ic - +subtraction +.It Ic * +multiplication +.It Ic / +division +.It Ic % +remainder of division +.It Ic < +less than +.It Ic > +greater than +.It Ic == +equal to +.It Ic = +equal to, same effect as +.Ic == +(this differs from C) +.It Ic <= +less than or equal to +.It Ic >= +greater than or equal to +.It Ic <> +not equal to (corresponds to C +.Ic != ; +this one is of limited portability, it is supported by Heirloom roff, +but not by groff) +.It Ic & +logical and (corresponds to C +.Ic && ) +.It Ic \&: +logical or (corresponds to C +.Ic || ) +.It Ic ? +maximum (not available in C) +.El +.Pp +There is no concept of precedence; evaluation proceeds from left to right, +except when subexpressions are enclosed in parentheses. +Inside parentheses, whitespace is ignored. +.Sh ESCAPE SEQUENCE REFERENCE +The +.Xr mandoc 1 +.Nm +parser recognises the following escape sequences. +In +.Xr mdoc 7 +and +.Xr man 7 +documents, using escape sequences is discouraged except for those +described in the +.Sx LANGUAGE SYNTAX +section above. +.Pp +A backslash followed by any character not listed here +simply prints that character itself. +.Bl -tag -width Ds +.It Ic \e +A backslash at the end of an input line can be used to continue the +logical input line on the next physical input line, joining the text +on both lines together as if it were on a single input line. +.It Ic \e +The escape sequence backslash-space +.Pq Sq \e\ \& +is an unpaddable space-sized non-breaking space character; see +.Sx Whitespace +and +.Xr mandoc_char 7 . +.It Ic \e! +Embed text up to and including the end of the input line into the +current diversion or into intermediate output without interpreting +requests, macros, and escapes. +Currently unsupported. +.It Ic \e\(dq +The rest of the input line is treated as +.Sx Comments . +.It Ic \e# +Line continuation with comment. +Discard the rest of the physical input line and continue the logical +input line on the next physical input line, joining the text on +both lines together as if it were on a single input line. +This is a groff extension. +.It Ic \e$ Ns Ar arg +Macro argument expansion, see +.Ic \&de . +.It Ic \e% +Hyphenation allowed at this point of the word; ignored by +.Xr mandoc 1 . +.It Ic \e& +Non-printing zero-width character, +often used for various kinds of escaping; see +.Sx Whitespace , +.Xr mandoc_char 7 , +and the +.Dq MACRO SYNTAX +and +.Dq Delimiters +sections in +.Xr mdoc 7 . +.It Ic \e\(aq +Acute accent special character; use +.Ic \e(aa +instead. +.It Ic \e( Ns Ar cc +.Sx Special Characters +with two-letter names, see +.Xr mandoc_char 7 . +.It Ic \e) +Zero-width space transparent to end-of-sentence detection; +ignored by +.Xr mandoc 1 . +.It Ic \e*[ Ns Ar name Ns Ic \&] +Interpolate the string with the +.Ar name . +For short names, there are variants +.Ic \e* Ns Ar c +and +.Ic \e*( Ns Ar cc . +.Pp +One string is predefined on the +.Nm +language level: +.Ic \e*(.T +expands to the name of the output device, +for example ascii, utf8, ps, pdf, html, or markdown. +.Pp +Macro sets traditionally predefine additional strings which are not +portable and differ across implementations. +Those supported by +.Xr mandoc 1 +are listed in +.Xr mandoc_char 7 . +.Pp +Strings can be defined, changed, and deleted with the +.Ic \&ds , +.Ic \&as , +and +.Ic \&rm +requests. +.It Ic \e, +Left italic correction (groff extension); ignored by +.Xr mandoc 1 . +.It Ic \e- +Special character +.Dq mathematical minus sign ; +see +.Xr mandoc_char 7 +for details. +.It Ic \e/ +Right italic correction (groff extension); ignored by +.Xr mandoc 1 . +.It Ic \e: +Breaking the line is allowed at this point of the word +without inserting a hyphen. +.It Ic \e? +Embed the text up to the next +.Ic \e? +into the current diversion without interpreting requests, macros, +and escapes. +This is a groff extension and currently unsupported. +.It Ic \e[ Ns Ar name Ns Ic \&] +.Sx Special Characters +with names of arbitrary length, see +.Xr mandoc_char 7 . +.It Ic \e^ +One-twelfth em half-narrow space character, effectively zero-width in +.Xr mandoc 1 . +.It Ic \e_ +Underline special character; use +.Ic \e(ul +instead. +.It Ic \e` +Grave accent special character; use +.Ic \e(ga +instead. +.It Ic \e{ +Begin conditional input; see +.Ic \&if . +.It Ic \e\(ba +One-sixth em narrow space character, effectively zero-width in +.Xr mandoc 1 . +.It Ic \e} +End conditional input; see +.Ic \&if . +.It Ic \e~ +Paddable non-breaking space character. +.It Ic \e0 +Digit width space character. +.It Ic \eA\(aq Ns Ar string Ns Ic \(aq +Anchor definition; ignored by +.Xr mandoc 1 . +.It Ic \ea +Leader character; ignored by +.Xr mandoc 1 . +.It Ic \eB\(aq Ns Ar string Ns Ic \(aq +Interpolate +.Sq 1 +if +.Ar string +conforms to the syntax of +.Sx Numerical expressions +explained above or +.Sq 0 +otherwise. +.It Ic \eb\(aq Ns Ar string Ns Ic \(aq +Bracket building function; ignored by +.Xr mandoc 1 . +.It Ic \eC\(aq Ns Ar name Ns Ic \(aq +.Sx Special Characters +with names of arbitrary length. +.It Ic \ec +When encountered at the end of an input text line, +the next input text line is considered to continue that line, +even if there are request or macro lines in between. +No whitespace is inserted. +.It Ic \eD\(aq Ns Ar string Ns Ic \(aq +Draw graphics function; ignored by +.Xr mandoc 1 . +.It Ic \ed +Move down by half a line; ignored by +.Xr mandoc 1 . +.It Ic \eE +Escape character intended to not be interpreted in copy mode. +In +.Xr mandoc 1 , +it currently does the same as +.Ic \e +itself. +.It Ic \ee +Backslash special character. +.It Ic \eF[ Ns Ar name Ns Ic \&] +Switch font family (groff extension); ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \eF Ns Ar c +and +.Ic \eF( Ns Ar cc . +.It Ic \ef[ Ns Ar name Ns Ic \&] +Switch to the font +.Ar name , +see +.Sx Font Selection . +For short names, there are variants +.Ic \ef Ns Ar c +and +.Ic \ef( Ns Ar cc . +An empty name +.Ic \ef[] +defaults to +.Ic \efP . +.It Ic \eg[ Ns Ar name Ns Ic \&] +Interpolate the format of a number register; ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \eg Ns Ar c +and +.Ic \eg( Ns Ar cc . +.It Ic \eH\(aq Ns Oo +|- Oc Ns Ar number Ns Ic \(aq +Set the height of the current font; ignored by +.Xr mandoc 1 . +.It Ic \eh\(aq Ns Oo Cm \&| Oc Ns Ar width Ns Ic \(aq +Horizontal motion. +If the vertical bar is given, the motion is relative to the current +indentation. +Otherwise, it is relative to the current position. +The default scaling unit is +.Cm m . +.It Ic \ek[ Ns Ar name Ns Ic \&] +Mark horizontal input place in register; ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \ek Ns Ar c +and +.Ic \ek( Ns Ar cc . +.It Ic \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns Ic \(aq +Vertical line drawing function; ignored by +.Xr mandoc 1 . +.It Ic \el\(aq Ns Ar width Ns Oo Ar c Oc Ns Ic \(aq +Draw a horizontal line of +.Ar width +using the glyph +.Ar c . +.It Ic \eM[ Ns Ar name Ns Ic \&] +Set fill (background) color (groff extension); ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \eM Ns Ar c +and +.Ic \eM( Ns Ar cc . +.It Ic \em[ Ns Ar name Ns Ic \&] +Set glyph drawing color (groff extension); ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \em Ns Ar c +and +.Ic \em( Ns Ar cc . +.It Ic \eN\(aq Ns Ar number Ns Ic \(aq +Character +.Ar number +on the current font. +.It Ic \en Ns Oo +|- Oc Ns Ic \&[ Ns Ar name Ns Ic \&] +Interpolate the number register +.Ar name . +For short names, there are variants +.Ic \en Ns Ar c +and +.Ic \en( Ns Ar cc . +If the optional sign is specified, +the register is first incremented or decremented by the +.Ar stepsize +that was specified in the relevant +.Ic \&nr +request, and the changed value is interpolated. +.It Ic \eO Ns Ar digit , Ic \eO[5 Ns arguments Ns Ic \&] +Suppress output. +This is a groff extension and currently unsupported. +With an argument of +.Ic 1 , 2 , 3 , +or +.Ic 4 , +it is ignored. +.It Ic \eo\(aq Ns Ar string Ns Ic \(aq +Overstrike, writing all the characters contained in the +.Ar string +to the same output position. +In terminal and HTML output modes, +only the last one of the characters is visible. +.It Ic \ep +Break the output line at the end of the current word. +.It Ic \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns Ic \(aq +Set number register; ignored by +.Xr mandoc 1 . +.It Ic \er +Move up by one line; ignored by +.Xr mandoc 1 . +.It Ic \eS\(aq Ns Ar number Ns Ic \(aq +Slant output; ignored by +.Xr mandoc 1 . +.It Ic \es\(aq Ns Oo +|- Oc Ns Ar number Ns Ic \(aq +Change point size; ignored by +.Xr mandoc 1 . +Alternative forms +.Ic \es Ns Oo +|- Oc Ns Ar n , +.Ic \es Ns Oo +|- Oc Ns Ic \(aq Ns Ar number Ns Ic \(aq , +.Ic \es[ Ns Oo +|- Oc Ns Ar number Ns Ic \&] , +and +.Ic \es Ns Oo +|- Oc Ns Ic \&[ Ns Ar number Ns Ic \&] +are also parsed and ignored. +.It Ic \et +Horizontal tab; ignored by +.Xr mandoc 1 . +.It Ic \eu +Move up by half a line; ignored by +.Xr mandoc 1 . +.It Ic \eV[ Ns Ar name Ns Ic \&] +Interpolate an environment variable; ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \eV Ns Ar c +and +.Ic \eV( Ns Ar cc . +.It Ic \ev\(aq Ns Ar number Ns Ic \(aq +Vertical motion; ignored by +.Xr mandoc 1 . +.It Ic \ew\(aq Ns Ar string Ns Ic \(aq +Interpolate the width of the +.Ar string . +The +.Xr mandoc 1 +implementation assumes that after expansion of user-defined strings, the +.Ar string +only contains normal characters, no escape sequences, and that each +character has a width of 24 basic units. +.It Ic \eX\(aq Ns Ar string Ns Ic \(aq +Output +.Ar string +as device control function; ignored in nroff mode and by +.Xr mandoc 1 . +.It Ic \ex\(aq Ns Ar number Ns Ic \(aq +Extra line space function; ignored by +.Xr mandoc 1 . +.It Ic \eY[ Ns Ar name Ns Ic \&] +Output a string as a device control function; ignored in nroff mode and by +.Xr mandoc 1 . +For short names, there are variants +.Ic \eY Ns Ar c +and +.Ic \eY( Ns Ar cc . +.It Ic \eZ\(aq Ns Ar string Ns Ic \(aq +Print +.Ar string +with zero width and height; ignored by +.Xr mandoc 1 . +.It Ic \ez +Output the next character without advancing the cursor position. +.El +.Sh COMPATIBILITY +The +.Xr mandoc 1 +implementation of the +.Nm +language is incomplete. +Major unimplemented features include: +.Pp +.Bl -dash -compact +.It +For security reasons, +.Xr mandoc 1 +never reads or writes external files except via +.Ic \&so +requests with safe relative paths. +.It +There is no automatic hyphenation, no adjustment to the right margin, +and very limited support for centering; the output is always set flush-left. +.It +Support for setting tabulator and leader characters is missing, +and support for manually changing indentation is limited. +.It +The +.Sq u +scaling unit is the default terminal unit. +In traditional troff systems, this unit changes depending on the +output media. +.It +Width measurements are implemented in a crude way +and often yield wrong results. +Support for explicit movement requests and escapes is limited. +.It +There is no concept of output pages, no support for floats, +graphics drawing, and picture inclusion; +terminal output is always continuous. +.It +Requests regarding color, font families, font sizes, +and glyph manipulation are ignored. +Font support is very limited. +Kerning is not implemented, and no ligatures are produced. +.It +The +.Qq \(aq +macro control character does not suppress output line breaks. +.It +Diversions and environments are not implemented, +and support for traps is very incomplete. +.It +Use of macros is not supported inside +.Xr tbl 7 +code. +.El +.Pp +The special semantics of the +.Cm nS +number register is an idiosyncrasy of +.Ox +manuals and not supported by other +.Xr mdoc 7 +implementations. +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr eqn 7 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr mdoc 7 , +.Xr tbl 7 +.Rs +.%A Joseph F. Ossanna +.%A Brian W. Kernighan +.%I AT&T Bell Laboratories +.%T Troff User's Manual +.%R Computing Science Technical Report +.%N 54 +.%C Murray Hill, New Jersey +.%D 1976 and 1992 +.%U http://www.kohala.com/start/troff/cstr54.ps +.Re +.Rs +.%A Joseph F. Ossanna +.%A Brian W. Kernighan +.%A Gunnar Ritter +.%T Heirloom Documentation Tools Nroff/Troff User's Manual +.%D September 17, 2007 +.%U http://heirloom.sourceforge.net/doctools/troff.pdf +.Re +.Sh HISTORY +The RUNOFF typesetting system, whose input forms the basis for +.Nm , +was written in MAD and FAP for the CTSS operating system by Jerome E. +Saltzer in 1964. +Doug McIlroy rewrote it in BCPL in 1969, renaming it +.Nm . +Dennis M. Ritchie rewrote McIlroy's +.Nm +in PDP-11 assembly for +.At v1 , +Joseph F. Ossanna improved roff and renamed it nroff +for +.At v2 , +then ported nroff to C as troff, which Brian W. Kernighan released with +.At v7 . +In 1989, James Clark re-implemented troff in C++, naming it groff. +.Sh AUTHORS +.An -nosplit +This +.Nm +reference was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +and +.An Ingo Schwarze Aq Mt schwarze@openbsd.org . diff --git a/static/netbsd/man7/rump_sp.7 b/static/netbsd/man7/rump_sp.7 new file mode 100644 index 00000000..6a826534 --- /dev/null +++ b/static/netbsd/man7/rump_sp.7 @@ -0,0 +1,117 @@ +.\" $NetBSD: rump_sp.7,v 1.2 2017/06/04 08:53:38 abhinav Exp $ +.\" +.\" Copyright (c) 2010 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 7, 2011 +.Dt RUMP_SP 7 +.Os +.Sh NAME +.Nm rump_sp +.Nd rump remote system call support +.Sh DESCRIPTION +The +.Nm +facility allows clients to attach to a rump kernel server over a +socket and perform system calls. +While making a local rump system call is faster than calling the +host kernel, a remote system call over a socket is slower. +This facility is therefore meant mostly for operations which are +not performance critical, such as configuration of a rump kernel +server. +.Ss Clients +The +.Nx +base system comes with multiple preinstalled clients which can be +used to configure a rump kernel and request diagnostic information. +These clients run as hybrids partially in the host system and +partially against the rump kernel. +For example, network-related clients will typically avoid making +any file system related system calls against the rump kernel, since +it is not guaranteed that a rump network server has file system +support. +Another example is DNS: since a rump server very rarely has a DNS +service configured, host networking is used to do DNS lookups. +.Pp +Some examples of clients include +.Nm rump.ifconfig +which configures interfaces, +.Nm rump.sysctl +which is used to access the +.Xr sysctl 7 +namespace +and +.Nm rump.traceroute +which is used to display a network trace starting from the rump kernel. +.Pp +Also, almost any unmodified dynamically linked application +(for example +.Xr telnet 1 +or +.Xr ls 1 ) +can be used as a rump kernel client with the help of system call hijacking. +See +.Xr rumphijack 3 +for more information. +.Ss Connecting to the server +A remote rump server is specified using an URL. +Currently two types of URLs are supported: TCP and local domain sockets. +The TCP URL is of the format tcp://ip.address:port/ and the local +domain URL is unix://path. +The latter can accept relative or absolute paths. +Note that absolute paths require three leading slashes. +.Pp +To preserve the standard usage of the rump clients' counterparts +the environment variable +.Ev RUMP_SERVER +is used to specify the server URL. +To keep track of which rump kernel the current shell is using, +modifying the shell prompt is recommended -- this is analogous +to the visual clue you have when you login from one machine to +another. +.Ss Client credentials and access control +The current scheme gives all connecting clients root credentials. +It is recommended to take precautions which prevent unauthorized +access. +For a unix domain socket it is enough to prevent access to the +socket using file system permissions. +For TCP/IP sockets the only available means is to prevent network +access to the socket with the use of firewalls. +More fine-grained access control based on cryptographic credentials +may be implemented at a future date. +.Sh EXAMPLES +Get a list of file systems supported by a rump kernel server +(in case that particular server does not support file systems, +an error will be returned): +.Bd -literal -offset indent +$ env RUMP_SERVER=unix://sock rump.sysctl vfs.generic.fstypes +.Ed +.Sh SEE ALSO +.Xr rump_server 1 , +.Xr rump 3 , +.Xr rumpclient 3 , +.Xr rumphijack 3 +.Sh HISTORY +.Nm +first appeared in +.Nx 6.0 . diff --git a/static/netbsd/man7/rumpkernel.7 b/static/netbsd/man7/rumpkernel.7 new file mode 100644 index 00000000..912bcec3 --- /dev/null +++ b/static/netbsd/man7/rumpkernel.7 @@ -0,0 +1,148 @@ +.\" $NetBSD: rumpkernel.7,v 1.5 2023/07/15 20:00:11 lukem Exp $ +.\" +.\" Copyright (c) 2008-2014 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 15, 2023 +.Dt RUMPKERNEL 7 +.Os +.Sh NAME +.Nm rump kernel +.Nd The Anykernel and Rump Kernels +.Sh DESCRIPTION +Rump kernels provide portable, componentized, kernel quality drivers +such as file systems, POSIX system call handlers, PCI device drivers, a +SCSI protocol stack, virtio and a TCP/IP stack. +The fundamental enabling technology is the anykernel architecture of +.Nx , +which enables the use of unmodified +.Nx +kernel drivers. +The minimalistic +.Xr rumpuser 3 +interface integrates a rump kernel to the host platform. +Suitable and readily supported platforms include for example POSIX +userspace (such as +.Nx ) , +hypervisors (such as Xen and KVM), and bare metal hardware. +.Pp +Rump kernels are component-oriented, which means that they consist +of libraries which are linked together to form runtime images. +If the platform supports it, dynamic linking may be used to load +components at runtime, allowing the creation of services where the +runtime component configuration is specified when the service is run (see +.Xr rump_server 1 +for an example). +.Pp +A rump kernel provides its own set of namespaces, such as a file system +hierarchy and TCP ports, that are independent of the ones on the host +and of any other rump kernel instances. +It should be noted that the presence of the provided namespaces +depends on the components that the rump kernel was constructed with. +For example, networking and file systems are components, and it is +possible to construct a rump kernel which supports neither. +.Pp +A rump kernel accepts the following bootstrap parameters. +The exact way of specifying the parameters depends on the host +platform; for example in POSIX userspace the parameters are +environment variables. +.Bl -tag -width RUMP_MEMLIMITXX +.It Dv RUMP_NCPU +If set, the value indicates the number of virtual cores configured into a +rump kernel, i.e. the number of threads which can be concurrently +executing code inside the rump kernel. +.Pp +The special value "host" can be used to specify the number of +of host cores available (note: not available on all platforms). +If this parameter is unset, two cores will be configured. +.It Dv RUMP_VERBOSE +If set to non-zero, causes bootstrap messages to be displayed on the +console. +.It Dv RUMP_MEMLIMIT +If set, indicates the maximum amount of memory that a rump kernel will +attempt to allocate from the host. +If this parameter is unset, the rump kernel attempt to allocate +host memory until allocation fails. +When the rump kernel is close to the allocation limit, or when host +allocation fails, the rump kernel will attempt to make more memory +available by invoking its internal pagedaemon to flush caches. +.El +.Sh SEE ALSO +.Lk https://rumpkernel.github.io +.Rs +.%A Antti Kantee +.%A Justin Cormack +.%T "Rump Kernels: No OS? No Problem!" +.%D October 2014 +.%I USENIX +.%J ;login: +.%N No. 5 +.%V Vol. 39 +.Re +.Rs +.%A Antti Kantee +.%D 2012 +.%J Aalto University Doctoral Dissertations +.%T Flexible Operating System Internals: The Design and Implementation of the Anykernel and Rump Kernels +.Re +.Rs +.%A Antti Kantee +.%D March 2010 +.%B Proceedings of AsiaBSDCon 2010 +.%P pp. 75-84 +.%T Rump Device Drivers: Shine On You Kernel Diamond +.Re +.Rs +.%A Arnaud Ysmal +.%A Antti Kantee +.%D September 2009 +.%B EuroBSDCon 2009 +.%T Fs-utils: File Systems Access Tools for Userland +.Re +.Rs +.%A Antti Kantee +.%D June 2009 +.%B Proceedings of the 2009 USENIX Annual Technical Conference +.%P pp. 201-214 +.%T Rump File Systems: Kernel Code Reborn +.Re +.Rs +.%A Antti Kantee +.%D May 2009 +.%B BSDCan 2009 +.%T Kernel Development in Userspace - The Rump Approach +.Re +.Rs +.%A Antti Kantee +.%D March 2009 +.%B Proceedings of AsiaBSDCon 2009 +.%P pp. 71-80 +.%T Environmental Independence: BSD Kernel TCP/IP in Userspace +.Re +.Sh HISTORY +An experimental concept for the anykernel and rump kernels was first seen +during the +.Nx 5.0 +development cycle. +A stable concept was ready for +.Nx 6.0 . diff --git a/static/netbsd/man7/scrypt.7 b/static/netbsd/man7/scrypt.7 new file mode 100644 index 00000000..9786db4a --- /dev/null +++ b/static/netbsd/man7/scrypt.7 @@ -0,0 +1,250 @@ +.\" $NetBSD: scrypt.7,v 1.3 2020/12/10 00:33:14 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SCRYPT 7" +.TH SCRYPT 7 "2020-01-23" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +scrypt \- EVP_PKEY scrypt KDF support +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1EVP_PKEY_SCRYPT\s0 algorithm implements the scrypt password based key +derivation function, as described in \s-1RFC 7914.\s0 It is memory-hard in the sense +that it deliberately requires a significant amount of \s-1RAM\s0 for efficient +computation. The intention of this is to render brute forcing of passwords on +systems that lack large amounts of main memory (such as GPUs or ASICs) +computationally infeasible. +.PP +scrypt provides three work factors that can be customized: N, r and p. N, which +has to be a positive power of two, is the general work factor and scales \s-1CPU\s0 +time in an approximately linear fashion. r is the block size of the internally +used hash function and p is the parallelization factor. Both r and p need to be +greater than zero. The amount of \s-1RAM\s0 that scrypt requires for its computation +is roughly (128 * N * r * p) bytes. +.PP +In the original paper of Colin Percival (\*(L"Stronger Key Derivation via +Sequential Memory-Hard Functions\*(R", 2009), the suggested values that give a +computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N = +2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for +this computation is roughly 1 GiB. On a more recent \s-1CPU\s0 (Intel i7\-5930K at 3.5 +GHz), this computation takes about 3 seconds. When N, r or p are not specified, +they default to 1048576, 8, and 1, respectively. The default amount of \s-1RAM\s0 that +may be used by scrypt defaults to 1025 MiB. +.SH "NOTES" +.IX Header "NOTES" +A context for scrypt can be obtained by calling: +.PP +.Vb 1 +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL); +.Ve +.PP +The output length of an scrypt key derivation is specified via the +length parameter to the \fBEVP_PKEY_derive\fR\|(3) function. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +This example derives a 64\-byte long test vector using scrypt using the password +\&\*(L"password\*(R", salt \*(L"NaCl\*(R" and N = 1024, r = 8, p = 16. +.PP +.Vb 2 +\& EVP_PKEY_CTX *pctx; +\& unsigned char out[64]; +\& +\& size_t outlen = sizeof(out); +\& pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL); +\& +\& if (EVP_PKEY_derive_init(pctx) <= 0) { +\& error("EVP_PKEY_derive_init"); +\& } +\& if (EVP_PKEY_CTX_set1_pbe_pass(pctx, "password", 8) <= 0) { +\& error("EVP_PKEY_CTX_set1_pbe_pass"); +\& } +\& if (EVP_PKEY_CTX_set1_scrypt_salt(pctx, "NaCl", 4) <= 0) { +\& error("EVP_PKEY_CTX_set1_scrypt_salt"); +\& } +\& if (EVP_PKEY_CTX_set_scrypt_N(pctx, 1024) <= 0) { +\& error("EVP_PKEY_CTX_set_scrypt_N"); +\& } +\& if (EVP_PKEY_CTX_set_scrypt_r(pctx, 8) <= 0) { +\& error("EVP_PKEY_CTX_set_scrypt_r"); +\& } +\& if (EVP_PKEY_CTX_set_scrypt_p(pctx, 16) <= 0) { +\& error("EVP_PKEY_CTX_set_scrypt_p"); +\& } +\& if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) { +\& error("EVP_PKEY_derive"); +\& } +\& +\& { +\& const unsigned char expected[sizeof(out)] = { +\& 0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00, +\& 0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe, +\& 0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30, +\& 0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62, +\& 0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88, +\& 0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda, +\& 0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d, +\& 0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40 +\& }; +\& +\& assert(!memcmp(out, expected, sizeof(out))); +\& } +\& +\& EVP_PKEY_CTX_free(pctx); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1RFC 7914\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set1_scrypt_salt\fR\|(3), +\&\fBEVP_PKEY_CTX_set_scrypt_N\fR\|(3), +\&\fBEVP_PKEY_CTX_set_scrypt_r\fR\|(3), +\&\fBEVP_PKEY_CTX_set_scrypt_p\fR\|(3), +\&\fBEVP_PKEY_CTX_set_scrypt_maxmem_bytes\fR\|(3), +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017\-2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man7/smp.7 b/static/netbsd/man7/smp.7 new file mode 100644 index 00000000..8c67dea4 --- /dev/null +++ b/static/netbsd/man7/smp.7 @@ -0,0 +1,23 @@ +* * * * * * +* * * * * * * + * * * * * * * + * * * * * * * * * * * + * * * * * * * * * * * * * + * * * * * * * * * * + * * * * * * * * + * * * * * * * * * + * * * * * * * + * * * * * * * * + * * * * * * * * + * * * * * * + * * * * * * * * + * * * * * * * * * * + * * * * * * * * * * * + * * * * * * * * * + * * * * * * * * * * * * * + * * * + * * * + * * * + * * * * * + * * * * * * * * * + * * * diff --git a/static/netbsd/man7/ssl.7 b/static/netbsd/man7/ssl.7 new file mode 100644 index 00000000..db206176 --- /dev/null +++ b/static/netbsd/man7/ssl.7 @@ -0,0 +1,153 @@ +.\" $NetBSD: ssl.7,v 1.9 2025/04/16 15:23:17 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "SSL 7" +.TH SSL 7 2025-02-11 3.0.16 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ssl \- OpenSSL SSL/TLS library +.SH SYNOPSIS +.IX Header "SYNOPSIS" +See the individual manual pages for details. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The OpenSSL \fBssl\fR library implements several versions of the +Secure Sockets Layer, Transport Layer Security, and Datagram Transport Layer +Security protocols. +This page gives a brief overview of the extensive API and data types +provided by the library. +.PP +An \fBSSL_CTX\fR object is created as a framework to establish +TLS/SSL enabled connections (see \fBSSL_CTX_new\fR\|(3)). +Various options regarding certificates, algorithms etc. can be set +in this object. +.PP +When a network connection has been created, it can be assigned to an +\&\fBSSL\fR object. After the \fBSSL\fR object has been created using +\&\fBSSL_new\fR\|(3), \fBSSL_set_fd\fR\|(3) or +\&\fBSSL_set_bio\fR\|(3) can be used to associate the network +connection with the object. +.PP +When the TLS/SSL handshake is performed using +\&\fBSSL_accept\fR\|(3) or \fBSSL_connect\fR\|(3) +respectively. +\&\fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3), \fBSSL_write_ex\fR\|(3) and \fBSSL_write\fR\|(3) are +used to read and write data on the TLS/SSL connection. +\&\fBSSL_shutdown\fR\|(3) can be used to shut down the +TLS/SSL connection. +.SH "DATA STRUCTURES" +.IX Header "DATA STRUCTURES" +Here are some of the main data structures in the library. +.IP "\fBSSL_METHOD\fR (SSL Method)" 4 +.IX Item "SSL_METHOD (SSL Method)" +This is a dispatch structure describing the internal \fBssl\fR library +methods/functions which implement the various protocol versions (SSLv3 +TLSv1, ...). It's needed to create an \fBSSL_CTX\fR. +.IP "\fBSSL_CIPHER\fR (SSL Cipher)" 4 +.IX Item "SSL_CIPHER (SSL Cipher)" +This structure holds the algorithm information for a particular cipher which +are a core part of the SSL/TLS protocol. The available ciphers are configured +on a \fBSSL_CTX\fR basis and the actual ones used are then part of the +\&\fBSSL_SESSION\fR. +.IP "\fBSSL_CTX\fR (SSL Context)" 4 +.IX Item "SSL_CTX (SSL Context)" +This is the global context structure which is created by a server or client +once per program life-time and which holds mainly default values for the +\&\fBSSL\fR structures which are later created for the connections. +.IP "\fBSSL_SESSION\fR (SSL Session)" 4 +.IX Item "SSL_SESSION (SSL Session)" +This is a structure containing the current TLS/SSL session details for a +connection: \fBSSL_CIPHER\fRs, client and server certificates, keys, etc. +.IP "\fBSSL\fR (SSL Connection)" 4 +.IX Item "SSL (SSL Connection)" +This is the main SSL/TLS structure which is created by a server or client per +established connection. This actually is the core structure in the SSL API. +At run-time the application usually deals with this structure which has +links to mostly all other structures. +.SH "HEADER FILES" +.IX Header "HEADER FILES" +Currently the OpenSSL \fBssl\fR library provides the following C header files +containing the prototypes for the data structures and functions: +.IP \fI\fR 4 +.IX Item "" +This is the common header file for the SSL/TLS API. Include it into your +program to make the API of the \fBssl\fR library available. It internally +includes both more private SSL headers and headers from the \fBcrypto\fR library. +Whenever you need hard-core details on the internals of the SSL API, look +inside this header file. +This file also includes the others listed below. +.IP \fI\fR 4 +.IX Item "" +Unused. Present for backwards compatibility only. +.IP \fI\fR 4 +.IX Item "" +This is the sub header file dealing with the SSLv3 protocol only. +.IP \fI\fR 4 +.IX Item "" +This is the sub header file dealing with the TLSv1 protocol only. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/tbl.7 b/static/netbsd/man7/tbl.7 new file mode 100644 index 00000000..8ce7bfe1 --- /dev/null +++ b/static/netbsd/man7/tbl.7 @@ -0,0 +1,455 @@ +.\" Id: tbl.7,v 1.37 2021/09/18 12:34:27 schwarze Exp +.\" +.\" Copyright (c) 2010, 2011 Kristaps Dzonsons +.\" Copyright (c) 2014,2015,2017,2018,2019 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd September 18, 2021 +.Dt TBL 7 +.Os +.Sh NAME +.Nm tbl +.Nd tbl language reference for mandoc +.Sh DESCRIPTION +The +.Nm tbl +language formats tables. +It is used within +.Xr mdoc 7 +and +.Xr man 7 +pages. +This manual describes the subset of the +.Nm +language accepted by the +.Xr mandoc 1 +utility. +.Pp +Each table is started with a +.Xr roff 7 +.Ic \&TS +macro, consist of at most one line of +.Sx Options , +one or more +.Sx Layout +lines, one or more +.Sx Data +lines, and ends with a +.Ic \&TE +macro. +All input must be 7-bit ASCII. +.Ss Options +If the first input line of a table ends with a semicolon, it contains +case-insensitive options separated by spaces, tabs, or commas. +Otherwise, it is interpreted as the first +.Sx Layout +line. +.Pp +The following options are available. +Some of them require arguments enclosed in parentheses: +.Bl -tag -width Ds +.It Cm allbox +Draw a single-line box around each table cell. +.It Cm box +Draw a single-line box around the table. +For GNU compatibility, this may also be invoked with +.Cm frame . +.It Cm center +Center the table instead of left-adjusting it. +For GNU compatibility, this may also be invoked with +.Cm centre . +.It Cm decimalpoint +Use the single-character argument as the decimal point with the +.Cm n +layout key. +This is a GNU extension. +.It Cm delim +Use the two characters of the argument as +.Xr eqn 7 +delimiters. +Currently unsupported. +.It Cm doublebox +Draw a double-line box around the table. +For GNU compatibility, this may also be invoked with +.Cm doubleframe . +.It Cm expand +Increase the width of the table to the current line length. +Currently ignored. +.It Cm linesize +Draw lines with the point size given by the unsigned integer argument. +Currently ignored. +.It Cm nokeep +Allow page breaks within the table. +This is a GNU extension and currently ignored. +.It Cm nospaces +Ignore leading and trailing spaces in data cells. +This is a GNU extension. +.It Cm nowarn +Suppress warnings about tables exceeding the current line length. +This is a GNU extension and currently ignored. +.It Cm tab +Use the single-character argument as a delimiter between data cells. +By default, the horizontal tabulator character is used. +.El +.Ss Layout +The table layout follows an +.Sx Options +line or a +.Xr roff 7 +.Ic \&TS +or +.Ic \&T& +macro. +Each layout line specifies how one line of +.Sx Data +is formatted. +The last layout line ends with a full stop. +It also applies to all remaining data lines. +Multiple layout lines can be joined by commas on a single physical +input line. +.Pp +Each layout line consists of one or more layout cell specifications, +optionally separated by whitespace. +The following case-insensitive key characters start a new cell +specification: +.Bl -tag -width 2n +.It Cm c +Center the string in this cell. +.It Cm r +Right-justify the string in this cell. +.It Cm l +Left-justify the string in this cell. +.It Cm n +Justify a number around its last decimal point. +If no decimal point is found in the number, +it is assumed to trail the number. +.It Cm s +Horizontally span columns from the last +.Pf non- Cm s +layout cell. +It is an error if a column span follows a +.Cm _ +or +.Cm = +cell, or comes first on a layout line. +The combined cell as a whole consumes only one cell +of the corresponding data line. +.It Cm a +Left-justify a string and pad with one space. +.It Cm \(ha +Vertically span rows from the last +.Pf non- Cm \(ha +layout cell. +It is an error to invoke a vertical span on the first layout line. +Unlike a horizontal span, a vertical span consumes a data cell +and discards the content. +.It Cm _ +Draw a single horizontal line in this cell. +This consumes a data cell and discards the content. +It may also be invoked with +.Cm \- . +.It Cm = +Draw a double horizontal line in this cell. +This consumes a data cell and discards the content. +.El +.Pp +Each cell key may be followed by zero or more of the following +case-insensitive modifiers: +.Bl -tag -width 2n +.It Cm b +Use a bold font for the contents of this cell. +.It Cm d +Move content down to the last row of this vertical span. +Currently ignored. +.It Cm e +Make this column wider to match the maximum width +of any other column also having the +.Cm e +modifier. +.It Cm f +The next one or two characters select the font to use for this cell. +One-character font names must be followed by a blank or period. +See the +.Xr roff 7 +manual for supported font names. +.It Cm i +Use an italic font for the contents of this cell. +.It Cm m +Specify a cell start macro. +This is a GNU extension and currently unsupported. +.It Cm p +Set the point size to the following unsigned argument, +or change it by the following signed argument. +Currently ignored. +.It Cm v +Set the vertical line spacing to the following unsigned argument, +or change it by the following signed argument. +Currently ignored. +.It Cm t +Do not vertically center content in this vertical span, +leave it in the top row. +Currently ignored. +.It Cm u +Move cell content up by half a table row. +Currently ignored. +.It Cm w +Specify a minimum column width. +.It Cm x +After determining the width of all other columns, distribute the +rest of the line length among all columns having the +.Cm x +modifier. +.It Cm z +Do not use this cell for determining the width of this column. +.It Cm \&| +Draw a single vertical line to the right of this cell. +.It Cm || +Draw a double vertical line to the right of this cell. +.El +.Pp +If a modifier consists of decimal digits, +it specifies a minimum spacing in units of +.Cm n +between this column and the next column to the right. +The default is 3. +If there is a vertical line, it is drawn inside the spacing. +.Ss Data +The data section follows the last +.Sx Layout +line. +Each data line consists of one or more data cells, delimited by +.Cm tab +characters. +.Pp +If a data cell contains only the two bytes +.Ql \e\(ha , +the cell above spans to this row, as if the layout specification +of this cell were +.Cm \(ha . +.Pp +If a data cell contains only the single character +.Ql _ +or +.Ql = , +a single or double horizontal line is drawn across the cell, +joining its neighbours. +If a data cell contains only the two character sequence +.Ql \e_ +or +.Ql \e= , +a single or double horizontal line is drawn inside the cell, +not joining its neighbours. +If a data line contains nothing but the single character +.Ql _ +or +.Ql = , +a horizontal line across the whole table is inserted +without consuming a layout row. +.Pp +In place of any data cell, a text block can be used. +It starts with +.Ic \&T{ +at the end of a physical input line. +Input line breaks inside the text block +neither end the text block nor its data cell. +It only ends if +.Ic \&T} +occurs at the beginning of a physical input line and is followed +by an end-of-cell indicator. +If the +.Ic \&T} +is followed by the end of the physical input line, the text block, +the data cell, and the data line ends at this point. +If the +.Ic \&T} +is followed by the +.Cm tab +character, only the text block and the data cell end, +but the data line continues with the data cell following the +.Cm tab +character. +If +.Ic \&T} +is followed by any other character, it does not end the text block, +which instead continues to the following physical input line. +.Sh EXAMPLES +String justification and font selection: +.Bd -literal -offset indent +\&.TS +rb c lb +r ci l. +r center l +ri ce le +right c left +\&.TE +.Ed +.Bd -filled -offset indent +.TS +rb c lb +r ci l. +r center l +ri ce le +right c left +.TE +.Ed +.Pp +Some ports in +.Ox 6.1 +to show number alignment and line drawing: +.Bd -literal -offset indent +\&.TS +box tab(:); +r| l +r n. +software:version +_ +AFL:2.39b +Mutt:1.8.0 +Ruby:1.8.7.374 +TeX Live:2015 +\&.TE +.Ed +.Bd -filled -offset indent +.TS +box tab(:); +r| l +r n. +software:version +_ +AFL:2.39b +Mutt:1.8.0 +Ruby:1.8.7.374 +TeX Live:2015 +.TE +.Ed +.sp 2v +Spans and skipping width calculations: +.Bd -literal -offset indent +\&.TS +box tab(:); +lz s | rt +lt| cb| \(ha +\(ha | rz s. +left:r +l:center: +:right +\&.TE +.Ed +.Bd -filled -offset indent +.TS +box tab(:); +lz s | rt +lt| cb| ^ +^ | rz s. +left:r +l:center: +:right +.TE +.Ed +.sp 2v +Text blocks, specifying spacings and specifying and equalizing +column widths, putting lines into individual cells, and overriding +.Cm allbox : +.Bd -literal -offset indent +\&.TS +allbox tab(:); +le le||7 lw10. +The fourth line:_:line 1 +of this column:=:line 2 +determines:\_:line 3 +the column width.:T{ +This text is too wide to fit into a column of width 17. +T}:line 4 +T{ +No break here. +T}::line 5 +\&.TE +.Ed +.Bd -filled -offset indent +.TS +allbox tab(:); +le le||7 lw10. +The fourth line:_:line 1 +of this column:=:line 2 +determines:\_:line 3 +the column width.:T{ +This text is too wide to fit into a column of width 17. +T}:line 4 +T{ +No break here. +T}::line 5 +.TE +.Ed +.sp 2v +These examples were constructed to demonstrate many +.Nm +features in a compact way. +In real manual pages, keep tables as simple as possible. +They usually look better, are less fragile, and are more portable. +.Sh COMPATIBILITY +The +.Xr mandoc 1 +implementation of +.Nm +doesn't support +.Xr mdoc 7 +and +.Xr man 7 +macros and +.Xr eqn 7 +equations inside tables. +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr mdoc 7 , +.Xr roff 7 +.Rs +.%A M. E. Lesk +.%T Tbl \(em A Program to Format Tables +.%D June 11, 1976 +.Re +.Sh HISTORY +The tbl utility, a preprocessor for troff, was originally written by M. +E. Lesk at Bell Labs in 1975. +The GNU reimplementation of tbl, part of the groff package, was released +in 1990 by James Clark. +A standalone tbl implementation was written by Kristaps Dzonsons in +2010. +This formed the basis of the implementation that first appeared in +.Ox 4.9 +as a part of the +.Xr mandoc 1 +utility. +.Sh AUTHORS +This +.Nm +reference was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +and +.An Ingo Schwarze Aq Mt schwarze@openbsd.org . +.Sh BUGS +In +.Fl T +.Cm utf8 +output mode, heavy lines are drawn instead of double lines. +This cannot be improved because the Unicode standard only provides +an incomplete set of box drawing characters with double lines, +whereas it provides a full set of box drawing characters +with heavy lines. +It is unlikely this can be improved in the future because the box +drawing characters are already marked in Unicode as characters +intended only for backward compatibility with legacy systems, +and their use is not encouraged. +So it seems unlikely that the missing ones might get added in the future. diff --git a/static/netbsd/man7/test_packets.7 b/static/netbsd/man7/test_packets.7 new file mode 100644 index 00000000..357fa402 --- /dev/null +++ b/static/netbsd/man7/test_packets.7 @@ -0,0 +1,37 @@ +; switch.ch ANY with strange RRSIG ordering. + +B0518510000100170000001A067377697463680263680000FF0001C00C0006000100015180002A067363736E6D73C00C0A686F73746D6173746572C00C77C09B050000708000001C2000093A80000000B4C00C00230001000151800024006400320173075349502B44325500045F736970045F7564700673776974636802636800C076000100010000003C0004823B8A22C076001C00010000003C0010200106200000001B000000000000000BC076002E000100015180007D00060502000151804B24A0F24AFD13F2FC60067377697463680263680077281AD5F78041CC354CA718703D133A36D0CE63C8E1FA0378DA2B3B4EB935E241225C23F786F5365D2D +F39E8A84702BEDA2591A82BCBDF4E8DD9094296CED48301DAA5DD71B0B8E60E69A858B8FD1ABD555C6711911D966FDFED53C9AC5A477C0CB002E00010002A300007D000205020002A3004B11ADE94AEA20E9FC600673776974636802636800BE4DD85BC15B5AB0575FA1E4ACE582D25A853D8A914FE431B2D057D56CE07B8017FC0994664AFB4B3B830B7E9A88B5C3FB7DACA5921B886BF6B20D4A08E24C73FCE86FDC3738DDBAAF8DB36321FABE9DCE94479C752AABB17B7FAF3D1B2B3F53C154002E00010000003C007D000105020000003C4B11ADE94AEA20E9FC60067377697463680263680000F41CF28713DCE591995F7FABB71832669065F359F2BE0F +1369BFA762005BD24ED3B9EB0E3706BC00F38810D2B60389AE55A5481B2662F76D09C632C9A0171F7ECD22D58E99106A1D5F3A4599AAD7287ECD20FB96BD6FBE4ADB87CACE63D358C1DD002E00010000012C007D000F05020000012C4B11ADE94AEA20E9FC600673776974636802636800DD53A4C140E5717101092724AD0CB23D2C47D5486711171C0BCFADA2B161202A964A663419C1A077E6D9ADAFD2749DF11930F03AED5E295A2C592E4EE9816E6AF1BF504DDEC5B99370BFA58330F165807DE37FD96BAFF859F263F37B16A37D4DC266002E00010000003C007D001C05020000003C4B11ADE94AEA20E9FC6006737769746368026368007A30FB0344B3 +5150669907042E30A66B1F674DE2E659710BC63B900522C22C209BDE6BBD7660F0BA579E2D497E3BA5C8098EE2B4F6247B6CA182AC9473B47738367FC67AB4D4CD5341B51F50A3AF16BA576E3F3C7C893E44AE04180FF631574DC2EF002E000100015180007D001D0502000151804B11ADE94AEA20E9FC60067377697463680263680028FB119F1E1F9DCDD48F3FC65030CA2AB06700A9331030EE4DFB933C6E6EA93EC22867117951F7E820D9D069DC44F78B7F5C740154AFCC7B8749DA956FFB80A9AEA311D503404A3CB8D771A1486F8E388F8CC410C7C433551FEE2DC8A8B89312C378002E000100015180007D00230502000151804B11ADE94AEA20E9FC +6006737769746368026368004930DC3A37A7BBE7585E62BFC6C024F68A421977CA990DF5D60CB6313A8F24829CAACC70F284DC4184CBA8C774BAFD72D418F81E5E14195BE398CC532824933260536DF58BD66A395D46FFDFF9F9902FD42E7C699A6A3EF50D22D3648829DAB3C401002F0001000000B4001F0672657331303203313032067377697463680263680000076201000C100380C483002E0001000000B4007D002F0502000000B44B12C1EC4AEB34ECFC600673776974636802636800039A5F99A0EAA9F55C2D138044208FC77DC2C0B85968CE642F9D6B1F7D5F83A800FD8908855FC55F7177CFCFCB5F1F2703C2BC5CDDC3346062BD1DFB28CFD91D +7E2B8DF25BEDBD2ADAC1539224DAF7BD8B4CC265955B0169DBFFF55DBEB92E6CC4B5003000010001518001080101030503010001BC06344005077BCC13F4DC094F157C2E49A33E9ED3835E32401A0BE8DB36214601E6D848CEF9A2A34788090081E953DCAD10A8A9B98E5ACBDF0B69AD0F106FC3385C3293253E0A14B78BAD1BD7CCF86B96209EAD12DFEDF02CF5B7BEB524F5753248B4354C5451277AF881CD5A4E1710C3B69ADB4FDD5C5A09B20F3324E658AD29D5E1BD4A1A17853DEF9CFBF1C80718850EE179A4486CA6CFCA577E9CDA80D35AC732D275E6678FDA0F1042880A7F4BCAF49F74CDF948D7E71586B10F9D908DC3C5C81232DC4C36218D7582 +E5CD9960272EDFD95CB613352C49393CFC07C94BF871292B8895493731EB8942D0E588DB49BFA4979AF5A7D900DCEE20FE80D6F3C4B5003000010001518000680100030503010001D7AE707CBD0F618702D448E87AF0020008AC85EBA502F5F39D2F396D1581A99F3928CDA7E2FF138224CED79D1F1CE7D303DAEE1A4323F79416FD892D7290FBEA3C00FA5DC25F4BFDA357953A047597F1560D768BCBB367102933102E8353E415C4B5003000010001518000680100030503010001E0835B08C93B89970736B288A7F8A7BC1A27B1307949EC4EC016931A5F10B722E22695741BA0CD83DFB19220F51E9320F932DCBA0F00F9888C27367DB1642A7AC623B849 +8D7006311C11248069AC5C78057652B23B2F19BE8C182F9EC474A55FC4B5002E000100015180011D00300502000151804B24A0F24AFD13F2AB3D0673776974636802636800B1F71FCBF44A0FDA3F339DC419113966FCD4DDA1A032681F5018E3FC2E3740105A2A3A3DBC66EE954BB9518C4AFA0F0463001D68BD8578D52085B73CB4777E13C07D3E479F925D3EA2133FA4D6AE1F3FF8AABD9A8CA37501131A5DA53780C6F697EABE2AE5027D96451B82EAE2E0AB9F62BA518D41C49C1D001D15F31B115F7656C6294E23C7F9CBFA7CA28A5B5F6E56A61C08238802F4342B7DF893013328BB638EA81A39ADE7BC737E097EFDA9A1F6E929AE49AE40E275369E48 +9E9ACFF2639EF00665FEFC67EB7F384AF0E4C6514445C6F4F8AA0C96137B45CD9FF1E075002FD75060E67AD07430365998CF5AE2AF1D6DC2F10CE7267BF320C40B62CF2C97C73A002E000100015180007D00300502000151804B24A0F24AFD13F2FC6006737769746368026368004AA60548E8E119C5028898B96F3E719947B0E6EE1E867B861022342D79E09B38540ABC2F7D2BE2F257F8B090AD21743A613627F03ECF18FEC2EDEB5225225F431FA76573BB94DADF6FC20FB09896D2C8248FB3DD3F0CD1CEC09CCC918299B23BC863000200010002A3000002C027C863000200010002A3000009066D6572617069C863C863001D0001000151800010001216 +138A2AAAA981D5657900994648C863000F00010000012C000C001407616C6574736368C863C863000F00010000012C000A0014056D6564656CC86306616E75626973C86300010001000151800004823B0A5C0865737472656C6C61C86300010001000151800004823B6C6FC8E8000100010002A3000004823BD30AC8E8001C00010002A300001020010620000000000000000000000005C027000100010002A3000004823B011EC027000100010002A3000004823B0A1EC027001C00010002A300001020010620000000000000000000000001C933000100010000012C0004823B6C26C933000100010000012C0004823B6C27C933001C00010000012C001020 +0106200000001402144FFFFE754774C933001C00010000012C0010200106200000001402144FFFFE754775C91B000100010000012C0004823B8A1AC91B000100010000012C0004823B8A1BC91B001C00010000012C0010200106200000001B0203BAFFFEBE9059C91B001C00010000012C0010200106200000001B0203BAFFFEBE905AC06C002E00010000012C007D002105040000012C4B11ADE94AEA20E9FC600673776974636802636800976C32190811F36B7EB9AF4D6F0A19E0CEE36B0293D8F956D43CDB55A9E7E07079590DB7EF6BC21E8AB71EEC0C7FEF4F6654C30A594118E0879FE0419B3F081C55C5C79464FB4E22B47A7342117613CA9EFAB15F +B6BD39DFC78DE09EDD8C84EEC93B002E000100015180007D00010503000151804B11ADE94AEA20E9FC6006737769746368026368002C0DBE38052528746486C66537C3605EC7B3EDCB661F9833AE84BFFAF581FEE5CE430C349B3F33E9564CFCC5D761F2FE04C7CDACE04543A2BA0386E86A74C2608ACE110A17A3E21342F4D3247D97340C2BF599FF73A46F870EB43D77CFDEA1CFC952002E000100015180007D00010503000151804B11ADE94AEA20E9FC6006737769746368026368005F3C8F014D97512C6EE50BEEB1436B2735438D21383291FC5CFFF824ED091BFBBA2EFB6F375B89CAA75A82DEED0BBDCE9CEDD342D029D7AB934FA41968A561C19840 +3FCAB16C7D6145F2F9B864CB73AB12D6BA0E4BF8B57FEF274A638A908E63C8E8002E00010002A300007D000105030002A3004B11ADE94AEA20E9FC600673776974636802636800DCA5BD623C5D2F4F05A9560A1529FD438FBC535898AD50AE9FE275372F18222302FBAA104BF199C119F69ABF8732BBB0123341F6CEDB586CD19918914C04CFBD2EBB8318C28899123F9F0F906275756DF005ACFAAF57DE18DBF32A11CB86F45EC8E8002E00010002A300007D001C05030002A3004B11ADE94AEA20E9FC60067377697463680263680086533D7CE4D47F70A42B4FE06CF2F5B3C30308130533F184D838436E61952148946224F0CEE10A2BE3931A0B2A339385 +A608C7155005EBEDCA2176A559EFAF28D5DA1E91F540874BAA1C46BB08B1BAAE1812699A18139CF02851AB058D044DB8C027002E00010002A300007D000105030002A3004B11ADE94AEA20E9FC60067377697463680263680077107EC5D87E073BDE7E022FD121A8E0D6FF851C38633197FC0C16900C916F617EBB895E985476BB68B62025C5378EBC8F6949CF045493041D7E0CBA75BA11F2DE6C0E0CBE40EE77BF9C72CF2D9789DFF31D39CFA37277FEE26D1685CAD8EF13C027002E00010002A300007D001C05030002A3004B11ADE94AEA20E9FC600673776974636802636800AF3A14ECD3CB4138D4335C4C21A8A11938100397E939D167C3AAD6BE357E +13BBDA2EC641FB23993A72ED6606C8C85E0D1660CC1770769697CEE7EB8E6474714984D7FF41FBBE48FF4A70669101BF00320340B82DC590B2C19D0006841121DC6AC933002E00010000012C007D000105030000012C4B11ADE94AEA20E9FC600673776974636802636800561C052414445D427CE00A40ACE2DA2EC168523823830CA724B087B8116F46B3CD051C5EC5874F6FC75CF6BA846279E469C474A75F9334242BB66FDD367C73B8BBC3F8748736BC5E6AED8B9B7C5FB5FE2DEDFBF46B403BC173DE958C038CFCCAC933002E00010000012C007D001C05030000012C4B11ADE94AEA20E9FC600673776974636802636800A6F44063C12A5A8BF5BCFADD +745C5B3915E463DA478131E636347EED414675023BBCA5BA2AABEC2FA3DF976A2343B4AA3403D1AFA3D470D25812BD1A319FBB5B833244D0FA18A59BB69ABB77BBDB3D7F62740D3871A69A5B9D43331D78AB8AE8C91B002E00010000012C007D000105030000012C4B11ADE94AEA20E9FC6006737769746368026368008906D2CFEFC3AA652125DD021CAB6392EBC4A9B4B3CFE3B07E4AFE7DA3263C7B8CE5DC3B66DA45D120E75B3D49ADC1F7D2E9A04A31760698FCFDEAB4AC82915D8E0AD2494DB4F11C02E115C3BD47DC8E57EDA7805BF0E7820A445F93A07698DF0000291000000080000000 + +;-- es.net IN ANY about RRSIG ordering. +687D8410000100150000000E026573036E65740000FF0001C00C00060001000151800027036E7331C00C0A686F73746D6173746572C00C77CECF4300001C2000000E100012750000000258C00C002E000100015180011A00300502000151804BE2932A4BD0101A2522026573036E657400AF2107A80A9D98A0712FF20826B95D8E686FFF023BEEAD1019045569D94D1493C84C819446ECB5489EBC6B556F4BE4B51A8E9CAC8BAA69F2B74948B78CBB197044E3D3A9E0E5EA958254637984D34BAE34167E1437D275E01C4B7C04C34053333514E1FE7EAC7C4777B02F24356F1F775526E19F54A21D3A134DC74DE153F9267008F5605D3BE38E61352BA9495D77 +97A76735BD68350CD648F40F95ADA4B25464A615E7CD4870E23C21D681F5C68C3DE9477D2EC7216FDF3269F5993428D0F1A4B7E203A04AB6807836263FDD7D6796BE6D84478B906B802DEBDCB1E0870481388503F0396CAD24147BC819A855E6CBCE98526ECAF8423450E30CB4F59C7062C069002E000100015180009A00300502000151804BE2932A4BD0101A4BA3026573036E657400602356C2D379E94F97D2900473D118288D46CFBCAAFF73D8A6FDF0B4305E8B338DD53A90106CDD78BF82A1AEC20B7C02067FDE1BEEC912E5581687BB32DD8BDC7E84B3F844F01E198E75C179194447C13B568886B33933FF35370060440D64E2DB7446962CA348C199 +DDFE4AA252AFFDEB3A818D1BF45CD795EA0907332B4508C18F002E000100015180009A00060502000151804BE2932A4BD0101A4BA3026573036E6574004FFB07563C6F88028C0E09CF163BAC777065BDCC826C583A3B3ABD525D6AF5101A6D5533888E5BAAA33DE28B52330815E14034506C4C69EDE8AD1A1F00B486C670FE0DC2F3B5F7210EBAC66695CC8679F2CA2353666A143A2E3E87377DCD8D3E6E450934BBD4CC6F9EE033E11D05CA3F44B1A64A2666E3AF2A8710F16FF8CC33C235002E000100000258009A002F0502000002584BE2932A4BD0101A4BA3026573036E6574003D2DDC713285C7338263BD338AFEEAB77571054B1F483A7BADC87BAF32 +0740A8D1B8B28CB23E04A80F90979704B44FE379103F4D91482D0EBC1D7005E326668F30B2A434F9DE76BB90DFEF2BFEDEE8CAD62164CA089651AB31498F18ED9A1E5694B4D460FFA4E667950322B2A75E8FD408B6A54EDB00257CE44AC865D1567346C2DB002E000100000258009A00100502000002584BE2932A4BD0101A4BA3026573036E6574004367180234A327C0AF72B3963518FC6E53A43E92CE6F5560E383FE8E7EF258FEA28BA666C026A90DAB67F46FBA4FF82F2704FEB3A27E25F3A8E6874B78938D70C5A20D94BEC90596B55C594F94A1438B14C8F890CE61D9630EFD897DEA9B3995D2C668469F62DB9346BB6AAF2EB6F3EE20EC31EAC80BCB +962105A64CCD5783EFC381002E000100000258009A000F0502000002584BE2932A4BD0101A4BA3026573036E657400D36D367D4D95060CB2952870BE9E826E6F7835CF6517FF83957F5097B6FC401FE5815B8895D02C68E23A47D7015A3DCE9FDE63AF9D9E1D697016444355633D0BE03177B35BE54980B241C12978A7F3EBF2420861EBFAA028CAF9FCBBF54C069869BFB7F9AB9E60D4791ACCA276AE698EB6EF7582235977E158DA8530EC84327EC427002E000100000258009A00010502000002584BE2932A4BD0101A4BA3026573036E65740068E7176D8561B49621F80DB36DC12A3C5DCD2DE5FE3973F5D7DE15769F099F2A1A9BB088042E794747E3AB +BB4AE48651F815D5D38BE7F4FB94F08F51FC209246296BE108111E90A7A5E2A5A79D305F81DBE313569B72598F36F3CFAA02FD9F321FBC2BDA10861F1D537D48DDF80BBF4B228724636FD79C06C4487365F602E6F5C4CD002E000100000258009A00020502000002584BE2932A4BD0101A4BA3026573036E657400BAA98093DDB57F38CA58C599EEED47F16AA20C1CCF668FF0A022AFAAC97059A28C50FE63034E58FBE361059B43FCBAE3876AC6AE8450987B8A00BEC29093267B9B655E645B7478294FF5E149984459A39D191585463BD80F635C21DBCF30462E60E4EACF8EECC25E4D02C181954CCBB8BDF5D19882CF6F9E982B1BEBEF14797DC573003000 +0100015180008801000305030100017D08356710D7E8A11F9B4C29E5E0F6B65F18CE64B4AAFAD7EA0E08DB85013CD777436CB8BC4EE33C0B4E6EEDFBE4227B25354F2EA2F978EE3222F3F32C1D4D3AF0F6014A527981FC5A0D2B65BF78B86A1D37965A98CAE3746CBB250655C2200FB9B8EBCC8C0AFD3182738F246AD0DAACA3199C54F08CF5F666477281872710E7C573003000010001518000880100030503010001DF43A43270EA741D5E79034C5E46A8310C9CFC7BD65C532D815D6B8C245EFF8F0C365DE400B6CDAC0124B00E08017DFB98D91133D5C18251EE0868852AD9E7FED091B393DAD1CD57381A5A1E7EA74E8FB4B708DB0F93B9EA4296EA4A71 +6E3572F168779CB5288880699413B3FFD4B7432EBE2AA2767B8EA6CB576A65C5163A3DC5730030000100015180010801010305030100017DA2FA058940109205AA36338EB8AA8B5B0D9788C4229368D371DBDE4BD24F0805C60EDD8DF223D250F23D189CDC434F388A91D6CEC1A9D6F305817409ACA784F381DFFD7EC3EC688FFE16D2AC57BD7F0B625EFC3099B3A9A5EDA1742460229669DD67D81F12069877F6AFA497F81EB12D179B183F5C8185B2786B790BEAFB6D02E0F94C780065511CF46AF80D40055022867DF712869CC262C0D315B92DFA96D58BC2336DAB5D1258DD60406913D116DC2EC1135D89C6D2092C35A19C67959743B407A3C30F3C6B8B +C4763504FE12541EDD947A5FBE8E402D31816D1824867E2CD89AEE5FF6ED7A2D683B8C5E6B7B5972BDFF355BFD9128F0D0EDB59A60F321C573003000010001518001080101030503010001DD8EC709089B6D74BAF2D294E4C626CF789B89A74B7E320D7002A03D0F94EA62DF1F19717FE8C4BFD732DA495E481353C78167255CC6256A98ACBFF5977B81A48C5E2A5AF23E8377423C4034D5D84E9E3548B9D0A07955586F67324B6B5720CC4456D86AEE3A21A4EBED9BA13358C8127D182A5083739B042D7E06307E417D020DD68EC0628E9C8279AF0F7E608A3C5D51AB33BF7C32EBD27B45D72B1AD5752BB485D52488FBA9A1B5BF3B2B50F074F481171E4B65 +3AF846E58FE46DEB3491FA683959B38B893BF55721CED8FC4A64DBEDB6BF1C7FADE650EE219A01E81DD0212B89259319CA5DC81F26821A5CC29B4CC1059AE28227B89B8816039E43C35E33C57300300001000151800108018103050301000188F31BEFA3466D6FCAF11E0D1954D2011D6EAECF922D9E1B8D620095A0D15E7CFF8EA33F8E2A8C3B3F45A1ADACFED62E3E4EDC884AEF8A7CADBCFF8EDF2158730136D01BDB6D057BEBF3D35A92ADB5E8ACB1152FE1244B2D36DCB500E952CFB6D744BF7DBAB24A901B984F869FF47113C9515D53FE1A57293B01C24195A1D40580566CDAE5B04348CB60507267BB38F34839EE959D43FB9605652157014059FDBD +39EB0836D4043A63F8660D241006F757DB92B35B39B5ABCA32A16A81C65C9F53DA79A99F1134CF3ED5304F189434AF787A3A10D63862E6C2E5FBA08B6EF6701783DB00CB41851DF13070947EEC090FCED3539F3F494170BD90E68F99453DF9C573002F00010000025800220B726573657276652D3132380231340131026573036E657400000762018000000380CA7C0010000100000258009C9B763D73706631206D7820613A6D61696C312E65732E6E657420613A6D61696C322E65732E6E657420613A6D61696C332E65732E6E657420613A6D61696C342E65732E6E657420613A6D61696C2E65732E6E657420613A6D61696C67772E65732E6E657420613A +706F7374616C312E65732E6E657420613A706F7374616C322E65732E6E657420613A706F7374616C332E65732E6E6574207E616C6CCA7C000F00010000025800090032046D61696CCA7CCA7C00010001000002580004C6800370CA7C00020001000002580009066E732D616F61CA7CCA7C00020001000002580002C024CA7C00020001000002580009066E732D6C766BCA7CCB4300010001000002580004C0BC1609CB43001C000100000258001020010400FFFFFFFFFFFFFFFFFFFFFF81C02400010001000151800004C680020AC024001C000100000258001020010400001400020000000000000010CB6600010001000002580004C67CFC16CB66001C0001 +00000258001020010400600000000000000000000022CB8900010001000002580004C681FC22CB89001C000100000258001020010400091000010000000000000002CB43002E000100000258009A00010503000002584BE2932A4BD0101A4BA3026573036E657400B425467E45E411066B99B85420FB7E844D734F414FFAF6B9528867B3DF808733BF479A0F125C84179401306579994AB8D84DF0173E2824527CEDA45C75ED4D818722EEB2D5A37641108B112D9A6D832D29A507C35DBBEBD46D50DE9915E924F53F55B5A2A263A48B48209FB50A13A7DF40AE697B1BCCE71A2B95C1BB9E47ACCACB43002E000100000258009A001C0503000002584BE2932A +4BD0101A4BA3026573036E6574002588E73F85BE8FAFD09628232906913DB78592B59F9C3C95A4AD1334D383C1326EE0C6FCF38892D8BB74631D680A6E4DB2D603D32394BC7B4EC798A1511667D246A0C30B33D03AB144C3704AA80AFCA27F197B2F83F20A9F0D2835C7C0A9B49E47E7CF2E192DC7DBF4635C39ECCCB291DB4B2832E0B8FF430A75726500194D9EC024002E000100015180009A00010503000151804BE2932A4BD0101A4BA3026573036E6574000E9F4098B1EF4F429B802007E3A9EA8E267A1F78EA7241AADD120A74CEBF70DC1DF76065A2CE0CDAA51AAB2F68411D9DEDC1F9DBEB3AB114A1FCBE122610756DE205EEC576CA5E62BD02497F +84D5DDB7110AC7F2BF02485B3E7B28FC1EB2999724B64D811270B085D1D10E184295D423F0141D652BD7E97633AC2E98C2819EDAC024002E000100000258009A001C0503000002584BE2932A4BD0101A4BA3026573036E657400936ADA283A90836E92BD42E2B6C8A0299147BCB8E47D9D4464C4151FCC99DC4F2D1C39FB691F6E322715B22F61E7BB8D5507982A3119674B350C569BDC2CD95C708EC73B4E5DEA516D053A4FD725326FFC5B0D0562B542BA96124D9FFBBF787CA0BBE6960951CC2FDD074376A1D184287C2C56A93FBBC1C7FFAA6977B30AE808CB66002E000100000258009A00010503000002584BE2932A4BD0101A4BA3026573036E657400 +0CE145578E56BB359606C9B85538450D2BCA3E9AD0DEFC8FF865DA646F900B9CBC7325B7F04706B60E2770107E62894FE9CF3B1A432F0FB53C5C7A8F37D0F60354C7D52F4DF88BDD4C46774AA728DFC1C807EF5276641CA28774F323C7326B7C1D99DFCB9498C6E096392009AA972B83F0583A5D1002CA26B59B5C97F6A8309C0000291000000080000000 + diff --git a/static/netbsd/man7/test_signatures.7 b/static/netbsd/man7/test_signatures.7 new file mode 100644 index 00000000..8c629980 --- /dev/null +++ b/static/netbsd/man7/test_signatures.7 @@ -0,0 +1,32 @@ +; Signature test file + +; first entry is a DNSKEY answer, with the DNSKEY rrset used for verification. +; later entries are verified with it. + +; DSA Key from ldns tool, key used in the testbound tests. + +; DSA key from ldns tool +ENTRY_BEGIN +SECTION QUESTION +example.com. IN DNSKEY +SECTION ANSWER +example.com. 3600 IN DNSKEY 256 3 3 ALXLUsWqUrY3JYER3T4TBJIIs70j+sDS/UT2QRp61SE7S3EEXopNXoFE73JLRmvpi/UrOO/Vz4Se6wXv/CYCKjGw06U4WRgRYXcpEhJROyNapmdIKSxhOzfLVE1gqA0PweZR8dtY3aNQSRn3sPpwJr6Mi/PqQKAMMrZ9ckJpf1+bQMOOvxgzz2U1GS18b3yZKcgTMEaJzd/GZYzi/BN2DzQ0MsrSwYXfsNLFOBbs8PJMW4LYIxeeOe6rUgkWOF7CC9Dh/dduQ1QrsJhmZAEFfd6ByYV+ ;{id = 2854 (zsk), size = 1688b} +ENTRY_END + +; entry to test +ENTRY_BEGIN +SECTION QUESTION +example.com. IN NS +SECTION ANSWER +example.com. IN NS ns.example.com. +example.com. 3600 IN RRSIG NS 3 2 3600 20070926134150 20070829134150 2854 example.com. MC0CFQCN+qHdJxoI/2tNKwsb08pra/G7aAIUAWA5sDdJTbrXA1/3OaesGBAO3sI= ;{id = 2854} +ENTRY_END + +ENTRY_BEGIN +SECTION QUESTION +ns.example.com. IN A +SECTION ANSWER +ns.example.com. IN A 1.2.3.4 +ns.example.com. 3600 IN RRSIG A 3 3 3600 20070926135752 20070829135752 2854 example.com. MC0CFQCMSWxVehgOQLoYclB9PIAbNP229AIUeH0vNNGJhjnZiqgIOKvs1EhzqAo= ;{id = 2854} +ENTRY_END + diff --git a/static/netbsd/man7/text-dump-0.7 b/static/netbsd/man7/text-dump-0.7 new file mode 100644 index 00000000..a48a7b0a --- /dev/null +++ b/static/netbsd/man7/text-dump-0.7 @@ -0,0 +1,9 @@ +.\" $NetBSD: text-dump-0.7,v 1.2 2017/01/28 21:31:51 christos Exp $ +.\" +changepw/kerberos@EXAMPLE.ORG 1::3:2376E6A4C1D5456D:-::2:2376E6A4C1D5456D:-::1:2376E6A4C1D5456D:-::18:39C3D293A6B0CEE734C7874764A8B5449F348AC00A6EA94F7451D07BE31EF239:-::16:108373F74F105875DCCE866B160886C7BC6780E526D0DAEA:-::23:D279B73431AA349F63594EA800397195:- 20050728203748:kadmin/admin@EXAMPLE.ORG 20050728203748:kadmin/admin@EXAMPLE.ORG - - - 3600 3600 639 20050728203748:743456:2 +default@EXAMPLE.ORG 0::3:3B2A671585E93D6B:3/"EXAMPLE.ORGdefault"::2:3B2A671585E93D6B:3/"EXAMPLE.ORGdefault"::1:3B2A671585E93D6B:3/"EXAMPLE.ORGdefault"::18:AF401411D3F29C204611A9BA1EF54AEDEC43A01B0123C57B994B2EE104E7F127:3/"EXAMPLE.ORGdefault"::16:02401CAD7A92760E464025760BCD3BE5DF616DD5A798C719:3/"EXAMPLE.ORGdefault"::23:31D6CFE0D16AE931B73C59D7E0C089C0:3/"EXAMPLE.ORGdefault" 20050728203748:kadmin/admin@EXAMPLE.ORG - - - - 86400 604800 254 20050728203748:863727:0 +kadmin/admin@EXAMPLE.ORG 1::3:2FCD23DCC2C726CE:-::2:2FCD23DCC2C726CE:-::1:2FCD23DCC2C726CE:-::18:1675F5E5BAD61428DE51F7C8EDCD53F23426D90F4F0BB4F9C73514D317E0482A:-::16:C79D6B0879B6ABADCE4A9B436B5B4A4F792679CDBC7F5D10:-::23:265C712FED225A85567BAF8CD9A4C4ED:- 20050728203748:kadmin/admin@EXAMPLE.ORG 20050728203748:kadmin/admin@EXAMPLE.ORG - - - 3600 3600 382 20050728203748:682995:2 +kadmin/changepw@EXAMPLE.ORG 1::3:57A132CB9D7F4F37:-::2:57A132CB9D7F4F37:-::1:57A132CB9D7F4F37:-::18:B8252C9E3EC99969053631C238BBF88A0AAA082A8F1C4ED8D1729170C79519B8:-::16:10CE89987A1FD0986E6D836DB3F473E04C648C34F17CBCE3:-::23:A6D2BCA6F54B1C1AA5E875F116EEDE82:- 20050728203748:kadmin/admin@EXAMPLE.ORG 20050728203748:kadmin/admin@EXAMPLE.ORG - - - 300 300 867 20050728203748:623022:2 +kadmin/hprop@EXAMPLE.ORG 1::3:76DC5751EFE52931:-::2:76DC5751EFE52931:-::1:76DC5751EFE52931:-::18:9B4D02F7D74790AB929E607BE5940CFF66801C237840EE968FDEFD7ED1387350:-::16:4CD575703D197F2991D5233704BAE379DF4FFBE616256762:-::23:E3D49F7E3462823492F33FAD8F0A754F:- 20050728203748:kadmin/admin@EXAMPLE.ORG 20050728203748:kadmin/admin@EXAMPLE.ORG - - - 3600 3600 383 20050728203748:803541:2 +krbtgt/EXAMPLE.ORG@EXAMPLE.ORG 1::3:C219830E0E73DCEC:-::2:C219830E0E73DCEC:-::1:C219830E0E73DCEC:-::18:56CD702EE58B6EF4CAF758DA0BA1B92B21EFC1D2E9FCC0785009BC391F8571B8:-::16:29E9A2F45B2561D5B592C1070708B94A894AE046D091CE7C:-::23:30A2FB86CDC17B4EC625DC66C47AAF37:- 20050728203748:kadmin/admin@EXAMPLE.ORG 20050728203748:kadmin/admin@EXAMPLE.ORG - - - 86400 2592000 126 20050728203748:560639:2 +lha@EXAMPLE.ORG 1::3:80AB08A261D6A82F:3/"EXAMPLE.ORGlha"::2:80AB08A261D6A82F:3/"EXAMPLE.ORGlha"::1:80AB08A261D6A82F:3/"EXAMPLE.ORGlha"::18:96653BEA5A46E5DF97D535C6C49F007E02F0E56B21F498C14F8C014871FE9889:3/"EXAMPLE.ORGlha"::16:7545202640A81304AE987F231FCB1F625D02CE7FF8A4ABEA:3/"EXAMPLE.ORGlha"::23:AC8E657F83DF82BEEA5D43BDAF7800CC:3/"EXAMPLE.ORGlha" 20050728203752:kadmin/admin@EXAMPLE.ORG 20050728203758:kadmin/admin@EXAMPLE.ORG - - - 86400 604800 126 20050728203752:988968:1 diff --git a/static/netbsd/man7/x509.7 b/static/netbsd/man7/x509.7 new file mode 100644 index 00000000..38378d30 --- /dev/null +++ b/static/netbsd/man7/x509.7 @@ -0,0 +1,133 @@ +.\" $NetBSD: x509.7,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509 7" +.TH X509 7 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +x509 \- X.509 certificate handling +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +An X.509 certificate is a structured grouping of information about +an individual, a device, or anything one can imagine. An X.509 CRL +(certificate revocation list) is a tool to help determine if a +certificate is still valid. The exact definition of those can be +found in the X.509 document from ITU\-T, or in RFC3280 from PKIX. +In OpenSSL, the type X509 is used to express such a certificate, and +the type X509_CRL is used to express a CRL. +.PP +A related structure is a certificate request, defined in PKCS#10 from +RSA Security, Inc, also reflected in RFC2896. In OpenSSL, the type +X509_REQ is used to express such a certificate request. +.PP +To handle some complex parts of a certificate, there are the types +X509_NAME (to express a certificate name), X509_ATTRIBUTE (to express +a certificate attribute), X509_EXTENSION (to express a certificate +extension) and a few more. +.PP +Finally, there\*(Aqs the supertype X509_INFO, which can contain a CRL, a +certificate and a corresponding private key. +.PP +\&\fBX509_\fR\fIXXX\fR, \fBd2i_X509_\fR\fIXXX\fR, and \fBi2d_X509_\fR\fIXXX\fR functions +handle X.509 certificates, with some exceptions, shown below. +.PP +\&\fBX509_CRL_\fR\fIXXX\fR, \fBd2i_X509_CRL_\fR\fIXXX\fR, and \fBi2d_X509_CRL_\fR\fIXXX\fR +functions handle X.509 CRLs. +.PP +\&\fBX509_REQ_\fR\fIXXX\fR, \fBd2i_X509_REQ_\fR\fIXXX\fR, and \fBi2d_X509_REQ_\fR\fIXXX\fR +functions handle PKCS#10 certificate requests. +.PP +\&\fBX509_NAME_\fR\fIXXX\fR functions handle certificate names. +.PP +\&\fBX509_ATTRIBUTE_\fR\fIXXX\fR functions handle certificate attributes. +.PP +\&\fBX509_EXTENSION_\fR\fIXXX\fR functions handle certificate extensions. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_NAME_ENTRY_get_object\fR\|(3), +\&\fBX509_NAME_add_entry_by_txt\fR\|(3), +\&\fBX509_NAME_add_entry_by_NID\fR\|(3), +\&\fBX509_NAME_print_ex\fR\|(3), +\&\fBX509_NAME_new\fR\|(3), +\&\fBPEM_X509_INFO_read\fR\|(3), +\&\fBd2i_X509\fR\|(3), +\&\fBd2i_X509_ALGOR\fR\|(3), +\&\fBd2i_X509_CRL\fR\|(3), +\&\fBd2i_X509_NAME\fR\|(3), +\&\fBd2i_X509_REQ\fR\|(3), +\&\fBd2i_X509_SIG\fR\|(3), +\&\fBcrypto\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2003\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man7/zpool-features.7 b/static/netbsd/man7/zpool-features.7 new file mode 100644 index 00000000..04cb681a --- /dev/null +++ b/static/netbsd/man7/zpool-features.7 @@ -0,0 +1,566 @@ +'\" te +.\" Copyright (c) 2012, Martin Matuska . +.\" All Rights Reserved. +.\" +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.\" +.\" Copyright (c) 2012 by Delphix. All rights reserved. +.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. +.\" Copyright (c) 2013, Joyent, Inc. All rights reserved. +.\" +.\" $FreeBSD: head/cddl/contrib/opensolaris/cmd/zpool/zpool-features.7 301104 2016-06-01 06:18:34Z allanjude $ +.\" +.Dd May 31, 2016 +.Dt ZPOOL-FEATURES 7 +.Os +.Sh NAME +.Nm zpool-features +.Nd ZFS pool feature descriptions +.Sh DESCRIPTION +ZFS pool on\-disk format versions are specified via "features" which replace +the old on\-disk format numbers (the last supported on\-disk format number is +28). +To enable a feature on a pool use the +.Cm upgrade +subcommand of the +.Xr zpool 8 +command, or set the +.Sy feature@feature_name +property to +.Ar enabled . +.Pp +The pool format does not affect file system version compatibility or the ability +to send file systems between pools. +.Pp +Since most features can be enabled independently of each other the on\-disk +format of the pool is specified by the set of all features marked as +.Sy active +on the pool. If the pool was created by another software version this set may +include unsupported features. +.Ss Identifying features +Every feature has a guid of the form +.Sy com.example:feature_name . +The reverse DNS name ensures that the feature's guid is unique across all ZFS +implementations. When unsupported features are encountered on a pool they will +be identified by their guids. +Refer to the documentation for the ZFS implementation that created the pool +for information about those features. +.Pp +Each supported feature also has a short name. +By convention a feature's short name is the portion of its guid which follows +the ':' (e.g. +.Sy com.example:feature_name +would have the short name +.Sy feature_name ), +however a feature's short name may differ across ZFS implementations if +following the convention would result in name conflicts. +.Ss Feature states +Features can be in one of three states: +.Bl -tag -width "XXXXXXXX" +.It Sy active +This feature's on\-disk format changes are in effect on the pool. +Support for this feature is required to import the pool in read\-write mode. +If this feature is not read-only compatible, support is also required to +import the pool in read\-only mode (see "Read\-only compatibility"). +.It Sy enabled +An administrator has marked this feature as enabled on the pool, but the +feature's on\-disk format changes have not been made yet. +The pool can still be imported by software that does not support this feature, +but changes may be made to the on\-disk format at any time which will move +the feature to the +.Sy active +state. +Some features may support returning to the +.Sy enabled +state after becoming +.Sy active . +See feature\-specific documentation for details. +.It Sy disabled +This feature's on\-disk format changes have not been made and will not be made +unless an administrator moves the feature to the +.Sy enabled +state. +Features cannot be disabled once they have been enabled. +.El +.Pp +The state of supported features is exposed through pool properties of the form +.Sy feature@short_name . +.Ss Read\-only compatibility +Some features may make on\-disk format changes that do not interfere with other +software's ability to read from the pool. +These features are referred to as "read\-only compatible". +If all unsupported features on a pool are read\-only compatible, the pool can +be imported in read\-only mode by setting the +.Sy readonly +property during import (see +.Xr zpool 8 +for details on importing pools). +.Ss Unsupported features +For each unsupported feature enabled on an imported pool a pool property +named +.Sy unsupported@feature_guid +will indicate why the import was allowed despite the unsupported feature. +Possible values for this property are: +.Bl -tag -width "XXXXXXXX" +.It Sy inactive +The feature is in the +.Sy enabled +state and therefore the pool's on\-disk format is still compatible with +software that does not support this feature. +.It Sy readonly +The feature is read\-only compatible and the pool has been imported in +read\-only mode. +.El +.Ss Feature dependencies +Some features depend on other features being enabled in order to function +properly. +Enabling a feature will automatically enable any features it depends on. +.Sh FEATURES +The following features are supported on this system: +.Bl -tag -width "XXXXXXXX" +.It Sy async_destroy +.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:async_destroy" +.It GUID Ta com.delphix:async_destroy +.It READ\-ONLY COMPATIBLE Ta yes +.It DEPENDENCIES Ta none +.El +.Pp +Destroying a file system requires traversing all of its data in order to +return its used space to the pool. +Without +.Sy async_destroy +the file system is not fully removed until all space has been reclaimed. +If the destroy operation is interrupted by a reboot or power outage the next +attempt to open the pool will need to complete the destroy operation +synchronously. +.Pp +When +.Sy async_destroy +is enabled the file system's data will be reclaimed by a background process, +allowing the destroy operation to complete without traversing the entire file +system. +The background process is able to resume interrupted destroys after the pool +has been opened, eliminating the need to finish interrupted destroys as part +of the open operation. +The amount of space remaining to be reclaimed by the background process is +available through the +.Sy freeing +property. +.Pp +This feature is only +.Sy active +while +.Sy freeing +is non\-zero. +.It Sy empty_bpobj +.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:empty_bpobj" +.It GUID Ta com.delphix:empty_bpobj +.It READ\-ONLY COMPATIBLE Ta yes +.It DEPENDENCIES Ta none +.El +.Pp +This feature increases the performance of creating and using a large number +of snapshots of a single filesystem or volume, and also reduces the disk +space required. +.Pp +When there are many snapshots, each snapshot uses many Block Pointer Objects +.Pq bpobj's +to track blocks associated with that snapshot. +However, in common use cases, most of these bpobj's are empty. +This feature allows us to create each bpobj on-demand, thus eliminating the +empty bpobjs. +.Pp +This feature is +.Sy active +while there are any filesystems, volumes, or snapshots which were created +after enabling this feature. +.It Sy filesystem_limits +.Bl -column "READ\-ONLY COMPATIBLE" "com.joyent:filesystem_limits" +.It GUID Ta com.joyent:filesystem_limits +.It READ\-ONLY COMPATIBLE Ta yes +.It DEPENDENCIES Ta extensible_dataset +.El +.Pp +This feature enables filesystem and snapshot limits. +These limits can be used +to control how many filesystems and/or snapshots can be created at the point in +the tree on which the limits are set. +.Pp +This feature is +.Sy active +once either of the limit properties has been +set on a dataset. +Once activated the feature is never deactivated. +.It Sy lz4_compress +.Bl -column "READ\-ONLY COMPATIBLE" "org.illumos:lz4_compress" +.It GUID Ta org.illumos:lz4_compress +.It READ\-ONLY COMPATIBLE Ta no +.It DEPENDENCIES Ta none +.El +.Pp +.Sy lz4 +is a high-performance real-time compression algorithm that +features significantly faster compression and decompression as well as a +higher compression ratio than the older +.Sy lzjb +compression. +Typically, +.Sy lz4 +compression is approximately 50% faster on +compressible data and 200% faster on incompressible data than +.Sy lzjb . +It is also approximately 80% faster on decompression, while +giving approximately 10% better compression ratio. +.Pp +When the +.Sy lz4_compress +feature is set to +.Sy enabled , +the +administrator can turn on +.Sy lz4 +compression on any dataset on the +pool using the +.Xr zfs 8 +command. +Also, all newly written metadata +will be compressed with +.Sy lz4 +algorithm. +Since this feature is not read-only compatible, this +operation will render the pool unimportable on systems without support +for the +.Sy lz4_compress +feature. +Booting off of +.Sy lz4 +-compressed root pools is supported. +.Pp +This feature becomes +.Sy active +as soon as it is enabled and will +never return to being +.Sy enabled . +.It Sy multi_vdev_crash_dump +.Bl -column "READ\-ONLY COMPATIBLE" "com.joyent:multi_vdev_crash_dump" +.It GUID Ta com.joyent:multi_vdev_crash_dump +.It READ\-ONLY COMPATIBLE Ta no +.It DEPENDENCIES Ta none +.El +.Pp +This feature allows a dump device to be configured with a pool comprised +of multiple vdevs. +Those vdevs may be arranged in any mirrored or raidz +configuration. +.\" TODO: this is not yet supported on FreeBSD. +.\" .Pp +.\" When the +.\" .Sy multi_vdev_crash_dump +.\" feature is set to +.\" .Sy enabled , +.\" the administrator can use the +.\" .Xr dumpon 8 +.\" command to configure a +.\" dump device on a pool comprised of multiple vdevs. +.It Sy spacemap_histogram +.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:spacemap_histogram" +.It GUID Ta com.delphix:spacemap_histogram +.It READ\-ONLY COMPATIBLE Ta yes +.It DEPENDENCIES Ta none +.El +.Pp +This features allows ZFS to maintain more information about how free space +is organized within the pool. If this feature is +.Sy enabled , +ZFS will +set this feature to +.Sy active +when a new space map object is created or +an existing space map is upgraded to the new format. +Once the feature is +.Sy active , +it will remain in that state until the pool is destroyed. +.It Sy extensible_dataset +.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:extensible_dataset" +.It GUID Ta com.delphix:extensible_dataset +.It READ\-ONLY COMPATIBLE Ta no +.It DEPENDENCIES Ta none +.El +.Pp +This feature allows more flexible use of internal ZFS data structures, +and exists for other features to depend on. +.Pp +This feature will be +.Sy active +when the first dependent feature uses it, +and will be returned to the +.Sy enabled +state when all datasets that use +this feature are destroyed. +.It Sy bookmarks +.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:bookmarks" +.It GUID Ta com.delphix:bookmarks +.It READ\-ONLY COMPATIBLE Ta yes +.It DEPENDENCIES Ta extensible_dataset +.El +.Pp +This feature enables use of the +.Nm zfs +.Cm bookmark +subcommand. +.Pp +This feature is +.Sy active +while any bookmarks exist in the pool. +All bookmarks in the pool can be listed by running +.Nm zfs +.Cm list +.Fl t No bookmark Fl r Ar poolname . +.It Sy enabled_txg +.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:enabled_txg" +.It GUID Ta com.delphix:enabled_txg +.It READ\-ONLY COMPATIBLE Ta yes +.It DEPENDENCIES Ta none +.El +.Pp +Once this feature is enabled ZFS records the transaction group number +in which new features are enabled. This has no user-visible impact, +but other features may depend on this feature. +.Pp +This feature becomes +.Sy active +as soon as it is enabled and will +never return to being +.Sy enabled . +.It Sy hole_birth +.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:hole_birth" +.It GUID Ta com.delphix:hole_birth +.It READ\-ONLY COMPATIBLE Ta no +.It DEPENDENCIES Ta enabled_txg +.El +.Pp +This feature improves performance of incremental sends +.Pq Dq zfs send -i +and receives for objects with many holes. +The most common case of +hole-filled objects is zvols. +.Pp +An incremental send stream from snapshot +.Sy A +to snapshot +.Sy B +contains information about every block that changed between +.Sy A +and +.Sy B . +Blocks which did not change between those snapshots can be +identified and omitted from the stream using a piece of metadata called +the 'block birth time', but birth times are not recorded for holes +.Pq blocks filled only with zeroes . +Since holes created after +.Sy A +cannot be +distinguished from holes created before +.Sy A , +information about every +hole in the entire filesystem or zvol is included in the send stream. +.Pp +For workloads where holes are rare this is not a problem. +However, when +incrementally replicating filesystems or zvols with many holes +.Pq for example a zvol formatted with another filesystem +a lot of time will +be spent sending and receiving unnecessary information about holes that +already exist on the receiving side. +.Pp +Once the +.Sy hole_birth +feature has been enabled the block birth times +of all new holes will be recorded. +Incremental sends between snapshots +created after this feature is enabled will use this new metadata to avoid +sending information about holes that already exist on the receiving side. +.Pp +This feature becomes +.Sy active +as soon as it is enabled and will +never return to being +.Sy enabled . +.It Sy embedded_data +.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:embedded_data" +.It GUID Ta com.delphix:embedded_data +.It READ\-ONLY COMPATIBLE Ta no +.It DEPENDENCIES Ta none +.El +.Pp +This feature improves the performance and compression ratio of +highly-compressible blocks. +Blocks whose contents can compress to 112 bytes +or smaller can take advantage of this feature. +.Pp +When this feature is enabled, the contents of highly-compressible blocks are +stored in the block "pointer" itself +.Po a misnomer in this case, as it contains +the compressed data, rather than a pointer to its location on disk +.Pc . +Thus +the space of the block +.Pq one sector, typically 512 bytes or 4KB +is saved, +and no additional i/o is needed to read and write the data block. +.Pp +This feature becomes +.Sy active +as soon as it is enabled and will +never return to being +.Sy enabled . +.It Sy large_blocks +.Bl -column "READ\-ONLY COMPATIBLE" "org.open-zfs:large_block" +.It GUID Ta org.open-zfs:large_block +.It READ\-ONLY COMPATIBLE Ta no +.It DEPENDENCIES Ta extensible_dataset +.El +.Pp +The +.Sy large_block +feature allows the record size on a dataset to be +set larger than 128KB. +.Pp +This feature becomes +.Sy active +once a +.Sy recordsize +property has been set larger than 128KB, and will return to being +.Sy enabled +once all filesystems that have ever had their recordsize larger than 128KB +are destroyed. +.Pp +Please note that booting from datasets that have recordsize greater than +128KB is +.Em NOT +supported by the +.Fx +boot loader. +.It Sy sha512 +.Bl -column "READ\-ONLY COMPATIBLE" "org.illumos:sha512" +.It GUID Ta org.illumos:sha512 +.It READ\-ONLY COMPATIBLE Ta no +.It DEPENDENCIES Ta none +.El +.Pp +The +.Sy sha512 +feature enables the use of the SHA-512/256 truncated hash algorithm +.Pq FIPS 180-4 +for checksum and dedup. +The native 64-bit arithmetic of SHA-512 provides an approximate 50% +performance boost over SHA-256 on 64-bit hardware and is thus a good +minimum-change replacement candidate for systems where hash performance is +important, but these systems cannot for whatever reason utilize the faster +.Sy skein +algorithms. +.Pp +When the +.Sy sha512 +feature is set to +.Sy enabled , +the administrator can turn on the +.Sy sha512 +checksum on any dataset using the +.Dl # zfs set checksum=sha512 Ar dataset +command. +This feature becomes +.Sy active +once a +.Sy checksum +property has been set to +.Sy sha512 , +and will return to being +.Sy enabled +once all filesystems that have ever had their checksum set to +.Sy sha512 +are destroyed. +.Pp +Booting off of a pools utilizing SHA-512/256 is +.Em NOT +yet supported. +.It Sy skein +.Bl -column "READ\-ONLY COMPATIBLE" "org.illumos:skein" +.It GUID Ta org.illumos:skein +.It READ\-ONLY COMPATIBLE Ta no +.It DEPENDENCIES Ta none +.El +.Pp +The +.Sy skein +feature enables the use of the Skein hash algorithm for checksum and dedup. +Skein is a high-performance secure hash algorithm that was a finalist in the +NIST SHA-3 competition. +It provides a very high security margin and high performance on 64-bit hardware +.Pq 80% faster than SHA-256 . +This implementation also utilizes the new salted checksumming functionality in +ZFS, which means that the checksum is pre-seeded with a secret 256-bit random +key +.Pq stored on the pool +before being fed the data block to be checksummed. +Thus the produced checksums are unique to a given pool, preventing hash +collision attacks on systems with dedup. +.Pp +When the +.Sy skein +feature is set to +.Sy enabled , +the administrator can turn on the +.Sy skein +checksum on any dataset using the +.Dl # zfs set checksum=skein Ar dataset +command. +This feature becomes +.Sy active +once a +.Sy checksum +property has been set to +.Sy skein , +and will return to being +.Sy enabled +once all filesystems that have ever had their checksum set to +.Sy skein +are destroyed. +.Pp +Booting off of pools using +.Sy skein +is +.Em NOT +supported. +.El +.Sh SEE ALSO +.Xr zpool 8 +.Sh AUTHORS +This manual page is a +.Xr mdoc 7 +reimplementation of the +.Tn illumos +manual page +.Em zpool-features(5) , +modified and customized for +.Fx +and licensed under the Common Development and Distribution License +.Pq Tn CDDL . +.Pp +The +.Xr mdoc 7 +implementation of this manual page was initially written by +.An Martin Matuska Aq mm@FreeBSD.org . -- cgit v1.2.3