diff options
Diffstat (limited to 'doc')
77 files changed, 896 insertions, 269 deletions
diff --git a/doc/build.info b/doc/build.info index bff57d5d50fb..bb1f00f49b76 100644 --- a/doc/build.info +++ b/doc/build.info @@ -699,6 +699,10 @@ DEPEND[html/man3/BIO_set_callback.html]=man3/BIO_set_callback.pod GENERATE[html/man3/BIO_set_callback.html]=man3/BIO_set_callback.pod DEPEND[man/man3/BIO_set_callback.3]=man3/BIO_set_callback.pod GENERATE[man/man3/BIO_set_callback.3]=man3/BIO_set_callback.pod +DEPEND[html/man3/BIO_set_flags.html]=man3/BIO_set_flags.pod +GENERATE[html/man3/BIO_set_flags.html]=man3/BIO_set_flags.pod +DEPEND[man/man3/BIO_set_flags.3]=man3/BIO_set_flags.pod +GENERATE[man/man3/BIO_set_flags.3]=man3/BIO_set_flags.pod DEPEND[html/man3/BIO_should_retry.html]=man3/BIO_should_retry.pod GENERATE[html/man3/BIO_should_retry.html]=man3/BIO_should_retry.pod DEPEND[man/man3/BIO_should_retry.3]=man3/BIO_should_retry.pod @@ -803,6 +807,10 @@ DEPEND[html/man3/CMS_EncryptedData_encrypt.html]=man3/CMS_EncryptedData_encrypt. GENERATE[html/man3/CMS_EncryptedData_encrypt.html]=man3/CMS_EncryptedData_encrypt.pod DEPEND[man/man3/CMS_EncryptedData_encrypt.3]=man3/CMS_EncryptedData_encrypt.pod GENERATE[man/man3/CMS_EncryptedData_encrypt.3]=man3/CMS_EncryptedData_encrypt.pod +DEPEND[html/man3/CMS_EncryptedData_set1_key.html]=man3/CMS_EncryptedData_set1_key.pod +GENERATE[html/man3/CMS_EncryptedData_set1_key.html]=man3/CMS_EncryptedData_set1_key.pod +DEPEND[man/man3/CMS_EncryptedData_set1_key.3]=man3/CMS_EncryptedData_set1_key.pod +GENERATE[man/man3/CMS_EncryptedData_set1_key.3]=man3/CMS_EncryptedData_set1_key.pod DEPEND[html/man3/CMS_EnvelopedData_create.html]=man3/CMS_EnvelopedData_create.pod GENERATE[html/man3/CMS_EnvelopedData_create.html]=man3/CMS_EnvelopedData_create.pod DEPEND[man/man3/CMS_EnvelopedData_create.3]=man3/CMS_EnvelopedData_create.pod @@ -1127,6 +1135,10 @@ DEPEND[html/man3/EVP_BytesToKey.html]=man3/EVP_BytesToKey.pod GENERATE[html/man3/EVP_BytesToKey.html]=man3/EVP_BytesToKey.pod DEPEND[man/man3/EVP_BytesToKey.3]=man3/EVP_BytesToKey.pod GENERATE[man/man3/EVP_BytesToKey.3]=man3/EVP_BytesToKey.pod +DEPEND[html/man3/EVP_CIPHER_CTX_get_app_data.html]=man3/EVP_CIPHER_CTX_get_app_data.pod +GENERATE[html/man3/EVP_CIPHER_CTX_get_app_data.html]=man3/EVP_CIPHER_CTX_get_app_data.pod +DEPEND[man/man3/EVP_CIPHER_CTX_get_app_data.3]=man3/EVP_CIPHER_CTX_get_app_data.pod +GENERATE[man/man3/EVP_CIPHER_CTX_get_app_data.3]=man3/EVP_CIPHER_CTX_get_app_data.pod DEPEND[html/man3/EVP_CIPHER_CTX_get_cipher_data.html]=man3/EVP_CIPHER_CTX_get_cipher_data.pod GENERATE[html/man3/EVP_CIPHER_CTX_get_cipher_data.html]=man3/EVP_CIPHER_CTX_get_cipher_data.pod DEPEND[man/man3/EVP_CIPHER_CTX_get_cipher_data.3]=man3/EVP_CIPHER_CTX_get_cipher_data.pod @@ -1603,6 +1615,10 @@ DEPEND[html/man3/OPENSSL_malloc.html]=man3/OPENSSL_malloc.pod GENERATE[html/man3/OPENSSL_malloc.html]=man3/OPENSSL_malloc.pod DEPEND[man/man3/OPENSSL_malloc.3]=man3/OPENSSL_malloc.pod GENERATE[man/man3/OPENSSL_malloc.3]=man3/OPENSSL_malloc.pod +DEPEND[html/man3/OPENSSL_ppccap.html]=man3/OPENSSL_ppccap.pod +GENERATE[html/man3/OPENSSL_ppccap.html]=man3/OPENSSL_ppccap.pod +DEPEND[man/man3/OPENSSL_ppccap.3]=man3/OPENSSL_ppccap.pod +GENERATE[man/man3/OPENSSL_ppccap.3]=man3/OPENSSL_ppccap.pod DEPEND[html/man3/OPENSSL_riscvcap.html]=man3/OPENSSL_riscvcap.pod GENERATE[html/man3/OPENSSL_riscvcap.html]=man3/OPENSSL_riscvcap.pod DEPEND[man/man3/OPENSSL_riscvcap.3]=man3/OPENSSL_riscvcap.pod @@ -3220,6 +3236,7 @@ html/man3/BIO_s_null.html \ html/man3/BIO_s_socket.html \ html/man3/BIO_sendmmsg.html \ html/man3/BIO_set_callback.html \ +html/man3/BIO_set_flags.html \ html/man3/BIO_should_retry.html \ html/man3/BIO_socket_wait.html \ html/man3/BN_BLINDING_new.html \ @@ -3246,6 +3263,7 @@ html/man3/BUF_MEM_new.html \ html/man3/CMAC_CTX.html \ html/man3/CMS_EncryptedData_decrypt.html \ html/man3/CMS_EncryptedData_encrypt.html \ +html/man3/CMS_EncryptedData_set1_key.html \ html/man3/CMS_EnvelopedData_create.html \ html/man3/CMS_add0_cert.html \ html/man3/CMS_add1_recipient_cert.html \ @@ -3327,6 +3345,7 @@ html/man3/ERR_remove_state.html \ html/man3/ERR_set_mark.html \ html/man3/EVP_ASYM_CIPHER_free.html \ html/man3/EVP_BytesToKey.html \ +html/man3/EVP_CIPHER_CTX_get_app_data.html \ html/man3/EVP_CIPHER_CTX_get_cipher_data.html \ html/man3/EVP_CIPHER_CTX_get_original_iv.html \ html/man3/EVP_CIPHER_meth_new.html \ @@ -3446,6 +3465,7 @@ html/man3/OPENSSL_instrument_bus.html \ html/man3/OPENSSL_load_builtin_modules.html \ html/man3/OPENSSL_load_u16_le.html \ html/man3/OPENSSL_malloc.html \ +html/man3/OPENSSL_ppccap.html \ html/man3/OPENSSL_riscvcap.html \ html/man3/OPENSSL_s390xcap.html \ html/man3/OPENSSL_secure_malloc.html \ @@ -3892,6 +3912,7 @@ man/man3/BIO_s_null.3 \ man/man3/BIO_s_socket.3 \ man/man3/BIO_sendmmsg.3 \ man/man3/BIO_set_callback.3 \ +man/man3/BIO_set_flags.3 \ man/man3/BIO_should_retry.3 \ man/man3/BIO_socket_wait.3 \ man/man3/BN_BLINDING_new.3 \ @@ -3918,6 +3939,7 @@ man/man3/BUF_MEM_new.3 \ man/man3/CMAC_CTX.3 \ man/man3/CMS_EncryptedData_decrypt.3 \ man/man3/CMS_EncryptedData_encrypt.3 \ +man/man3/CMS_EncryptedData_set1_key.3 \ man/man3/CMS_EnvelopedData_create.3 \ man/man3/CMS_add0_cert.3 \ man/man3/CMS_add1_recipient_cert.3 \ @@ -3999,6 +4021,7 @@ man/man3/ERR_remove_state.3 \ man/man3/ERR_set_mark.3 \ man/man3/EVP_ASYM_CIPHER_free.3 \ man/man3/EVP_BytesToKey.3 \ +man/man3/EVP_CIPHER_CTX_get_app_data.3 \ man/man3/EVP_CIPHER_CTX_get_cipher_data.3 \ man/man3/EVP_CIPHER_CTX_get_original_iv.3 \ man/man3/EVP_CIPHER_meth_new.3 \ @@ -4118,6 +4141,7 @@ man/man3/OPENSSL_instrument_bus.3 \ man/man3/OPENSSL_load_builtin_modules.3 \ man/man3/OPENSSL_load_u16_le.3 \ man/man3/OPENSSL_malloc.3 \ +man/man3/OPENSSL_ppccap.3 \ man/man3/OPENSSL_riscvcap.3 \ man/man3/OPENSSL_s390xcap.3 \ man/man3/OPENSSL_secure_malloc.3 \ diff --git a/doc/designs/ML-KEM.md b/doc/designs/ML-KEM.md index 267656dfba22..b1ca4098e089 100644 --- a/doc/designs/ML-KEM.md +++ b/doc/designs/ML-KEM.md @@ -44,7 +44,7 @@ subsequent computations (encapsulation). Since the private key includes the public key as one of its components, the matrix is also pre-computed and stored with the private key, and then need not be regenerated during decapsulation. -During encapsulation (typically peformed by servers), it is in principle +During encapsulation (typically performed by servers), it is in principle possible to save space and compute the matrix elements *just-in-time*, as each matrix element is used exactly once. This is not currently implemented, and the matrix is pre-computed in full. @@ -90,7 +90,7 @@ Keys can be generated via the usual **EVP_PKEY_generate()** and An explicit seed can be specified by setting the key generation **OSSL_PKEY_PARAM_ML_KEM_SEED** parameter to a 64-byte octet-string -(concatentation of the **d** and **z** values (32-bytes each) in that order). +(concatenation of the **d** and **z** values (32-bytes each) in that order). KEM API ------- diff --git a/doc/designs/ddd/ddd-01-conn-blocking.c b/doc/designs/ddd/ddd-01-conn-blocking.c index d2df84d85498..d9e1a3fbae5e 100644 --- a/doc/designs/ddd/ddd-01-conn-blocking.c +++ b/doc/designs/ddd/ddd-01-conn-blocking.c @@ -52,7 +52,7 @@ BIO *new_conn(SSL_CTX *ctx, const char *hostname) SSL *ssl = NULL; const char *bare_hostname; #ifdef USE_QUIC - static const unsigned char alpn[] = {5, 'd', 'u', 'm', 'm', 'y'}; + static const unsigned char alpn[] = { 5, 'd', 'u', 'm', 'm', 'y' }; #endif out = BIO_new_ssl_connect(ctx); @@ -150,7 +150,7 @@ int main(int argc, char **argv) snprintf(host_port, sizeof(host_port), "%s:%s", argv[1], argv[2]); mlen = snprintf(msg, sizeof(msg), - "GET / HTTP/1.0\r\nHost: %s\r\n\r\n", argv[1]); + "GET / HTTP/1.0\r\nHost: %s\r\n\r\n", argv[1]); ctx = create_ssl_ctx(); if (ctx == NULL) { diff --git a/doc/designs/ddd/ddd-02-conn-nonblocking-threads.c b/doc/designs/ddd/ddd-02-conn-nonblocking-threads.c index 19d978bba078..3d2c07918239 100644 --- a/doc/designs/ddd/ddd-02-conn-nonblocking-threads.c +++ b/doc/designs/ddd/ddd-02-conn-nonblocking-threads.c @@ -65,7 +65,7 @@ APP_CONN *new_conn(SSL_CTX *ctx, const char *hostname) SSL *ssl = NULL; const char *bare_hostname; #ifdef USE_QUIC - static const unsigned char alpn[] = {5, 'd', 'u', 'm', 'm', 'y'}; + static const unsigned char alpn[] = { 5, 'd', 'u', 'm', 'm', 'y' }; #endif conn = calloc(1, sizeof(APP_CONN)); @@ -216,8 +216,8 @@ int get_conn_pending_tx(APP_CONN *conn) { #ifdef USE_QUIC return (SSL_net_read_desired(conn->ssl) ? POLLIN : 0) - | (SSL_net_write_desired(conn->ssl) ? POLLOUT : 0) - | POLLERR; + | (SSL_net_write_desired(conn->ssl) ? POLLOUT : 0) + | POLLERR; #else return (conn->tx_need_rx ? POLLIN : 0) | POLLOUT | POLLERR; #endif @@ -273,7 +273,7 @@ int main(int argc, char **argv) snprintf(host_port, sizeof(host_port), "%s:%s", argv[1], argv[2]); tx_len = snprintf(tx_msg, sizeof(tx_msg), - "GET / HTTP/1.0\r\nHost: %s\r\n\r\n", argv[1]); + "GET / HTTP/1.0\r\nHost: %s\r\n\r\n", argv[1]); ctx = create_ssl_ctx(); if (ctx == NULL) { @@ -296,7 +296,7 @@ int main(int argc, char **argv) } else if (l == -1) { fprintf(stderr, "tx error\n"); } else if (l == -2) { - struct pollfd pfd = {0}; + struct pollfd pfd = { 0 }; pfd.fd = get_conn_fd(conn); pfd.events = get_conn_pending_tx(conn); if (poll(&pfd, 1, timeout) == 0) { @@ -314,7 +314,7 @@ int main(int argc, char **argv) } else if (l == -1) { break; } else if (l == -2) { - struct pollfd pfd = {0}; + struct pollfd pfd = { 0 }; pfd.fd = get_conn_fd(conn); pfd.events = get_conn_pending_rx(conn); if (poll(&pfd, 1, timeout) == 0) { diff --git a/doc/designs/ddd/ddd-02-conn-nonblocking.c b/doc/designs/ddd/ddd-02-conn-nonblocking.c index a92892f6e142..b24d3720e980 100644 --- a/doc/designs/ddd/ddd-02-conn-nonblocking.c +++ b/doc/designs/ddd/ddd-02-conn-nonblocking.c @@ -65,7 +65,7 @@ APP_CONN *new_conn(SSL_CTX *ctx, const char *hostname) SSL *ssl = NULL; const char *bare_hostname; #ifdef USE_QUIC - static const unsigned char alpn[] = {5, 'd', 'u', 'm', 'm', 'y'}; + static const unsigned char alpn[] = { 5, 'd', 'u', 'm', 'm', 'y' }; #endif conn = calloc(1, sizeof(APP_CONN)); @@ -228,8 +228,8 @@ int get_conn_pending_tx(APP_CONN *conn) { #ifdef USE_QUIC return (SSL_net_read_desired(conn->ssl) ? POLLIN : 0) - | (SSL_net_write_desired(conn->ssl) ? POLLOUT : 0) - | POLLERR; + | (SSL_net_write_desired(conn->ssl) ? POLLOUT : 0) + | POLLERR; #else return (conn->tx_need_rx ? POLLIN : 0) | POLLOUT | POLLERR; #endif @@ -302,13 +302,13 @@ void teardown_ctx(SSL_CTX *ctx) static inline void ms_to_timeval(struct timeval *t, int ms) { - t->tv_sec = ms < 0 ? -1 : ms/1000; - t->tv_usec = ms < 0 ? 0 : (ms%1000)*1000; + t->tv_sec = ms < 0 ? -1 : ms / 1000; + t->tv_usec = ms < 0 ? 0 : (ms % 1000) * 1000; } static inline int timeval_to_ms(const struct timeval *t) { - return t->tv_sec*1000 + t->tv_usec/1000; + return t->tv_sec * 1000 + t->tv_usec / 1000; } int main(int argc, char **argv) @@ -336,7 +336,7 @@ int main(int argc, char **argv) snprintf(host_port, sizeof(host_port), "%s:%s", argv[1], argv[2]); tx_len = snprintf(tx_msg, sizeof(tx_msg), - "GET / HTTP/1.0\r\nHost: %s\r\n\r\n", argv[1]); + "GET / HTTP/1.0\r\nHost: %s\r\n\r\n", argv[1]); ctx = create_ssl_ctx(); if (ctx == NULL) { @@ -362,7 +362,7 @@ int main(int argc, char **argv) #ifdef USE_QUIC struct timeval start, now, deadline, t; #endif - struct pollfd pfd = {0}; + struct pollfd pfd = { 0 }; #ifdef USE_QUIC ms_to_timeval(&t, get_conn_pump_timeout(conn)); @@ -406,7 +406,7 @@ int main(int argc, char **argv) #ifdef USE_QUIC struct timeval start, now, deadline, t; #endif - struct pollfd pfd = {0}; + struct pollfd pfd = { 0 }; #ifdef USE_QUIC ms_to_timeval(&t, get_conn_pump_timeout(conn)); diff --git a/doc/designs/ddd/ddd-03-fd-blocking.c b/doc/designs/ddd/ddd-03-fd-blocking.c index c545714c3c5f..5adde1a9d555 100644 --- a/doc/designs/ddd/ddd-03-fd-blocking.c +++ b/doc/designs/ddd/ddd-03-fd-blocking.c @@ -51,7 +51,7 @@ SSL *new_conn(SSL_CTX *ctx, int fd, const char *bare_hostname) { SSL *ssl; #ifdef USE_QUIC - static const unsigned char alpn[] = {5, 'd', 'u', 'm', 'm', 'y'}; + static const unsigned char alpn[] = { 5, 'd', 'u', 'm', 'm', 'y' }; #endif ssl = SSL_new(ctx); @@ -138,7 +138,7 @@ int main(int argc, char **argv) { int rc, fd = -1, l, mlen, res = 1; static char msg[300]; - struct addrinfo hints = {0}, *result = NULL; + struct addrinfo hints = { 0 }, *result = NULL; SSL *ssl = NULL; SSL_CTX *ctx = NULL; char buf[2048]; @@ -149,7 +149,7 @@ int main(int argc, char **argv) } mlen = snprintf(msg, sizeof(msg), - "GET / HTTP/1.0\r\nHost: %s\r\n\r\n", argv[1]); + "GET / HTTP/1.0\r\nHost: %s\r\n\r\n", argv[1]); ctx = create_ssl_ctx(); if (ctx == NULL) { @@ -157,9 +157,9 @@ int main(int argc, char **argv) goto fail; } - hints.ai_family = AF_INET; - hints.ai_socktype = SOCK_STREAM; - hints.ai_flags = AI_PASSIVE; + hints.ai_family = AF_INET; + hints.ai_socktype = SOCK_STREAM; + hints.ai_flags = AI_PASSIVE; rc = getaddrinfo(argv[1], argv[2], &hints, &result); if (rc < 0) { fprintf(stderr, "cannot resolve\n"); diff --git a/doc/designs/ddd/ddd-04-fd-nonblocking.c b/doc/designs/ddd/ddd-04-fd-nonblocking.c index d39827adf66a..42caac896769 100644 --- a/doc/designs/ddd/ddd-04-fd-nonblocking.c +++ b/doc/designs/ddd/ddd-04-fd-nonblocking.c @@ -58,7 +58,7 @@ APP_CONN *new_conn(SSL_CTX *ctx, int fd, const char *bare_hostname) APP_CONN *conn; SSL *ssl; #ifdef USE_QUIC - static const unsigned char alpn[] = {5, 'd', 'u', 'm', 'm', 'y'}; + static const unsigned char alpn[] = { 5, 'd', 'u', 'm', 'm', 'y' }; #endif conn = calloc(1, sizeof(APP_CONN)); @@ -121,13 +121,13 @@ int tx(APP_CONN *conn, const void *buf, int buf_len) if (l <= 0) { rc = SSL_get_error(conn->ssl, l); switch (rc) { - case SSL_ERROR_WANT_READ: - conn->tx_need_rx = 1; - case SSL_ERROR_WANT_CONNECT: - case SSL_ERROR_WANT_WRITE: - return -2; - default: - return -1; + case SSL_ERROR_WANT_READ: + conn->tx_need_rx = 1; + case SSL_ERROR_WANT_CONNECT: + case SSL_ERROR_WANT_WRITE: + return -2; + default: + return -1; } } @@ -150,12 +150,12 @@ int rx(APP_CONN *conn, void *buf, int buf_len) if (l <= 0) { rc = SSL_get_error(conn->ssl, l); switch (rc) { - case SSL_ERROR_WANT_WRITE: - conn->rx_need_tx = 1; - case SSL_ERROR_WANT_READ: - return -2; - default: - return -1; + case SSL_ERROR_WANT_WRITE: + conn->rx_need_tx = 1; + case SSL_ERROR_WANT_READ: + return -2; + default: + return -1; } } @@ -199,8 +199,8 @@ int get_conn_pending_tx(APP_CONN *conn) { #ifdef USE_QUIC return (SSL_net_read_desired(conn->ssl) ? POLLIN : 0) - | (SSL_net_write_desired(conn->ssl) ? POLLOUT : 0) - | POLLERR; + | (SSL_net_write_desired(conn->ssl) ? POLLOUT : 0) + | POLLERR; #else return (conn->tx_need_rx ? POLLIN : 0) | POLLOUT | POLLERR; #endif @@ -270,7 +270,7 @@ void teardown_ctx(SSL_CTX *ctx) #include <sys/socket.h> #include <sys/signal.h> #ifdef USE_QUIC -# include <sys/time.h> +#include <sys/time.h> #endif #include <netdb.h> #include <unistd.h> @@ -280,13 +280,13 @@ void teardown_ctx(SSL_CTX *ctx) static inline void ms_to_timeval(struct timeval *t, int ms) { - t->tv_sec = ms < 0 ? -1 : ms/1000; - t->tv_usec = ms < 0 ? 0 : (ms%1000)*1000; + t->tv_sec = ms < 0 ? -1 : ms / 1000; + t->tv_usec = ms < 0 ? 0 : (ms % 1000) * 1000; } static inline int timeval_to_ms(const struct timeval *t) { - return t->tv_sec*1000 + t->tv_usec/1000; + return t->tv_sec * 1000 + t->tv_usec / 1000; } #endif @@ -304,7 +304,7 @@ int main(int argc, char **argv) int timeout = 2000 /* ms */; #endif APP_CONN *conn = NULL; - struct addrinfo hints = {0}, *result = NULL; + struct addrinfo hints = { 0 }, *result = NULL; SSL_CTX *ctx = NULL; #ifdef USE_QUIC @@ -317,7 +317,7 @@ int main(int argc, char **argv) } tx_len = snprintf(tx_msg, sizeof(tx_msg), - "GET / HTTP/1.0\r\nHost: %s\r\n\r\n", argv[1]); + "GET / HTTP/1.0\r\nHost: %s\r\n\r\n", argv[1]); ctx = create_ssl_ctx(); if (ctx == NULL) { @@ -325,9 +325,9 @@ int main(int argc, char **argv) goto fail; } - hints.ai_family = AF_INET; - hints.ai_socktype = SOCK_STREAM; - hints.ai_flags = AI_PASSIVE; + hints.ai_family = AF_INET; + hints.ai_socktype = SOCK_STREAM; + hints.ai_flags = AI_PASSIVE; rc = getaddrinfo(argv[1], argv[2], &hints, &result); if (rc < 0) { fprintf(stderr, "cannot resolve\n"); @@ -377,7 +377,7 @@ int main(int argc, char **argv) #ifdef USE_QUIC struct timeval start, now, deadline, t; #endif - struct pollfd pfd = {0}; + struct pollfd pfd = { 0 }; #ifdef USE_QUIC ms_to_timeval(&t, get_conn_pump_timeout(conn)); @@ -421,7 +421,7 @@ int main(int argc, char **argv) #ifdef USE_QUIC struct timeval start, now, deadline, t; #endif - struct pollfd pfd = {0}; + struct pollfd pfd = { 0 }; #ifdef USE_QUIC ms_to_timeval(&t, get_conn_pump_timeout(conn)); diff --git a/doc/designs/ddd/ddd-05-mem-nonblocking.c b/doc/designs/ddd/ddd-05-mem-nonblocking.c index 8e30016bb180..33b156ccc542 100644 --- a/doc/designs/ddd/ddd-05-mem-nonblocking.c +++ b/doc/designs/ddd/ddd-05-mem-nonblocking.c @@ -63,7 +63,7 @@ APP_CONN *new_conn(SSL_CTX *ctx, const char *bare_hostname) APP_CONN *conn; SSL *ssl; #ifdef USE_QUIC - static const unsigned char alpn[] = {5, 'd', 'u', 'm', 'm', 'y'}; + static const unsigned char alpn[] = { 5, 'd', 'u', 'm', 'm', 'y' }; #endif conn = calloc(1, sizeof(APP_CONN)); @@ -125,8 +125,8 @@ APP_CONN *new_conn(SSL_CTX *ctx, const char *bare_hostname) } #endif - conn->ssl_bio = ssl_bio; - conn->net_bio = net_bio; + conn->ssl_bio = ssl_bio; + conn->net_bio = net_bio; return conn; } @@ -144,13 +144,13 @@ int tx(APP_CONN *conn, const void *buf, int buf_len) if (l <= 0) { rc = SSL_get_error(conn->ssl, l); switch (rc) { - case SSL_ERROR_WANT_READ: - conn->tx_need_rx = 1; - case SSL_ERROR_WANT_CONNECT: - case SSL_ERROR_WANT_WRITE: - return -2; - default: - return -1; + case SSL_ERROR_WANT_READ: + conn->tx_need_rx = 1; + case SSL_ERROR_WANT_CONNECT: + case SSL_ERROR_WANT_WRITE: + return -2; + default: + return -1; } } else { conn->tx_need_rx = 0; @@ -173,12 +173,12 @@ int rx(APP_CONN *conn, void *buf, int buf_len) if (l <= 0) { rc = SSL_get_error(conn->ssl, l); switch (rc) { - case SSL_ERROR_WANT_WRITE: - conn->rx_need_tx = 1; - case SSL_ERROR_WANT_READ: - return -2; - default: - return -1; + case SSL_ERROR_WANT_WRITE: + conn->rx_need_tx = 1; + case SSL_ERROR_WANT_READ: + return -2; + default: + return -1; } } else { conn->rx_need_tx = 0; @@ -245,8 +245,8 @@ int get_conn_pending_tx(APP_CONN *conn) { #ifdef USE_QUIC return (SSL_net_read_desired(conn->ssl) ? POLLIN : 0) - | (SSL_net_write_desired(conn->ssl) ? POLLOUT : 0) - | POLLERR; + | (SSL_net_write_desired(conn->ssl) ? POLLOUT : 0) + | POLLERR; #else return (conn->tx_need_rx ? POLLIN : 0) | POLLOUT | POLLERR; #endif @@ -299,7 +299,7 @@ static int pump(APP_CONN *conn, int fd, int events, int timeout) int l, l2; char buf[2048]; /* QUIC: would need to be changed if < 1472 */ size_t wspace; - struct pollfd pfd = {0}; + struct pollfd pfd = { 0 }; pfd.fd = fd; pfd.events = (events & (POLLIN | POLLERR)); @@ -308,7 +308,7 @@ static int pump(APP_CONN *conn, int fd, int events, int timeout) if (net_tx_avail(conn) > 0) pfd.events |= POLLOUT; - if ((pfd.events & (POLLIN|POLLOUT)) == 0) + if ((pfd.events & (POLLIN | POLLOUT)) == 0) return 1; if (poll(&pfd, 1, timeout) == 0) @@ -319,21 +319,22 @@ static int pump(APP_CONN *conn, int fd, int events, int timeout) l = read(fd, buf, wspace > sizeof(buf) ? sizeof(buf) : wspace); if (l <= 0) { switch (errno) { - case EAGAIN: + case EAGAIN: + goto stop; + default: + if (l == 0) /* EOF */ goto stop; - default: - if (l == 0) /* EOF */ - goto stop; - fprintf(stderr, "error on read: %d\n", errno); - return -1; + fprintf(stderr, "error on read: %d\n", errno); + return -1; } break; } l2 = write_net_rx(conn, buf, l); if (l2 < l) fprintf(stderr, "short write %d %d\n", l2, l); - } stop:; + } + stop:; } if (pfd.revents & POLLOUT) { @@ -359,7 +360,7 @@ int main(int argc, char **argv) int l, tx_len; int timeout = 2000 /* ms */; APP_CONN *conn = NULL; - struct addrinfo hints = {0}, *result = NULL; + struct addrinfo hints = { 0 }, *result = NULL; SSL_CTX *ctx = NULL; if (argc < 3) { @@ -368,8 +369,8 @@ int main(int argc, char **argv) } tx_len = snprintf(tx_msg, sizeof(tx_msg), - "GET / HTTP/1.0\r\nHost: %s\r\n\r\n", - argv[1]); + "GET / HTTP/1.0\r\nHost: %s\r\n\r\n", + argv[1]); ctx = create_ssl_ctx(); if (ctx == NULL) { @@ -377,9 +378,9 @@ int main(int argc, char **argv) goto fail; } - hints.ai_family = AF_INET; - hints.ai_socktype = SOCK_STREAM; - hints.ai_flags = AI_PASSIVE; + hints.ai_family = AF_INET; + hints.ai_socktype = SOCK_STREAM; + hints.ai_flags = AI_PASSIVE; rc = getaddrinfo(argv[1], argv[2], &hints, &result); if (rc < 0) { fprintf(stderr, "cannot resolve\n"); diff --git a/doc/designs/ddd/ddd-06-mem-uv.c b/doc/designs/ddd/ddd-06-mem-uv.c index b4e2164e9196..fd5eadc3c6ef 100644 --- a/doc/designs/ddd/ddd-06-mem-uv.c +++ b/doc/designs/ddd/ddd-06-mem-uv.c @@ -3,16 +3,16 @@ #include <uv.h> #include <assert.h> #ifdef USE_QUIC -# include <sys/time.h> +#include <sys/time.h> #endif typedef struct app_conn_st APP_CONN; typedef struct upper_write_op_st UPPER_WRITE_OP; typedef struct lower_write_op_st LOWER_WRITE_OP; -typedef void (app_connect_cb)(APP_CONN *conn, int status, void *arg); -typedef void (app_write_cb)(APP_CONN *conn, int status, void *arg); -typedef void (app_read_cb)(APP_CONN *conn, void *buf, size_t buf_len, void *arg); +typedef void(app_connect_cb)(APP_CONN *conn, int status, void *arg); +typedef void(app_write_cb)(APP_CONN *conn, int status, void *arg); +typedef void(app_read_cb)(APP_CONN *conn, void *buf, size_t buf_len, void *arg); #ifdef USE_QUIC static void set_timer(APP_CONN *conn); @@ -32,7 +32,7 @@ static int setup_ssl(APP_CONN *conn, const char *hostname); #ifdef USE_QUIC static inline int timeval_to_ms(const struct timeval *t) { - return t->tv_sec*1000 + t->tv_usec/1000; + return t->tv_sec * 1000 + t->tv_usec / 1000; } #endif @@ -42,12 +42,12 @@ static inline int timeval_to_ms(const struct timeval *t) * it is in WANT_READ. */ struct upper_write_op_st { - struct upper_write_op_st *prev, *next; - const uint8_t *buf; - size_t buf_len, written; - APP_CONN *conn; - app_write_cb *cb; - void *cb_arg; + struct upper_write_op_st *prev, *next; + const uint8_t *buf; + size_t buf_len, written; + APP_CONN *conn; + app_write_cb *cb; + void *cb_arg; }; /* @@ -55,37 +55,37 @@ struct upper_write_op_st { */ struct lower_write_op_st { #ifdef USE_QUIC - uv_udp_send_t w; + uv_udp_send_t w; #else - uv_write_t w; + uv_write_t w; #endif - uv_buf_t b; - uint8_t *buf; - APP_CONN *conn; + uv_buf_t b; + uint8_t *buf; + APP_CONN *conn; }; /* * Application connection object. */ struct app_conn_st { - SSL_CTX *ctx; - SSL *ssl; - BIO *net_bio; + SSL_CTX *ctx; + SSL *ssl; + BIO *net_bio; #ifdef USE_QUIC - uv_udp_t udp; - uv_timer_t timer; + uv_udp_t udp; + uv_timer_t timer; #else - uv_stream_t *stream; - uv_tcp_t tcp; - uv_connect_t tcp_connect; + uv_stream_t *stream; + uv_tcp_t tcp; + uv_connect_t tcp_connect; #endif - app_connect_cb *app_connect_cb; /* called once handshake is done */ - void *app_connect_arg; - app_read_cb *app_read_cb; /* application's on-RX callback */ - void *app_read_arg; - const char *hostname; - char init_handshake, done_handshake, closed; - char *teardown_done; + app_connect_cb *app_connect_cb; /* called once handshake is done */ + void *app_connect_arg; + app_read_cb *app_read_cb; /* application's on-RX callback */ + void *app_read_arg; + const char *hostname; + char init_handshake, done_handshake, closed; + char *teardown_done; UPPER_WRITE_OP *pending_upper_write_head, *pending_upper_write_tail; }; @@ -129,8 +129,8 @@ SSL_CTX *create_ssl_ctx(void) */ APP_CONN *new_conn(SSL_CTX *ctx, const char *hostname, - struct sockaddr *sa, socklen_t sa_len, - app_connect_cb *cb, void *arg) + struct sockaddr *sa, socklen_t sa_len, + app_connect_cb *cb, void *arg) { int rc; APP_CONN *conn = NULL; @@ -149,15 +149,15 @@ APP_CONN *new_conn(SSL_CTX *ctx, const char *hostname, uv_tcp_init(uv_default_loop(), &conn->tcp); conn->tcp.data = conn; - conn->stream = (uv_stream_t *)&conn->tcp; + conn->stream = (uv_stream_t *)&conn->tcp; #endif - conn->app_connect_cb = cb; - conn->app_connect_arg = arg; + conn->app_connect_cb = cb; + conn->app_connect_arg = arg; #ifdef USE_QUIC rc = uv_udp_connect(&conn->udp, sa); #else - conn->tcp_connect.data = conn; + conn->tcp_connect.data = conn; rc = uv_tcp_connect(&conn->tcp_connect, &conn->tcp, sa, tcp_connect_done); #endif if (rc < 0) { @@ -169,8 +169,8 @@ APP_CONN *new_conn(SSL_CTX *ctx, const char *hostname, return NULL; } - conn->ctx = ctx; - conn->hostname = hostname; + conn->ctx = ctx; + conn->hostname = hostname; #ifdef USE_QUIC rc = setup_ssl(conn, hostname); @@ -189,7 +189,7 @@ APP_CONN *new_conn(SSL_CTX *ctx, const char *hostname, */ int app_read_start(APP_CONN *conn, app_read_cb *cb, void *arg) { - conn->app_read_cb = cb; + conn->app_read_cb = cb; conn->app_read_arg = arg; set_rx(conn); return 0; @@ -280,7 +280,7 @@ static void dequeue_upper_write_op(APP_CONN *conn) } static void net_read_alloc(uv_handle_t *handle, - size_t suggested_size, uv_buf_t *buf) + size_t suggested_size, uv_buf_t *buf) { #ifdef USE_QUIC if (suggested_size < 1472) @@ -288,7 +288,7 @@ static void net_read_alloc(uv_handle_t *handle, #endif buf->base = malloc(suggested_size); - buf->len = suggested_size; + buf->len = suggested_size; } static void on_rx_push(APP_CONN *conn) @@ -349,7 +349,7 @@ static void handle_pending_writes(APP_CONN *conn) #ifdef USE_QUIC static void net_read_done(uv_udp_t *stream, ssize_t nr, const uv_buf_t *buf, - const struct sockaddr *addr, unsigned int flags) + const struct sockaddr *addr, unsigned int flags) #else static void net_read_done(uv_stream_t *stream, ssize_t nr, const uv_buf_t *buf) #endif @@ -440,11 +440,11 @@ static void flush_write_buf(APP_CONN *conn) if (!op) return; - op->buf = buf; - op->conn = conn; - op->w.data = op; - op->b.base = (char *)buf; - op->b.len = rd; + op->buf = buf; + op->conn = conn; + op->w.data = op; + op->b.base = (char *)buf; + op->b.len = rd; #ifdef USE_QUIC rc = uv_udp_send(&op->w, &conn->udp, &op->b, 1, NULL, net_write_done); @@ -497,7 +497,7 @@ static int setup_ssl(APP_CONN *conn, const char *hostname) BIO *internal_bio = NULL, *net_bio = NULL; SSL *ssl = NULL; #ifdef USE_QUIC - static const unsigned char alpn[] = {5, 'd', 'u', 'm', 'm', 'y'}; + static const unsigned char alpn[] = { 5, 'd', 'u', 'm', 'm', 'y' }; #endif ssl = SSL_new(conn->ctx); @@ -539,8 +539,8 @@ static int setup_ssl(APP_CONN *conn, const char *hostname) } #endif - conn->net_bio = net_bio; - conn->ssl = ssl; + conn->net_bio = net_bio; + conn->ssl = ssl; return handshake_ssl(conn); } @@ -634,11 +634,11 @@ static int write_deferred(APP_CONN *conn, const void *buf, size_t buf_len, app_w if (!op) return -1; - op->buf = buf; + op->buf = buf; op->buf_len = buf_len; - op->conn = conn; - op->cb = cb; - op->cb_arg = arg; + op->conn = conn; + op->cb = cb; + op->cb_arg = arg; enqueue_upper_write_op(conn, op); set_rx(conn); @@ -657,7 +657,7 @@ static void teardown_continued(uv_handle_t *handle) return; #endif - for (op=conn->pending_upper_write_head; op; op=next_op) { + for (op = conn->pending_upper_write_head; op; op = next_op) { next_op = op->next; free(op); } @@ -720,7 +720,7 @@ int main(int argc, char **argv) int rc = 1; SSL_CTX *ctx = NULL; APP_CONN *conn = NULL; - struct addrinfo hints = {0}, *result = NULL; + struct addrinfo hints = { 0 }, *result = NULL; if (argc < 3) { fprintf(stderr, "usage: %s host port\n", argv[0]); @@ -728,15 +728,15 @@ int main(int argc, char **argv) } mlen = snprintf(tx_msg, sizeof(tx_msg), - "GET / HTTP/1.0\r\nHost: %s\r\n\r\n", argv[1]); + "GET / HTTP/1.0\r\nHost: %s\r\n\r\n", argv[1]); ctx = create_ssl_ctx(); if (!ctx) goto fail; - hints.ai_family = AF_INET; - hints.ai_socktype = SOCK_STREAM; - hints.ai_flags = AI_PASSIVE; + hints.ai_family = AF_INET; + hints.ai_socktype = SOCK_STREAM; + hints.ai_flags = AI_PASSIVE; rc = getaddrinfo(argv[1], argv[2], &hints, &result); if (rc < 0) { fprintf(stderr, "cannot resolve\n"); diff --git a/doc/designs/evp_skey.md b/doc/designs/evp_skey.md index 1c8e94966918..74ec53aef65e 100644 --- a/doc/designs/evp_skey.md +++ b/doc/designs/evp_skey.md @@ -102,9 +102,9 @@ EVP_SKEY *EVP_SKEY_generate(OSSL_LIB_CTX *libctx, const char *skeymgmtname, EVP_SKEY *EVP_SKEY_import(OSSL_LIB_CTX *libctx, const char *skeymgmtname, const char *propquery, int selection, const OSSL_PARAM *params); -EVP_SKEY *EVP_SKEY_import_raw(OSSL_LIB_CTX *libctx, const char *skeymgmtname, - const char *key, size_t keylen, - const char *propquery); +EVP_SKEY *EVP_SKEY_import_raw_key(OSSL_LIB_CTX *libctx, const char *skeymgmtname, + unsigned char *key, size_t keylen, + const char *propquery); int EVP_SKEY_up_ref(EVP_SKEY *skey); void EVP_SKEY_free(EVP_SKEY *skey); ``` diff --git a/doc/designs/functions-for-explicitly-fetched-signature-algorithms.md b/doc/designs/functions-for-explicitly-fetched-signature-algorithms.md index cb4df1a40c38..d474c588bd20 100644 --- a/doc/designs/functions-for-explicitly-fetched-signature-algorithms.md +++ b/doc/designs/functions-for-explicitly-fetched-signature-algorithms.md @@ -54,7 +54,7 @@ and `EVP_PKEY_verify()` remain supported. Some more recent verification algorithms need to obtain the signature before processing the data. This is particularly important for streaming modes of operation. -This design proposes a mechanism to accomodate these algorithms +This design proposes a mechanism to accommodate these algorithms and modes of operation. New public API - API Reference diff --git a/doc/designs/ml-dsa.md b/doc/designs/ml-dsa.md index 2504b518890b..efe8138fc5ec 100644 --- a/doc/designs/ml-dsa.md +++ b/doc/designs/ml-dsa.md @@ -103,7 +103,7 @@ the API's used should be OpenSSL command line support ---------------------------- -For backwards compatability reasons `EVP_DigestSignInit_ex()`, +For backwards compatibility reasons `EVP_DigestSignInit_ex()`, `EVP_DigestSign()`, `EVP_DigestVerifyInit_ex()` and `EVP_DigestVerify()` may also be used, but the digest passed in `mdname` must be NULL (i.e. it effectively behaves the same as above). diff --git a/doc/designs/quic-design/quic-concurrency.md b/doc/designs/quic-design/quic-concurrency.md index 55af2a94db98..1f8e23e336c9 100644 --- a/doc/designs/quic-design/quic-concurrency.md +++ b/doc/designs/quic-design/quic-concurrency.md @@ -386,7 +386,7 @@ int ossl_cml_write(QUIC_CML *cml, QUIC_CML_PIPE pipe_handle, /* * Returns the number of bytes a receiving pipe currently has waiting to be * read. The returned value may increase over time asynchronously but will only - * decreate in response to an ossl_cml_read call. + * decrease in response to an ossl_cml_read call. */ size_t ossl_cml_read_available(QUIC_CML *cml, QUIC_CML_PIPE pipe_handle); diff --git a/doc/designs/quic-design/server/quic-polling.md b/doc/designs/quic-design/server/quic-polling.md index 68b2c8a89d61..cda4ffef5e5e 100644 --- a/doc/designs/quic-design/server/quic-polling.md +++ b/doc/designs/quic-design/server/quic-polling.md @@ -1072,7 +1072,7 @@ typedef struct ssl_poll_event_st { * this, applications must still ensure no events in an SSL_POLL_EVENT * structure recorded from a previous call to this function are left over, which * may still reference that poll descriptor. Therefore, applications must still - * excercise caution when freeing resources which are registered, or which were + * exercise caution when freeing resources which are registered, or which were * previously registered in a poll group. */ #define SSL_POLL_FLAG_NO_HANDLE_EVENTS (1U << 0) @@ -1324,13 +1324,13 @@ void process_event(const SSL_POLL_EVENT *event) for (i = 0; i < nevents; ++i) { process_event(&events[i]); /* do something in application */ - /* We have processed the event so now reenable it. */ + /* We have processed the event so now re-enable it. */ SSL_POLL_CHANGE_chflag(chg++, events[i].desc, events[i].instance, SSL_POLL_EVENT_FLAG_DISABLE, 0); ++nchanges; } - /* Reenable any event we processed and go to sleep again. */ + /* Re-enable any event we processed and go to sleep again. */ if (!SSL_POLL_GROUP_change_poll(pg, changes, nchanges, sizeof(changes[0]), events, OSSL_NELEM(events), sizeof(events[0]), NULL, 0, &nevents)) @@ -1419,7 +1419,7 @@ There are two kinds of polling that occur: Firstly, the `SSL_POLL_METHOD` object is defined abstractly as follows: ```c -/* API (Psuedocode) */ +/* API (Pseudocode) */ #define SSL_POLL_METHOD_CAP_IMMEDIATE (1U << 0) /* supports immediate mode */ #define SSL_POLL_METHOD_CAP_RETAINED (1U << 1) /* supports retained mode */ diff --git a/doc/internal/man3/ossl_cmp_certreq_new.pod b/doc/internal/man3/ossl_cmp_certreq_new.pod index 37a234066d36..219ea7a5bcb2 100644 --- a/doc/internal/man3/ossl_cmp_certreq_new.pod +++ b/doc/internal/man3/ossl_cmp_certreq_new.pod @@ -150,7 +150,7 @@ The function does not protect the message if I<unprotectedErrors> is nonzero. =head1 NOTES -CMP is specified in RFC 4210 (and CRMF in RFC 4211). +CMP is specified in RFC 9810 (and CRMF in RFC 4211). =head1 RETURN VALUES diff --git a/doc/internal/man3/ossl_cmp_ctx_set1_caPubs.pod b/doc/internal/man3/ossl_cmp_ctx_set1_caPubs.pod index f3c45ed56c65..3c5cf9f9a7e9 100644 --- a/doc/internal/man3/ossl_cmp_ctx_set1_caPubs.pod +++ b/doc/internal/man3/ossl_cmp_ctx_set1_caPubs.pod @@ -54,7 +54,7 @@ ossl_cmp_ctx_set1_recipNonce() sets the given recipient nonce in the context. =head1 NOTES -CMP is defined in RFC 4210 (and CRMF in RFC 4211). +CMP is defined in RFC 9810. =head1 RETURN VALUES diff --git a/doc/internal/man3/ossl_cmp_hdr_init.pod b/doc/internal/man3/ossl_cmp_hdr_init.pod index a0804aa4cf2a..61bdaad252bf 100644 --- a/doc/internal/man3/ossl_cmp_hdr_init.pod +++ b/doc/internal/man3/ossl_cmp_hdr_init.pod @@ -72,7 +72,7 @@ PKIHeader to the given X509 Name value, without consuming the pointer. If B<nm> is NULL, recipient is set to the NULL DN (the empty list of strings). ossl_cmp_hdr_update_messagetime() (re-)sets the messageTime to the current -system time. As written in RFC 4210, section 5.1.1: +system time. As written in RFC 9810, section 5.1.1: The messageTime field contains the time at which the sender created the message. This may be useful to allow end entities to correct/check their local time for consistency with the time on a central system. @@ -109,13 +109,13 @@ values in the given OSSL_CMP_CTX structure. This starts a new transaction in case ctx->transactionID is NULL. The sender name is copied from the subject of the client cert, if any, or else from the subject name provided for certification requests. -As required by RFC 4210 section 5.1.1., if the sender name is not known +As required by RFC 9810 section 5.1.1., if the sender name is not known to the client it set to the NULL-DN. In this case for identification at least the senderKID must be set, which we take from any referenceValue provided. =head1 NOTES -CMP is defined in RFC 4210 (and CRMF in RFC 4211). +CMP is defined in RFC 9810. =head1 RETURN VALUES diff --git a/doc/internal/man3/ossl_cmp_mock_srv_new.pod b/doc/internal/man3/ossl_cmp_mock_srv_new.pod index 6f4f4fe86ba0..165b68065063 100644 --- a/doc/internal/man3/ossl_cmp_mock_srv_new.pod +++ b/doc/internal/man3/ossl_cmp_mock_srv_new.pod @@ -85,7 +85,7 @@ the client should wait for the next poll. =head1 NOTES -CMP is defined in RFC 4210 (and CRMF in RFC 4211). +CMP is defined in RFC 9810 (and CRMF in RFC 4211). =head1 RETURN VALUES diff --git a/doc/internal/man3/ossl_cmp_msg_check_update.pod b/doc/internal/man3/ossl_cmp_msg_check_update.pod index d1513bf34f0c..2a6a9fccb04c 100644 --- a/doc/internal/man3/ossl_cmp_msg_check_update.pod +++ b/doc/internal/man3/ossl_cmp_msg_check_update.pod @@ -64,7 +64,7 @@ If all checks pass then ossl_cmp_msg_check_update() records in B<ctx> the senderNonce of the received message as the new recipNonce and learns the transaction ID if none is currently present in B<ctx>. -Moreover, according to RFC 4210 section 5.3.2, if the message protection is +Moreover, according to RFC 9810 section 5.3.2, if the message protection is PBM-based then any certificates in the caPubs field are added to the list of trusted certificates (if set via L<OSSL_CMP_CTX_set0_trusted(3)>). This way these certs are available for validating subsequent messages in the diff --git a/doc/internal/man3/ossl_cmp_msg_create.pod b/doc/internal/man3/ossl_cmp_msg_create.pod index d4294d3e9fa6..6a8321cd80bc 100644 --- a/doc/internal/man3/ossl_cmp_msg_create.pod +++ b/doc/internal/man3/ossl_cmp_msg_create.pod @@ -107,7 +107,7 @@ Returns 1 on success, 0 on error. =head1 NOTES -CMP is defined in RFC 4210 (and CRMF in RFC 4211). +CMP is defined in RFC 9810. =head1 RETURN VALUES diff --git a/doc/internal/man3/ossl_cmp_msg_protect.pod b/doc/internal/man3/ossl_cmp_msg_protect.pod index 7e14274f584a..fce51c9840d2 100644 --- a/doc/internal/man3/ossl_cmp_msg_protect.pod +++ b/doc/internal/man3/ossl_cmp_msg_protect.pod @@ -41,7 +41,7 @@ of the chain, i.e, the trust anchor (unless it is part of extraCertsOut). =head1 NOTES -CMP is defined in RFC 4210 (and CRMF in RFC 4211). +CMP is defined in RFC 9810. The I<ctx> parameter of ossl_cmp_msg_add_extraCerts() and thus also of ossl_cmp_msg_protect() cannot be made I<const> diff --git a/doc/internal/man3/ossl_cmp_pkisi_get_status.pod b/doc/internal/man3/ossl_cmp_pkisi_get_status.pod index e44bfd3f0190..df5acbf61d41 100644 --- a/doc/internal/man3/ossl_cmp_pkisi_get_status.pod +++ b/doc/internal/man3/ossl_cmp_pkisi_get_status.pod @@ -60,7 +60,7 @@ Uses data from I<ctx>, which in case of indirect POPO includes the private key. ossl_cmp_pkisi_get_status() returns the PKIStatus of I<si>, or -1 on error. ossl_cmp_PKIStatus_to_string() returns a human-readable string representing -the PKIStatus values as specified in RFC 4210, Appendix F. +the PKIStatus values as specified in RFC 9810, Appendix F. ossl_cmp_pkisi_get0_statusString() returns a direct pointer to the statusString field contained in I<si>. @@ -73,7 +73,7 @@ with index I<index> in the PKIFailureInfo of the I<si>, or -1 on error. =head1 NOTES -CMP is defined in RFC 4210 (and CRMF in RFC 4211). +CMP is defined in RFC 9810. =head1 RETURN VALUES diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in index f44615d1fc18..906143d2927d 100644 --- a/doc/man1/openssl-cmp.pod.in +++ b/doc/man1/openssl-cmp.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-cmp - Certificate Management Protocol (CMP, RFC 4210) application +openssl-cmp - Certificate Management Protocol (CMP, RFCs 9810 and 9811) application =head1 SYNOPSIS @@ -171,7 +171,8 @@ Certificate verification options, for both CMP and TLS: =head1 DESCRIPTION The B<cmp> command is a client implementation for the Certificate -Management Protocol (CMP) as defined in RFC4210. +Management Protocol (CMP) as defined in RFCs 9810 and +its HTTP(S) transfer as defined in RFC 9811. It can be used to request certificates from a CA server, update their certificates, request certificates to be revoked, and perform other types of CMP requests. @@ -439,7 +440,7 @@ Request implicit confirmation of newly enrolled certificates. Do not send certificate confirmation message for newly enrolled certificate without requesting implicit confirmation to cope with broken servers not supporting implicit confirmation correctly. -B<WARNING:> This leads to behavior violating RFC 4210. +B<WARNING:> This leads to behavior violating RFC 9810. =item B<-certout> I<filename> @@ -697,7 +698,7 @@ This applies to the following message types and contents: B<WARNING:> This setting leads to unspecified behavior and it is meant exclusively to allow interoperability with server implementations violating -RFC 4210, e.g.: +RFC 9810, e.g.: =over 4 @@ -813,7 +814,7 @@ This takes precedence over the B<-cert> and B<-key> options. The secret is used for creating MAC-based protection of outgoing messages and for validating incoming messages that have MAC-based protection. The algorithm used by default is Password-Based Message Authentication Code (PBM) -as defined in RFC 4210 section 5.1.3.1. +as defined in RFC 9810 section 5.1.3.1. For more information about the format of I<arg> see L<openssl-passphrase-options(1)>. @@ -837,7 +838,7 @@ this "protection certificate", also called "signer certificate", will be included first in the extraCerts field of outgoing messages and the signature is done with the corresponding key. In Initialization Request (IR) messages this can be used for authenticating -using an external entity certificate as defined in appendix E.7 of RFC 4210. +using an external entity certificate as defined in appendix D.7 of RFC 9810. For Key Update Request (KUR) messages this is also used as the certificate to be updated if the B<-oldcert> option is not given. @@ -880,7 +881,7 @@ L<openssl-passphrase-options(1)>. =item B<-digest> I<name> -Specifies name of supported digest to use in RFC 4210's MSG_SIG_ALG +Specifies name of supported digest to use in RFC 9810's MSG_SIG_ALG and as the one-way function (OWF) in C<MSG_MAC_ALG>. If applicable, this is used for message protection and proof-of-possession (POPO) signatures. @@ -893,7 +894,7 @@ Specifies the name of the MAC algorithm in C<MSG_MAC_ALG>. To get the names of supported MAC algorithms use C<openssl list -mac-algorithms> and possibly combine such a name with the name of a supported digest algorithm, e.g., hmacWithSHA256. -Defaults to C<hmac-sha1> as per RFC 4210. +Defaults to C<hmac-sha1>, for backward compatibility with RFC 4210. =item B<-extracerts> I<filenames>|I<uris> @@ -1113,6 +1114,7 @@ If the transaction contains more requests, the remaining ones are not saved. Save the first CMP requests created by the client to the given file and exit. Any options related to CMP servers and their responses are ignored. +This option does not combine with the B<-port> option. This option is useful for supporting offline scenarios where the certificate request (or any other CMP request) is produced beforehand and sent out later. @@ -1283,7 +1285,7 @@ Send response messages without CMP-level protection. In case of negative responses, server shall send unprotected error messages, certificate responses (IP/CP/KUP), and revocation responses (RP). -WARNING: This setting leads to behavior violating RFC 4210. +WARNING: This setting leads to behavior violating RFC 9810. =item B<-accept_unprotected> @@ -1296,7 +1298,7 @@ So far this has no effect because the server does not accept any error messages. =item B<-accept_raverified> -Accept RAVERIFED as proof of possession (POPO). +Accept RAVERIFIED as proof of possession (POPO). =back diff --git a/doc/man1/openssl-cms.pod.in b/doc/man1/openssl-cms.pod.in index 36f1b3e4a82c..13a436b07660 100644 --- a/doc/man1/openssl-cms.pod.in +++ b/doc/man1/openssl-cms.pod.in @@ -424,7 +424,7 @@ Currently, the AES variants with GCM mode are the only supported AEAD algorithms. If not specified, AES-256-CBC is used as the default. Only used with B<-encrypt> and -B<-EncryptedData_create> commands. +B<-EncryptedData_encrypt> commands. =item B<-wrap> I<cipher> @@ -451,7 +451,7 @@ with caution: see the notes section below. =item B<-md> I<digest> Digest algorithm to use when signing or resigning. If not present then the -default digest algorithm for the signing key will be used (usually SHA1). +default digest algorithm for the signing key will be used (usually SHA-256). =item B<-signer> I<file> @@ -784,7 +784,7 @@ The use of PSS with B<-sign>. The use of OAEP or non-RSA keys with B<-encrypt>. -Additionally the B<-EncryptedData_create> and B<-data_create> type cannot +Additionally the B<-EncryptedData_encrypt> and B<-data_create> type cannot be processed by the older L<openssl-smime(1)> command. =head1 EXAMPLES @@ -931,7 +931,7 @@ The B<-digest> option was added in OpenSSL 3.2. =head1 COPYRIGHT -Copyright 2008-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2008-2026 The OpenSSL Project Authors. All Rights Reserved. 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 diff --git a/doc/man1/openssl-fipsinstall.pod.in b/doc/man1/openssl-fipsinstall.pod.in index d44b4a7dac85..2db5acd24294 100644 --- a/doc/man1/openssl-fipsinstall.pod.in +++ b/doc/man1/openssl-fipsinstall.pod.in @@ -369,7 +369,7 @@ longer allowed. =item B<-self_test_oninstall> -The converse of B<-self_test_oninstall>. The two fields related to the +The converse of B<-self_test_onload>. The two fields related to the "test status indicator" and "MAC status indicator" are written to the output configuration file. This field is not relevant for an OpenSSL FIPS 140-3 provider, since this is no diff --git a/doc/man1/openssl-rehash.pod.in b/doc/man1/openssl-rehash.pod.in index 06a34f6910fa..466ff42aea56 100644 --- a/doc/man1/openssl-rehash.pod.in +++ b/doc/man1/openssl-rehash.pod.in @@ -10,6 +10,7 @@ openssl-rehash, c_rehash - Create symbolic links to files named by the hash values =head1 SYNOPSIS + =for openssl duplicate options B<openssl> diff --git a/doc/man1/openssl-req.pod.in b/doc/man1/openssl-req.pod.in index 4d386ec423cb..a21147575c8b 100644 --- a/doc/man1/openssl-req.pod.in +++ b/doc/man1/openssl-req.pod.in @@ -403,7 +403,7 @@ If an extension is added using this option that has the same OID as one defined in the extension section of the config file, it overrides that one. This option can be given multiple times. -Doing so, the same key most not be given more than once. +Doing so, the same key must not be given more than once. =item B<-precert> diff --git a/doc/man1/openssl-verification-options.pod b/doc/man1/openssl-verification-options.pod index 676fbb38a552..81a11c37f4c4 100644 --- a/doc/man1/openssl-verification-options.pod +++ b/doc/man1/openssl-verification-options.pod @@ -581,7 +581,7 @@ keyCertSign bit set if the keyUsage extension is present. The extKeyUsage (EKU) extension places additional restrictions on certificate use. If this extension is present (whether critical or not) -in an end-entity certficiate, the key is allowed only for the uses specified, +in an end-entity certificate, the key is allowed only for the uses specified, while the special EKU B<anyExtendedKeyUsage> allows for all uses. Note that according to RFC 5280 section 4.2.1.12, @@ -639,7 +639,7 @@ This is used as a workaround if the basicConstraints extension is absent. =item B<Netscape SSL Server> (C<nssslserver>) In addition to what has been described for B<sslserver>, for a Netscape -SSL client to connect to an SSL server, its EE certficate must have the +SSL client to connect to an SSL server, its EE certificate must have the B<keyEncipherment> bit set if the keyUsage extension is present. This isn't always valid because some cipher suites use the key for digital signing. Otherwise it is the same as a normal SSL server. @@ -660,19 +660,19 @@ This is used as a workaround if the basicConstraints extension is absent. =item B<S/MIME Signing> (C<smimesign>) -In addition to the common S/MIME checks, for target certficiates +In addition to the common S/MIME checks, for target certificates the key usage must allow for C<digitalSignature> and/or B<nonRepudiation>. =item B<S/MIME Encryption> (C<smimeencrypt>) -In addition to the common S/MIME checks, for target certficiates +In addition to the common S/MIME checks, for target certificates the key usage must allow for C<keyEncipherment>. =item B<CRL Signing> (C<crlsign>) For target certificates, the key usage must allow for C<cRLSign>. -For all other certifcates the normal CA checks apply. +For all other certificates the normal CA checks apply. Except in this case the basicConstraints extension must be present. =item B<OCSP Helper> (C<ocsphelper>) @@ -680,7 +680,7 @@ Except in this case the basicConstraints extension must be present. For target certificates, no checks are performed at this stage, but special checks apply; see L<OCSP_basic_verify(3)>. -For all other certifcates the normal CA checks apply. +For all other certificates the normal CA checks apply. =item B<Timestamp Signing> (C<timestampsign>) @@ -689,7 +689,7 @@ C<digitalSignature> and/or C<nonRepudiation> and must not include other bits. The EKU extension must be present and contain C<timeStamping> only. Moreover, it must be marked as critical. -For all other certifcates the normal CA checks apply. +For all other certificates the normal CA checks apply. =item B<Code Signing> (C<codesign>) @@ -699,7 +699,7 @@ include <digitalSignature>, but must not include C<keyCertSign> nor C<cRLSign>. The EKU extension must be present and contain C<codeSign>, but must not include C<anyExtendedKeyUsage> nor C<serverAuth>. -For all other certifcates the normal CA checks apply. +For all other certificates the normal CA checks apply. =back diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod index edef2ff59894..635b52aeb120 100644 --- a/doc/man1/openssl.pod +++ b/doc/man1/openssl.pod @@ -722,7 +722,8 @@ For information about specific commands, see L<openssl-engine(1)>, L<openssl-rehash(1)>, and L<tsget(1)>. For information about querying or specifying CPU architecture flags, see -L<OPENSSL_ia32cap(3)>, L<OPENSSL_s390xcap(3)> and L<OPENSSL_riscvcap(3)>. +L<OPENSSL_ia32cap(3)>, L<OPENSSL_ppccap(3)>, L<OPENSSL_s390xcap(3)>, +and L<OPENSSL_riscvcap(3)>. =head1 SEE ALSO diff --git a/doc/man3/BIO_set_flags.pod b/doc/man3/BIO_set_flags.pod new file mode 100644 index 000000000000..7899cc3e5751 --- /dev/null +++ b/doc/man3/BIO_set_flags.pod @@ -0,0 +1,194 @@ +=pod + +=head1 NAME + +BIO_set_flags, BIO_clear_flags, BIO_test_flags, BIO_get_flags, +BIO_set_retry_read, BIO_set_retry_write, BIO_set_retry_special, +BIO_clear_retry_flags, BIO_get_retry_flags +- manipulate and interpret BIO flags + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + void BIO_set_flags(BIO *b, int flags); + void BIO_clear_flags(BIO *b, int flags); + int BIO_test_flags(const BIO *b, int flags); + int BIO_get_flags(const BIO *b); + + void BIO_set_retry_read(BIO *b); + void BIO_set_retry_write(BIO *b); + void BIO_set_retry_special(BIO *b); + void BIO_clear_retry_flags(BIO *b); + int BIO_get_retry_flags(BIO *b); + +=head1 DESCRIPTION + +A B<BIO> has an internal set of bit flags that describe its state. These +functions and macros are used primarily by B<BIO> implementations and by code +that builds B<BIO> chains to manipulate those flags. + +BIO_set_flags() sets the bits given in I<flags> in the B<BIO> I<b>. Any bits +already set in the B<BIO>'s flag word remain set. + +BIO_clear_flags() clears the bits given in I<flags> from the B<BIO> I<b>. Any +other bits in the flag word are left unchanged. + +BIO_test_flags() tests the bits given in I<flags> in the B<BIO> I<b> and +returns a nonzero value if any of them are currently set and zero +otherwise. + +BIO_get_flags() returns the current flag word from the B<BIO> I<b>. This is +equivalent to testing for all bits and returning the result. + +The following convenience macros are built on top of these primitives and are +used to maintain the retry state of a BIO: + +BIO_set_retry_read() marks the B<BIO> I<b> as being in a retryable state +by setting the B<BIO_FLAGS_SHOULD_RETRY> flag. In addition, it sets the +B<BIO_FLAGS_READ> flag to indicate that the retry condition is +associated with a read operation. + +BIO_set_retry_write() marks the B<BIO> I<b> as being in a retryable state +by setting the B<BIO_FLAGS_SHOULD_RETRY> flag. In addition, it sets the +B<BIO_FLAGS_WRITE> flag to indicate that the retry condition is +associated with a write operation. + +BIO_set_retry_special() marks the B<BIO> I<b> as being in a retryable state +by setting the B<BIO_FLAGS_SHOULD_RETRY> flag. In addition, it sets the +B<BIO_FLAGS_IO_SPECIAL> flag to indicate that the retry condition is +associated with a read operation some "special" condition. +The precise meaning of this condition depends on the B<BIO> type. + +BIO_clear_retry_flags() clears all retry-related bits from I<b>, i.e. +B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>, B<BIO_FLAGS_IO_SPECIAL>, and +B<BIO_FLAGS_SHOULD_RETRY>. + +BIO_get_retry_flags() returns retry-related bits that are +currently set in I<b>. The result is a subset of +B<BIO_FLAGS_RWS|BIO_FLAGS_SHOULD_RETRY>. + +The retry bits are interpreted by the higher level macros +BIO_should_read(), BIO_should_write(), BIO_should_io_special(), +BIO_retry_type() and BIO_should_retry(), as documented in +L<BIO_should_retry(3)>. Application code will typically use those macros +rather than manipulate the underlying flags directly. + +The following flag bits are currently defined for use with BIO_set_flags(), +BIO_clear_flags() and BIO_test_flags(): + +=over 4 + +=item B<BIO_FLAGS_READ> + +The last I/O operation should be retried when the B<BIO> becomes readable. +This flag is normally set by the B<BIO> implementation via BIO_set_retry_read() +after a failed read operation. + +=item B<BIO_FLAGS_WRITE> + +The last I/O operation should be retried when the B<BIO> becomes writable. +This flag is normally set by the B<BIO> implementation via BIO_set_retry_write() +after a failed write operation. + +=item B<BIO_FLAGS_IO_SPECIAL> + +The last I/O operation should be retried when some "special" condition +becomes true. The precise meaning of this condition depends on the B<BIO> +type and is usually obtained via BIO_get_retry_BIO() and +BIO_get_retry_reason() as described in L<BIO_should_retry(3)>. +This flag is normally set by the B<BIO> implementation via +BIO_set_retry_special(). + +=item B<BIO_FLAGS_RWS> + +The bitwise OR of B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE> and +B<BIO_FLAGS_IO_SPECIAL>. This mask is used when clearing or extracting +the retry-direction bits. + +=item B<BIO_FLAGS_SHOULD_RETRY> + +Set if the last I/O operation on the B<BIO> should be retried at a later time. +If this bit is not set then the condition is treated as an error. +This flag is normally set by the B<BIO> implementation. + +=item B<BIO_FLAGS_BASE64_NO_NL> + +When set on a base64 filter B<BIO> this flag disables the generation of +newline characters in the encoded output and causes newlines to be ignored +in the input. See also L<BIO_f_base64(3)>. +The flag has no effect on any other built-in B<BIO> types. + +=item B<BIO_FLAGS_MEM_RDONLY> + +When set on a memory B<BIO> this flag indicates that the underlying buffer is +read only. Attempts to write to such a B<BIO> will fail. +The flag has no effect on any other built-in B<BIO> types. + +=item B<BIO_FLAGS_NONCLEAR_RST> + +On a memory B<BIO> this flag modifies the behaviour of BIO_reset(). When it +is set, resetting the B<BIO> does not clear the underlying buffer but only +resets the current read position. +The flag has no effect on any other built-in B<BIO> types. + +=item B<BIO_FLAGS_IN_EOF> + +This flag may be used by a B<BIO> implementation to indicate that the end +of the input stream has been reached. However, B<BIO> types are not +required to use this flag to signal end-of-file conditions; they may rely +on other mechanisms such as system calls or by querying the next B<BIO> in a +chain. Applications must therefore not test this flag directly to +determine whether EOF has been reached, and must use BIO_eof() instead. + +=back + +A range of additional flag values is reserved for internal use by OpenSSL +to track kernel TLS (KTLS) state. This range and the corresponding flag +macros are not part of the public API and must not be used by applications. + +=head1 RETURN VALUES + +BIO_get_flags() returns a bit mask of the flags currently set on the B<BIO>. + +BIO_test_flags() returns a bit mask consisting of those flags from the +argument that are currently set in the B<BIO>. Consequently, it returns a +nonzero value if and only if at least one of the requested flags is set. + +BIO_get_retry_flags() returns a bit mask consisting of those flags from +B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>, B<BIO_FLAGS_IO_SPECIAL>, and +B<BIO_FLAGS_SHOULD_RETRY> that are currently set in the I<BIO>. + +=head1 NOTES + +Ordinary application code will rarely need to call BIO_set_flags(), +BIO_clear_flags() or BIO_test_flags() directly. They are intended for B<BIO> +implementations and for code that forwards retry state from one B<BIO> in a +chain to another. +After a failed I/O operation, applications should normally use +BIO_should_retry() and related macros as described in +L<BIO_should_retry(3)> instead of inspecting the flags directly. + +These functions and macros are not thread-safe. If a single B<BIO> +is accessed from multiple threads, the caller must provide appropriate +external synchronisation. + +=head1 SEE ALSO + +L<BIO_should_retry(3)>, L<BIO_f_base64(3)>, L<bio(7)> + +=head1 HISTORY + +The functions and macros described here have been available in OpenSSL since +at least 1.1.0 (B<BIO_FLAGS_IN_EOF> since 1.1.1). + +=head1 COPYRIGHT + +Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. + +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 +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/CMS_EncryptedData_decrypt.pod b/doc/man3/CMS_EncryptedData_decrypt.pod index fe77701fe017..80bbdcc95f35 100644 --- a/doc/man3/CMS_EncryptedData_decrypt.pod +++ b/doc/man3/CMS_EncryptedData_decrypt.pod @@ -21,10 +21,10 @@ CMS_EncryptedData_decrypt, CMS_EnvelopedData_decrypt =head1 DESCRIPTION CMS_EncryptedData_decrypt() decrypts a I<cms> EncryptedData object using the -symmetric I<key> of size I<keylen> bytes. I<out> is a BIO to write the content -to and I<flags> is an optional set of flags. -I<dcont> is used in the rare case where the encrypted content is detached. It -will normally be set to NULL. +symmetric I<key> of size I<keylen> bytes. AEAD cipher algorithms are not +supported. I<out> is a BIO to write the content to and I<flags> is an optional +set of flags. I<dcont> is used in the rare case where the encrypted content is +detached. It will normally be set to NULL. The following flags can be passed in the I<flags> parameter. diff --git a/doc/man3/CMS_EncryptedData_encrypt.pod b/doc/man3/CMS_EncryptedData_encrypt.pod index d3c3b254be03..5f19edcf9a92 100644 --- a/doc/man3/CMS_EncryptedData_encrypt.pod +++ b/doc/man3/CMS_EncryptedData_encrypt.pod @@ -34,7 +34,7 @@ B<CMS_PARTIAL>. Internally CMS_final() is called unless B<CMS_STREAM> and/or B<CMS_PARTIAL> is specified. The algorithm passed in the I<cipher> parameter must support ASN1 encoding of -its parameters. +its parameters. AEAD cipher algorithms are not supported. The B<CMS_ContentInfo> structure can be freed using L<CMS_ContentInfo_free(3)>. diff --git a/doc/man3/CMS_EncryptedData_set1_key.pod b/doc/man3/CMS_EncryptedData_set1_key.pod new file mode 100644 index 000000000000..0722ef18d2f9 --- /dev/null +++ b/doc/man3/CMS_EncryptedData_set1_key.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +CMS_EncryptedData_set1_key - Sets the cipher and key for +CMS EncryptedData + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int CMS_EncryptedData_set1_key(CMS_ContentInfo *cms, const EVP_CIPHER *ciph, + const unsigned char *key, size_t keylen); + +=head1 DESCRIPTION + +CMS_EncryptedData_set1_key() takes in a I<cms> EncryptedData object and sets +the appropriate attributes to I<ciph>, it makes a copy of the symmetric I<key> +of size I<keylen>. AEAD cipher algorithms are not supported. + +=head1 RETURN VALUES + +CMS_EncryptedData_set1_key() returns 0 if an error occurred otherwise +returns 1. + +=head1 SEE ALSO + +L<CMS_EncryptedData_encrypt(3)>, L<CMS_EncryptedData_decrypt(3)> + +=head1 COPYRIGHT + +Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. + +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 +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/EVP_CIPHER_CTX_get_app_data.pod b/doc/man3/EVP_CIPHER_CTX_get_app_data.pod new file mode 100644 index 000000000000..3865bb439086 --- /dev/null +++ b/doc/man3/EVP_CIPHER_CTX_get_app_data.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + +EVP_CIPHER_CTX_get_app_data, EVP_CIPHER_CTX_set_app_data - Routines to +inspect and modify application data related to EVP_CIPHER_CTX + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx); + void EVP_CIPHER_CTX_set_app_data(EVP_CIPHER_CTX *ctx, void *data); + +=head1 DESCRIPTION + +The functions EVP_CIPHER_CTX_set_app_data() and EVP_CIPHER_CTX_get_app_data() +associate an opaque, application-defined pointer with an EVP_CIPHER_CTX object. + +This pointer is not interpreted by the library and is reserved entirely for use +by the application. It may be used to store arbitrary context or state that +needs to be accessible wherever the corresponding EVP_CIPHER_CTX is available. + +=head1 RETURN VALUES + +The EVP_CIPHER_CTX_get_app_data() function returns a opaque pointer to the +current application data for the EVP_CIPHER_CTX. + +=head1 COPYRIGHT + +Copyright 2026 The OpenSSL Project Authors. All Rights Reserved. + +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 +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index 3c62659319c2..f6b29d9daa9b 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -69,8 +69,6 @@ EVP_CIPHER_CTX_get_block_size, EVP_CIPHER_CTX_get_key_length, EVP_CIPHER_CTX_get_iv_length, EVP_CIPHER_CTX_get_tag_length, -EVP_CIPHER_CTX_get_app_data, -EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_flags, EVP_CIPHER_CTX_set_flags, EVP_CIPHER_CTX_clear_flags, @@ -228,8 +226,6 @@ EVP_CIPHER_CTX_mode int EVP_CIPHER_CTX_get_key_length(const EVP_CIPHER_CTX *ctx); int EVP_CIPHER_CTX_get_iv_length(const EVP_CIPHER_CTX *ctx); int EVP_CIPHER_CTX_get_tag_length(const EVP_CIPHER_CTX *ctx); - void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx); - void EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data); int EVP_CIPHER_CTX_get_type(const EVP_CIPHER_CTX *ctx); int EVP_CIPHER_CTX_get_mode(const EVP_CIPHER_CTX *ctx); int EVP_CIPHER_CTX_get_num(const EVP_CIPHER_CTX *ctx); @@ -1960,7 +1956,7 @@ rather than a 0 return value indicating an error. =head1 COPYRIGHT -Copyright 2000-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2026 The OpenSSL Project Authors. All Rights Reserved. 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 diff --git a/doc/man3/EVP_PKEY_keygen.pod b/doc/man3/EVP_PKEY_keygen.pod index 9cdea5b36220..5e32676cb9a9 100644 --- a/doc/man3/EVP_PKEY_keygen.pod +++ b/doc/man3/EVP_PKEY_keygen.pod @@ -86,10 +86,12 @@ If the callback returns 0 then the key generation operation is aborted and an error occurs. This might occur during a time consuming operation where a user clicks on a "cancel" button. -The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set -and retrieve an opaque pointer. This can be used to set some application -defined value which can be retrieved in the callback: for example a handle -which is used to update a "progress dialog". +The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() +associate an opaque, application-defined pointer with an EVP_PKEY_CTX object. + +This pointer is not interpreted by the library and is reserved entirely for use +by the application. It may be used to store arbitrary context or state that +needs to be accessible wherever the corresponding EVP_PKEY_CTX is available. EVP_PKEY_Q_keygen() abstracts from the explicit use of B<EVP_PKEY_CTX> while providing a 'quick' but limited way of generating a new asymmetric key pair. @@ -239,7 +241,7 @@ EVP_PKEY_Q_keygen() and EVP_PKEY_generate() were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2006-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2006-2026 The OpenSSL Project Authors. All Rights Reserved. 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 diff --git a/doc/man3/EVP_SKEY.pod b/doc/man3/EVP_SKEY.pod index 27ad844d7ed4..5a2f9e182704 100644 --- a/doc/man3/EVP_SKEY.pod +++ b/doc/man3/EVP_SKEY.pod @@ -21,7 +21,7 @@ EVP_SKEY_free, EVP_SKEY_is_a, EVP_SKEY_to_provider const char *propquery, int selection, const OSSL_PARAM *params); EVP_SKEY *EVP_SKEY_import_raw_key(OSSL_LIB_CTX *libctx, const char *skeymgmtname, - unsigned char *key, size_t *len, + unsigned char *key, size_t len, const char *propquery); int EVP_SKEY_export(const EVP_SKEY *skey, int selection, OSSL_CALLBACK *export_cb, void *export_cbarg); @@ -56,8 +56,10 @@ which is used by OpenSSL to store symmetric keys, assigns the B<EVP_SKEYMGMT> object associated with the key, and initializes the object from the B<params> argument. -The EVP_SKEY_import_raw_key() function is a helper that creates an B<EVP_SKEY> object -containing the raw byte representation of the symmetric keys. +The EVP_SKEY_import_raw_key() function is a helper that creates an B<EVP_SKEY> +object containing the raw byte representation of the symmetric keys from the +buffer I<key> having length I<len>. The I<skeymgmtname> defines the name of the +target B<EVP_SKEYMGMT> for the newly created key. The EVP_SKEY_export() function extracts values from a key I<skey> using the I<selection>. I<selection> is described below. It uses a callback I<export_cb> @@ -129,7 +131,7 @@ EVP_SKEY_up_ref() returns 1 for success and 0 on failure. EVP_SKEY_export() and EVP_SKEY_get0_raw_key() return 1 for success and 0 on failure. EVP_SKEY_get0_skeymgmt_name() and EVP_SKEY_get0_provider_name() return the -names of the associated EVP_SKEYMGMT object and its provider correspondigly. +names of the associated EVP_SKEYMGMT object and its provider correspondingly. EVP_SKEY_is_a() returns 1 if I<skey> has the key type I<name>, otherwise 0. @@ -152,7 +154,7 @@ were introduced in OpenSSL 3.5. =head1 COPYRIGHT -Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2025-2026 The OpenSSL Project Authors. All Rights Reserved. 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 diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod index d02eb47e9a6e..bdbf596ec3a5 100644 --- a/doc/man3/OPENSSL_malloc.pod +++ b/doc/man3/OPENSSL_malloc.pod @@ -121,6 +121,10 @@ before ultimately calling OPENSSL_free(). If the argument to OPENSSL_free() is NULL, nothing is done. OPENSSL_cleanse() fills B<ptr> of size B<len> with a string of 0's. +It is useful in cases when it is needed to ensure that memory (that contains +sensitive information) is overwritten (for example, before it is reclaimed, +or when it is stored on stack), and such operation is not optimised out +by compiler optimisations such as dead store elimination (as memset(3) may be). Use OPENSSL_cleanse() with care if the memory is a mapping of a file. If the storage controller uses write compression, then it's possible that sensitive tail bytes will survive zeroization because the block of diff --git a/doc/man3/OPENSSL_ppccap.pod b/doc/man3/OPENSSL_ppccap.pod new file mode 100644 index 000000000000..8434395f3c85 --- /dev/null +++ b/doc/man3/OPENSSL_ppccap.pod @@ -0,0 +1,155 @@ +=pod + +=head1 NAME + +OPENSSL_ppccap - the PowerPC processor capabilities vector + +=head1 SYNOPSIS + + env OPENSSL_ppccap=... <application> + +=head1 DESCRIPTION + +libcrypto supports PowerPC instruction set extensions. These extensions are +represented by bits in the PowerPC capabilities vector. When libcrypto +initializes, it stores the results returned by PowerPC CPU capabilities detection +logic in the PowerPC capabilities vector. The CPU capabilities detection methods +are OS-dependent and use a combination of information gathered by the kernel +during boot and probe functions that attempt to execute instructions and trap +illegal instruction signals with a signal handler. + +To override the set of extensions available to an application, you can set the +B<OPENSSL_ppccap> environment variable before you start the application. The +environment variable is assigned a numerical value that denotes the bits in +the PowerPC capabilities vector. The ppc_arch.h header file states that, "Flags' +usage can appear ambiguous, because they are set rather to reflect OpenSSL +performance preferences than actual processor capabilities." + +Multiple extensions are enabled by logically OR-ing the values that represent the +desired extensions. + +B<Notes>: Enabling an extension on a CPU that does not support the extension +will result in a SIGILL crash. On AIX, all vector instructions can be disabled +with the schedo -ro allow_vmx=0 command. DO NOT USE THIS COMMAND to disable +vector instructions in the OS when it is running on a CPU level that supports the +instructions without also disabling them in libcrpto via the OPENSSL_ppccap +environment variable or the application will crash with a SIGILL. + +Currently, the following extensions are defined: + +=over 4 + +=item 0x01 + +Name: B<PPC_FPU64> + +This flag is obsolete. + +=item 0x02 + +Name: B<PPC_ALTIVEC> + +Meaning: Use AltiVec (aka VMX) instructions. In some but not all cases, this +capability gates the use of later ISA vector instructions. The associated probe +instruction is vor (vector logical or). + +Effect: Enables use of vector instructions but does not enable extensions added +at specific ISA levels. However, disabling this capability disables a subset of +vector extensions added at specific ISA levels even if they are otherwise +enabled. + +=item 0x04 + +Name: B<PPC_CRYPTO207> + +Meaning: Use instructions added in ISA level 2.07. The associated probe +instruction instruction is vcipher (vector AES cipher round). + +Effect: Enables AES, SHA-2 sigma, and other ISA 2.07 instructions for AES, SHA-2, +GHASH, and Poly1305. + +=item 0x08 + +Name: B<PPC_FPU> + +Meaning: Use FPU instructions. The associated probe instruction is fmr (floating +move register). + +Effect: Enables Poly1305 FPU implementation. The PPC_CRYPTO207 capability +overrides this effect. + +=item 0x10 + +Name: B<PPC_MADD300> + +Meaning: Use instructions added in ISA level 3.00. The associated probe +instruction is maddhdu (multiply-add high doubleword unsigned). + +Effect: Enables use of the polynomial multiply and other ISA 3.00 instructions +for AES-GCM, P-384, and P-521. + +=item 0x20 + +Name: B<PPC_MFTB> + +Meaning: Use the mftb (move from time base) instruction. The associated probe +instruction is mftb. + +Effect: Enables use of the mftb instruction to sample the lower 32 bits of the +CPU time base register in order to acquire entropy. Considered obsolete. The +PPC_MFSPR268 capability overrides this capability. + +=item 0x40 + +Name: B<PPC_MFSPR268> + +Meaning: Use the mfspr (move from special purpose register) instruction to +read SPR 268. The associated probe instruction is mfspr 268. + +Effect: Enables use of the mfspr instruction to sample the lower 32 bits of the +CPU time base register from SPR 268, the TBL (time base lower) register, in order +to acquire entropy. + +=item 0x80 + +Name: B<PPC_BRD31> + +Meaning: Use instructions added in ISA level 3.1. The associated probe instruction +is brd (byte-reverse doubleword). + +Effect: Enables use of ISA 3.1 instructions in ChaCha20. + +=back + +=head1 RETURN VALUES + +Not available. + +=head1 EXAMPLES + +Check currently detected capabilities: + + $ openssl info -cpusettings + OPENSSL_ppccap=0x2E + +The detected capabilities in the above example indicate that PPC_MFTB, PPC_FPU, +PPC_CRYPTO207, PPC_MFSPR268, and PPC_ALTIVEC are enabled. + +Disable all instruction set extensions: + + OPENSSL_ppccap=0x00 + +Enable base AltiVec extensions: + + OPENSSL_ppccap=0x02 + +=head1 COPYRIGHT + +Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. + +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 +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/OPENSSL_riscvcap.pod b/doc/man3/OPENSSL_riscvcap.pod index 1ebf20826a7f..3113b98f336f 100644 --- a/doc/man3/OPENSSL_riscvcap.pod +++ b/doc/man3/OPENSSL_riscvcap.pod @@ -189,15 +189,21 @@ Not available. Check currently detected capabilities $ openssl info -cpusettings - OPENSSL_riscvcap=ZBA_ZBB_ZBC_ZBS_V + OPENSSL_riscvcap=RV64GC_ZBA_ZBB_ZBC_ZBS_V vlen:256 + +Note: The first word in the displayed capabilities is the RISC-V base +architecture value, which is derived from the compiler configuration. +It is therefore not overridable by the environment variable. +When the V extension is given the riscv_vlen value is always displayed, +there is no way to override the riscv_vlen by the environment variable. Disables all instruction set extensions: - OPENSSL_riscvcap="rv64gc" + export OPENSSL_riscvcap="rv64gc" Only enable the vector extension: - OPENSSL_riscvcap="rv64gc_v" + export OPENSSL_riscvcap="rv64gc_v" =head1 COPYRIGHT diff --git a/doc/man3/OSSL_CMP_ATAV_set0.pod b/doc/man3/OSSL_CMP_ATAV_set0.pod index 2fe37f794078..8a184a13f836 100644 --- a/doc/man3/OSSL_CMP_ATAV_set0.pod +++ b/doc/man3/OSSL_CMP_ATAV_set0.pod @@ -80,7 +80,7 @@ OSSL_CMP_ATAV_free() deallocates I<atav>. It is defined as a macro. =head1 NOTES -CMP is defined in RFC 4210. CRMF is defined in RFC 4211. +CMP is defined in RFC 9810. CRMF is defined in RFC 4211. =head1 RETURN VALUES diff --git a/doc/man3/OSSL_CMP_CTX_new.pod b/doc/man3/OSSL_CMP_CTX_new.pod index 53e8166228da..a966d9b17c9c 100644 --- a/doc/man3/OSSL_CMP_CTX_new.pod +++ b/doc/man3/OSSL_CMP_CTX_new.pod @@ -287,19 +287,19 @@ is provided as the newPkey or client's pkey component of the CMP context. =item B<OSSL_CMP_OPT_DIGEST_ALGNID> -The NID of the digest algorithm to be used in RFC 4210's MSG_SIG_ALG +The NID of the digest algorithm to be used in RFC 9810's MSG_SIG_ALG for signature-based message protection and Proof-of-Possession (POPO). Default is SHA256. =item B<OSSL_CMP_OPT_OWF_ALGNID> The NID of the digest algorithm to be used as one-way function (OWF) for MAC-based message protection with password-based MAC (PBM). -See RFC 4210 section 5.1.3.1 for details. +See RFC 9810 section 5.1.3.1 for details. Default is SHA256. =item B<OSSL_CMP_OPT_MAC_ALGNID> The NID of the MAC algorithm to be used for message protection with PBM. -Default is HMAC-SHA1 as per RFC 4210. +Default is HMAC-SHA1, for backward compatibility with RFC 4210. =item B<OSSL_CMP_OPT_REVOCATION_REASON> @@ -319,7 +319,7 @@ Do not confirm enrolled certificates, to cope with broken servers not supporting implicit confirmation correctly. B<WARNING:> This setting leads to unspecified behavior and it is meant exclusively to allow interoperability with server implementations violating -RFC 4210. +RFC 9810. =item B<OSSL_CMP_OPT_UNPROTECTED_SEND> @@ -333,7 +333,7 @@ error messages as well as certificate responses (IP/CP/KUP) and revocation responses (RP) with rejection. B<WARNING:> This setting leads to unspecified behavior and it is meant exclusively to allow interoperability with server implementations violating -RFC 4210. +RFC 9810. =item B<OSSL_CMP_OPT_IGNORE_KEYUSAGE> @@ -543,7 +543,7 @@ messages that have MAC-based protection (protectionAlg = C<MSG_MAC_ALG>). OSSL_CMP_CTX_set1_referenceValue() sets the given referenceValue I<ref> with length I<len> in the given I<ctx> or clears it if the I<ref> argument is NULL. -According to RFC 4210 section 5.1.1, if no value for the sender field in +According to RFC 9810 section 5.1.1, if no value for the sender field in CMP message headers can be determined (i.e., no CMP signer certificate and no subject DN is set via OSSL_CMP_CTX_set1_subjectName() then the sender field will contain the NULL-DN @@ -756,7 +756,7 @@ the I<ctx>. This will be used to validate the recipNonce in incoming messages. =head1 NOTES -CMP is defined in RFC 4210 (and CRMF in RFC 4211). +CMP is defined in RFC 9810 (and CRMF in RFC 4211). =head1 RETURN VALUES diff --git a/doc/man3/OSSL_CMP_HDR_get0_transactionID.pod b/doc/man3/OSSL_CMP_HDR_get0_transactionID.pod index 6e79e9a0e3c3..a66d1b88b5a7 100644 --- a/doc/man3/OSSL_CMP_HDR_get0_transactionID.pod +++ b/doc/man3/OSSL_CMP_HDR_get0_transactionID.pod @@ -30,7 +30,7 @@ in the generalInfo field of the given PKIHeader. =head1 NOTES -CMP is defined in RFC 4210. +CMP is defined in RFC 9810. =head1 RETURN VALUES diff --git a/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod b/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod index ce555d16e6ac..f7f3a24494bf 100644 --- a/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod +++ b/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod @@ -173,7 +173,7 @@ B<algId> or B<rsaKeyLen> and assigns to I<*keySpec> a copy of the keySpec field. =head1 NOTES -CMP is defined in RFC 4210. +CMP is defined in RFC 9810. =head1 RETURN VALUES diff --git a/doc/man3/OSSL_CMP_ITAV_set0.pod b/doc/man3/OSSL_CMP_ITAV_set0.pod index 13d7868a6deb..0b4c76e6a76a 100644 --- a/doc/man3/OSSL_CMP_ITAV_set0.pod +++ b/doc/man3/OSSL_CMP_ITAV_set0.pod @@ -29,7 +29,7 @@ OSSL_CMP_ITAV_get0_certProfile =head1 DESCRIPTION -ITAV is short for InfoTypeAndValue. This type is defined in RFC 4210 +ITAV is short for InfoTypeAndValue. This type is defined in RFC 9810 section 5.3.19 and Appendix F. It is used at various places in CMP messages, e.g., in the generalInfo PKIHeader field, to hold a key-value pair. @@ -61,7 +61,7 @@ It is an error if the infoType of I<itav> is not B<certProfile>. =head1 NOTES -CMP is defined in RFC 4210 and RFC 9480 (and CRMF in RFC 4211). +CMP is defined in RFC 9810. OIDs to use as types in B<OSSL_CMP_ITAV> can be found at L<https://datatracker.ietf.org/doc/html/rfc9480#section-4.2.2>. diff --git a/doc/man3/OSSL_CMP_MSG_get0_header.pod b/doc/man3/OSSL_CMP_MSG_get0_header.pod index f8f535f30b02..9ba221190928 100644 --- a/doc/man3/OSSL_CMP_MSG_get0_header.pod +++ b/doc/man3/OSSL_CMP_MSG_get0_header.pod @@ -114,7 +114,7 @@ to BIO I<bio>. =head1 NOTES -CMP is defined in RFC 4210. +CMP is defined in RFC 9810. =head1 RETURN VALUES diff --git a/doc/man3/OSSL_CMP_MSG_http_perform.pod b/doc/man3/OSSL_CMP_MSG_http_perform.pod index c8d1a4fb47e7..89dc637f0ed3 100644 --- a/doc/man3/OSSL_CMP_MSG_http_perform.pod +++ b/doc/man3/OSSL_CMP_MSG_http_perform.pod @@ -43,8 +43,8 @@ such as L<OSSL_HTTP_proxy_connect(3)>. =head1 NOTES -CMP is defined in RFC 4210. -HTTP transfer for CMP is defined in RFC 6712. +CMP is defined in RFC 9810. +HTTP transfer for CMP is defined in RFC 9811. =head1 RETURN VALUES diff --git a/doc/man3/OSSL_CMP_SRV_CTX_new.pod b/doc/man3/OSSL_CMP_SRV_CTX_new.pod index 7484a7a04966..34862a090680 100644 --- a/doc/man3/OSSL_CMP_SRV_CTX_new.pod +++ b/doc/man3/OSSL_CMP_SRV_CTX_new.pod @@ -107,6 +107,7 @@ which may be due to normal successful end of the transaction or due to an error. OSSL_CMP_CTX_server_perform() is an interface to OSSL_CMP_SRV_process_request() that can be used by a CMP client in the same way as L<OSSL_CMP_MSG_http_perform(3)>. +In particular, the first parameter I<client_ctx> is the B<OSSL_CMP_CTX> of the client. The B<OSSL_CMP_SRV_CTX> must be set as I<transfer_cb_arg> of I<client_ctx>. OSSL_CMP_SRV_CTX_new() creates and initializes an B<OSSL_CMP_SRV_CTX> structure @@ -157,7 +158,7 @@ confirmation of newly enrolled certificates if requested. =head1 NOTES -CMP is defined in RFC 4210 (and CRMF in RFC 4211). +CMP is defined in RFC 9810 (and CRMF in RFC 4211). So far the CMP server implementation is limited to one request per CMP message (and consequently to at most one response component per CMP message). diff --git a/doc/man3/OSSL_CMP_STATUSINFO_new.pod b/doc/man3/OSSL_CMP_STATUSINFO_new.pod index 9c5ce577c734..edca81133ad6 100644 --- a/doc/man3/OSSL_CMP_STATUSINFO_new.pod +++ b/doc/man3/OSSL_CMP_STATUSINFO_new.pod @@ -39,7 +39,7 @@ in the given buffer, with the given maximal length. =head1 NOTES -CMP is defined in RFC 4210 (and CRMF in RFC 4211). +CMP is defined in RFC 9810. =head1 RETURN VALUES diff --git a/doc/man3/OSSL_CMP_exec_certreq.pod b/doc/man3/OSSL_CMP_exec_certreq.pod index ce6826c6754b..1bc4d795b61c 100644 --- a/doc/man3/OSSL_CMP_exec_certreq.pod +++ b/doc/man3/OSSL_CMP_exec_certreq.pod @@ -119,7 +119,7 @@ otherwise the issuer DN and serial number of the certificate set by L<OSSL_CMP_CTX_set1_oldCert(3)>, otherwise the subject DN and public key of the certificate signing request set by L<OSSL_CMP_CTX_set1_p10CSR(3)>. -RFC 4210 is vague in which PKIStatus should be returned by the server. +RFC 9810 is vague in which PKIStatus should be returned by the server. We take "accepted" and "grantedWithMods" as clear success and handle "revocationWarning" and "revocationNotification" just as warnings because CAs typically return them as an indication that the certificate was already revoked. @@ -138,7 +138,7 @@ and returns the list of B<ITAV>s received in a genp response message. This can be used, for instance, with infoType C<signKeyPairTypes> to obtain the set of signature algorithm identifiers that the CA will certify for subject public keys. -See RFC 4210 section 5.3.19 and appendix E.5 for details. +See RFC 9810 section 5.3.19 and appendix D.5 for details. Functions implementing more specific genm/genp exchanges are described next. OSSL_CMP_get1_caCerts() uses a genm/genp message exchange with infoType caCerts @@ -151,7 +151,7 @@ OSSL_CMP_get1_rootCaKeyUpdate() uses a genm request message with infoType rootCaCert to obtain from the CMP server referenced by I<ctx> in a genp response message with infoType rootCaKeyUpdate any update of the given root CA certificate I<oldWithOld> and verifies it as far as possible. -See RFC 4210 section 4.4 for details. +See RFC 9810 section 4.4 for details. On success it assigns to I<*newWithNew> the root certificate received. When the I<newWithOld> and I<oldWithNew> output parameters are not NULL, it assigns to them the corresponding transition certificates. @@ -183,7 +183,7 @@ Both must be freed by the caller. =head1 NOTES -CMP is defined in RFC 4210 (and CRMF in RFC 4211). +CMP is defined in RFC 9810 (and CRMF in RFC 4211). The CMP client implementation is limited to one request per CMP message (and consequently to at most one response component per CMP message). diff --git a/doc/man3/OSSL_CMP_validate_msg.pod b/doc/man3/OSSL_CMP_validate_msg.pod index af060a8eb8a0..25d0a1bb3c33 100644 --- a/doc/man3/OSSL_CMP_validate_msg.pod +++ b/doc/man3/OSSL_CMP_validate_msg.pod @@ -60,7 +60,7 @@ verification callback) and non-trusted intermediate certs from the I<ctx>. =head1 NOTES -CMP is defined in RFC 4210 (and CRMF in RFC 4211). +CMP is defined in RFC 9810. =head1 RETURN VALUES diff --git a/doc/man3/OSSL_CRMF_MSG_get0_tmpl.pod b/doc/man3/OSSL_CRMF_MSG_get0_tmpl.pod index 0f700c118f55..a8a5a36b68a9 100644 --- a/doc/man3/OSSL_CRMF_MSG_get0_tmpl.pod +++ b/doc/man3/OSSL_CRMF_MSG_get0_tmpl.pod @@ -92,7 +92,7 @@ of the given CertId I<cid>, which must be of ASN.1 type GEN_DIRNAME. OSSL_CRMF_ENCRYPTEDKEY_get1_encCert() decrypts the certificate in the given encryptedKey I<ecert>, using the private key I<pkey>, library context I<libctx> and property query string I<propq> (see L<OSSL_LIB_CTX(3)>). -This is needed for the indirect POPO method as in RFC 4210 section 5.2.8.2. +This is needed for the indirect POPO method as in RFC 9810 section 5.2.8.3.2. The function returns the decrypted certificate as a copy, leaving its ownership with the caller, who is responsible for freeing it. @@ -119,7 +119,7 @@ I<libctx> and property query string I<propq> (see L<OSSL_LIB_CTX(3)>). OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert() decrypts the certificate in the given encryptedValue I<ecert>, using the private key I<pkey>, library context I<libctx> and property query string I<propq> (see L<OSSL_LIB_CTX(3)>). -This is needed for the indirect POPO method as in RFC 4210 section 5.2.8.2. +This is needed for the indirect POPO method as in RFC 9810 section 5.2.8.3.2. The function returns the decrypted certificate as a copy, leaving its ownership with the caller, who is responsible for freeing it. diff --git a/doc/man3/OSSL_CRMF_pbmp_new.pod b/doc/man3/OSSL_CRMF_pbmp_new.pod index ff8b3c327cd2..66125f8c50fd 100644 --- a/doc/man3/OSSL_CRMF_pbmp_new.pod +++ b/doc/man3/OSSL_CRMF_pbmp_new.pod @@ -43,14 +43,15 @@ for the random number generation (DRBG) and may be NULL for the default. The algorithms for the OWF (one-way function) and for the MAC (message authentication code) may be any with a NID defined in F<< <openssl/objects.h> >>. -As specified by RFC 4210, these should include NID_hmac_sha1. +For backward compatibility with RFC 4210, these should include NID_hmac_sha1. -RFC 4210 recommends that the salt SHOULD be at least 8 bytes (64 bits) long, +RFC 4210 recommended that the salt SHOULD be at least 8 bytes (64 bits) long, where 16 bytes is common. The iteration count must be at least 100, as stipulated by RFC 4211, and is limited to at most 100000 to avoid DoS through manipulated or otherwise malformed input. +See RFC 9045 for currently suggested values. =head1 RETURN VALUES diff --git a/doc/man3/OSSL_DECODER_CTX.pod b/doc/man3/OSSL_DECODER_CTX.pod index 33b09c836db8..96111c4e32dd 100644 --- a/doc/man3/OSSL_DECODER_CTX.pod +++ b/doc/man3/OSSL_DECODER_CTX.pod @@ -167,6 +167,13 @@ I<reference>, unpacks the object which it refers to, and exports it by creating an L<OSSL_PARAM(3)> array that it then passes to I<export_cb>, along with I<export_arg>. +Note that functions OSSL_DECODER_CTX_set_selection(), +OSSL_DECODER_CTX_set_output_type(), OSSL_DECODER_CTX_set_output_structure(), +OSSL_DECODER_CTX_add_encoder(), OSSL_DECODER_CTX_add_extra(), +OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data(), and +OSSL_DECODER_CTX_set_cleanup() shouldn't be used after the context is finalised, +in particular after calling the function OSSL_DECODER_CTX_new_for_pkey(). + =head2 Constructor A B<OSSL_DECODER_CONSTRUCT> gets the following arguments: diff --git a/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod b/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod index e55212ad554b..9539f21ccf92 100644 --- a/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod +++ b/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod @@ -71,6 +71,10 @@ zero). This helps the caller to distinguish between an error when creating the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to act accordingly. +Note that OSSL_DECODER_CTX_new_for_pkey() finalises the OSSL_DECODER_CTX; +after that the OSSL_DECODER_CTX_set_* and OSSL_DECODER_CTX_add_* functions +described in L<OSSL_DECODER_CTX(3)> shouldn't be called. + OSSL_DECODER_CTX_set_passphrase() gives the implementation a pass phrase to use when decrypting the encoded private key. Alternatively, a pass phrase callback may be specified with the following functions. diff --git a/doc/man3/OSSL_ENCODER_CTX.pod b/doc/man3/OSSL_ENCODER_CTX.pod index e9248c356a05..ab1bfa9c0c35 100644 --- a/doc/man3/OSSL_ENCODER_CTX.pod +++ b/doc/man3/OSSL_ENCODER_CTX.pod @@ -130,6 +130,13 @@ passed to the constructor every time it's called. OSSL_ENCODER_CTX_set_cleanup() sets the constructor data I<cleanup> function. This is called by L<OSSL_ENCODER_CTX_free(3)>. +Note that functions OSSL_ENCODER_CTX_set_selection(), +OSSL_ENCODER_CTX_set_output_type(), OSSL_ENCODER_CTX_set_output_structure(), +OSSL_ENCODER_CTX_add_encoder(), OSSL_ENCODER_CTX_add_extra(), +OSSL_ENCODER_CTX_set_construct(), OSSL_ENCODER_CTX_set_construct_data(), and +OSSL_ENCODER_CTX_set_cleanup() shouldn't be used after the context is finalised, +in particular after calling the function OSSL_ENCODER_CTX_new_for_pkey(). + =head2 Constructor A B<OSSL_ENCODER_CONSTRUCT> gets the following arguments: @@ -202,6 +209,12 @@ output type. OSSL_ENCODER_INSTANCE_get_output_structure() returns a string with the name of the output structure. +=head1 NOTES AND BUGS + +The chain mechanism in ENCODE is not yet completely implemented. +It affects functions such as OSSL_ENCODER_CTX_add_extra and the +inner processing loop. + =head1 SEE ALSO L<provider(7)>, L<OSSL_ENCODER(3)> diff --git a/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod b/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod index 3bf9c10e374e..072659d07ece 100644 --- a/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod +++ b/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod @@ -60,6 +60,10 @@ zero). This helps the caller to distinguish between an error when creating the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to act accordingly. +Note that OSSL_ENCODER_CTX_new_for_pkey() finalises the OSSL_ENCODER_CTX; +after that the OSSL_ENCODER_CTX_set_* and OSSL_ENCODER_CTX_add_* functions +described in L<OSSL_ENCODER_CTX(3)> shouldn't be called. + OSSL_ENCODER_CTX_set_cipher() tells the implementation what cipher should be used to encrypt encoded keys. The cipher is given by name I<cipher_name>. The interpretation of that I<cipher_name> is diff --git a/doc/man3/OSSL_PROVIDER.pod b/doc/man3/OSSL_PROVIDER.pod index 1c1818a1f065..f90b5d7a9efe 100644 --- a/doc/man3/OSSL_PROVIDER.pod +++ b/doc/man3/OSSL_PROVIDER.pod @@ -206,7 +206,7 @@ I<capability>. For each capability of that name supported by the provider it will call the callback I<cb> and supply a set of L<OSSL_PARAM(3)>s describing the capability. It will also pass back the argument I<arg>. For more details about capabilities and what they can be used for please see -L<provider-base(7)/CAPABILTIIES>. +L<provider-base(7)/CAPABILITIES>. =head1 RETURN VALUES diff --git a/doc/man3/SSL_CONF_cmd.pod b/doc/man3/SSL_CONF_cmd.pod index 9338ffc01ddf..3e2de6e66be7 100644 --- a/doc/man3/SSL_CONF_cmd.pod +++ b/doc/man3/SSL_CONF_cmd.pod @@ -408,6 +408,11 @@ Padding attempts to pad TLSv1.3 records so that they are a multiple of the set length on send. A value of 0 or 1 turns off padding as relevant. Otherwise, the values must be >1 or <=16384. +Note that, for QUIC objects, padding is always performed at the +packet level, and so cannot be done at the record level. Given that, when the +config file is created, there is no knowledge of what kind of SSL objects are +being created, this option is silently ignored for QUIC objects. + =item B<SignatureAlgorithms> This sets the supported signature algorithms for TLSv1.2 and TLSv1.3. diff --git a/doc/man3/SSL_CTX_set_cert_verify_callback.pod b/doc/man3/SSL_CTX_set_cert_verify_callback.pod index 4d510f3041d4..d93916f3b248 100644 --- a/doc/man3/SSL_CTX_set_cert_verify_callback.pod +++ b/doc/man3/SSL_CTX_set_cert_verify_callback.pod @@ -63,6 +63,11 @@ on resumption, even though no chain is presented int that case. Moreover, the calling application will be informed about the detailed result of the verification procedure and may elect to base further decisions on it. +I<callback> may call L<X509_verify_cert(3)> to run the built-in verification +function. This may be useful if application wishes to dynamically reconfigure +I<x509_store_ctx> before verification, or postprocess the result. In this case, +L<X509_verify_cert(3)> will set the B<error> member as described above. + Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback> function set using L<SSL_CTX_set_verify(3)>. diff --git a/doc/man3/SSL_CTX_set_client_hello_cb.pod b/doc/man3/SSL_CTX_set_client_hello_cb.pod index 74468ab8ac15..6367c68a6250 100644 --- a/doc/man3/SSL_CTX_set_client_hello_cb.pod +++ b/doc/man3/SSL_CTX_set_client_hello_cb.pod @@ -69,6 +69,9 @@ holding the numerical value of the TLS extension types in the order they appear in the ClientHello. B<*outlen> contains the number of elements in the array. In situations when the ClientHello has no extensions, the function will return success with B<*out> set to NULL and B<*outlen> set to 0. +Note that SSL_client_hello_get1_extensions_present() returns only recognised +extensions; therefore, unrecognised (including GREASE) extensions will not +appear in the output. SSL_client_hello_get_extension_order() is similar to SSL_client_hello_get1_extensions_present(), without internal memory allocation. @@ -101,8 +104,12 @@ not use a servername callback, in order to avoid unexpected behavior that occurs due to the relative order of processing between things like session resumption and the historical servername callback. -The SSL_client_hello_* family of functions may only be called from code executing -within a ClientHello callback. +The SSL_client_hello_* family of functions may only be called from code +executing within a ClientHello callback. + +The SSL_client_hello_get0_*() functions return raw ClientHello data, whereas +SSL_client_hello_get1_extensions_present() returns only recognized extensions +(so unknown/GREASE-extensions are not included). =head1 RETURN VALUES diff --git a/doc/man3/SSL_CTX_set_domain_flags.pod b/doc/man3/SSL_CTX_set_domain_flags.pod index cc9ad5911498..6c1264288957 100644 --- a/doc/man3/SSL_CTX_set_domain_flags.pod +++ b/doc/man3/SSL_CTX_set_domain_flags.pod @@ -42,7 +42,7 @@ Specifying this flag configures the Single-Threaded Concurrency Model (SCM). =item B<SSL_DOMAIN_FLAG_MULTI_THREAD> -Speciyfing this flag configures the Contentive Concurrency Model (CCM) (unless +Specifying this flag configures the Contentive Concurrency Model (CCM) (unless B<SSL_DOMAIN_FLAG_THREAD_ASSISTED> is also specified). If OpenSSL was built without thread support, this is identical to diff --git a/doc/man3/SSL_get_error.pod b/doc/man3/SSL_get_error.pod index 794598facb33..799e16dd5a3a 100644 --- a/doc/man3/SSL_get_error.pod +++ b/doc/man3/SSL_get_error.pod @@ -23,7 +23,8 @@ current thread's OpenSSL error queue. Thus, SSL_get_error() must be used in the same thread that performed the TLS/SSL I/O operation, and no other OpenSSL function calls should appear in between. The current thread's error queue must be empty before the TLS/SSL I/O operation is -attempted, or SSL_get_error() will not work reliably. +attempted, or SSL_get_error() will not work reliably. Emptying the +current thread's error queue is done with L<ERR_clear_error(3)>. =head1 NOTES @@ -181,9 +182,13 @@ connection and SSL_shutdown() must not be called. =back +The OpenSSL error queue can be inspected with the B<ERR> family of functions, +such as L<ERR_print_errors(3)> and L<ERR_peek_last_error_all(3)>. + =head1 SEE ALSO -L<ssl(7)> +L<ssl(7)>, +L<ERR_clear_error(3)>, ERR_print_errors(3), ERR_peek_last_error_all(3) =head1 HISTORY diff --git a/doc/man3/SSL_set_quic_tls_cbs.pod b/doc/man3/SSL_set_quic_tls_cbs.pod index 75d217bdeaa6..65dab1d974b4 100644 --- a/doc/man3/SSL_set_quic_tls_cbs.pod +++ b/doc/man3/SSL_set_quic_tls_cbs.pod @@ -70,6 +70,11 @@ given SSL object I<s>, a set of callbacks are supplied in an B<OSSL_DISPATCH> table via I<qtdis>. The I<arg> parameter will be passed as an argument when the various callbacks are called. +The above callbacks are invoked, as needed, by SSL_do_handshake() and SSL_read() (including +SSL_read_ex, SSL_peek, SSL_peek_ex). Once the SSL handshake is complete, the QUIC +stack must arrange to call one of the SSL_read() variants whenever a post-handshake CRYPTO +frame is received. The number of bytes requested may be zero. + An B<OSSL_DISPATCH> table should consist of an array of B<OSSL_DISPATCH> entries where each entry is a function id, and a function pointer. The array should be terminated with an empty entry (i.e. a 0 function id, and a NULL function diff --git a/doc/man3/UI_new.pod b/doc/man3/UI_new.pod index eb80f453d5c6..613dd4ce6dce 100644 --- a/doc/man3/UI_new.pod +++ b/doc/man3/UI_new.pod @@ -159,17 +159,20 @@ With the description "pass phrase" and the filename "foo.key", that becomes string and may include encodings that will be processed by the other method functions. -UI_add_user_data() adds a user data pointer for the method to use at any +UI_add_user_data() sets the user data pointer for the method to use at any time. The built-in UI method doesn't care about this info. Note that several -calls to this function doesn't add data, it replaces the previous blob +calls to this function doesn't add data, it replaces the previous pointer with the one given as argument. +The return value is the previously set user data pointer if it was set +using UI_add_user_data() and thus the caller owns it, otherwise NULL. UI_dup_user_data() duplicates the user data and works as an alternative to UI_add_user_data() when the user data needs to be preserved for a longer duration, perhaps even the lifetime of the application. The UI object takes ownership of this duplicate and will free it whenever it gets replaced or the UI is destroyed. UI_dup_user_data() returns 0 on success, or -1 on memory -allocation failure or if the method doesn't have a duplicator function. +allocation failure or if the method doesn't have a duplicator and a destructor +function. UI_get0_user_data() retrieves the data that has last been given to the UI with UI_add_user_data() or UI_dup_user_data. @@ -224,6 +227,9 @@ is less than or equal to 0 otherwise. UI_construct_prompt() returns a string or NULL if an error occurred. +UI_add_user_data() returns +the user data pointer previously set using this function, otherwise NULL. + UI_dup_user_data() returns 0 on success or -1 on error. UI_get0_result() returns a string or NULL on error. @@ -245,7 +251,7 @@ The UI_dup_user_data() function was added in OpenSSL 1.1.1. =head1 COPYRIGHT -Copyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2001-2026 The OpenSSL Project Authors. All Rights Reserved. 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 diff --git a/doc/man3/X509_STORE_get0_param.pod b/doc/man3/X509_STORE_get0_param.pod index 95a1725bc388..794b149e6616 100644 --- a/doc/man3/X509_STORE_get0_param.pod +++ b/doc/man3/X509_STORE_get0_param.pod @@ -25,8 +25,9 @@ parameters for I<xs>. The returned pointer must not be freed by the calling application X509_STORE_get1_objects() returns a snapshot of all objects in the store's X509 -cache. The cache contains B<X509> and B<X509_CRL> objects. The caller is -responsible for freeing the returned list. +cache. The cache contains B<X509> and B<X509_CRL> objects. The caller +is responsible for freeing the returned list, +using sk_X509_OBJECT_pop_free(sk, X509_OBJECT_free). X509_STORE_get0_objects() retrieves an internal pointer to the store's X509 object cache. The cache contains B<X509> and B<X509_CRL> objects. The @@ -35,7 +36,8 @@ shared across multiple threads, it is not safe to use the result of this function. Use X509_STORE_get1_objects() instead, which avoids this problem. X509_STORE_get1_all_certs() returns a list of all certificates in the store. -The caller is responsible for freeing the returned list. +The caller is responsible for freeing the returned list +with OSSL_STACK_OF_X509_free(). =head1 RETURN VALUES @@ -54,6 +56,7 @@ certificates on success, else NULL. =head1 SEE ALSO +L<DEFINE_STACK_OF(3)>, L<X509_STORE_new(3)> =head1 HISTORY diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod index 8e04c2286c57..41e76ae8379b 100644 --- a/doc/man3/d2i_X509.pod +++ b/doc/man3/d2i_X509.pod @@ -592,6 +592,10 @@ B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>(), as well as i2d_ASN1_bio_stream(), return 1 for success and 0 if an error occurs. +On error, these functions may record the error in the OpenSSL error queue. +That error queue can be inspected with the B<ERR> family of functions, such as +L<ERR_print_errors(3)> and L<ERR_peek_last_error_all(3)>. + =head1 EXAMPLES Allocate and encode the DER encoding of an X509 structure: @@ -704,6 +708,10 @@ structure has been modified after deserialization or previous serialization. This is because some objects cache the encoding for efficiency reasons. +=head1 SEE ALSO + +ERR_print_errors(3), ERR_peek_last_error_all(3) + =head1 HISTORY d2i_OSSL_ATTRIBUTES_SYNTAX(), d2i_OSSL_BASIC_ATTR_CONSTRAINTS(), diff --git a/doc/man7/EVP_PKEY-ML-DSA.pod b/doc/man7/EVP_PKEY-ML-DSA.pod index 3948fe6a5a45..e87053b0a183 100644 --- a/doc/man7/EVP_PKEY-ML-DSA.pod +++ b/doc/man7/EVP_PKEY-ML-DSA.pod @@ -19,7 +19,7 @@ and the private key I<priv>. Each of the different key types has an associated security category. This value is one of 2, 3 or 5 for key types B<ML-DSA-44>, B<ML-DSA-65> and B<ML-DSA-87> respectively, which correspond to security strengths of -128, 192 and 256 repsectively. +128, 192 and 256 respectively. =head2 Keygen Parameters diff --git a/doc/man7/EVP_PKEY-ML-KEM.pod b/doc/man7/EVP_PKEY-ML-KEM.pod index ea9a5f0b4119..be12a50ccff8 100644 --- a/doc/man7/EVP_PKEY-ML-KEM.pod +++ b/doc/man7/EVP_PKEY-ML-KEM.pod @@ -110,7 +110,7 @@ configuration options programmatically. =item C<ml-kem.import_pct_type> (B<OSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE>) <UTF8 string> -When an B<ML-KEM> key is imported as an explict FIPS 203 B<dk> decapsulation +When an B<ML-KEM> key is imported as an explicit FIPS 203 B<dk> decapsulation key, rather than a seed, a pairwise consistency test (PCT) is optionally performed. By default, or when this parameter is set explicitly to C<random>, the PCT diff --git a/doc/man7/EVP_SIGNATURE-ED25519.pod b/doc/man7/EVP_SIGNATURE-ED25519.pod index 924f254aad0f..559968664e1a 100644 --- a/doc/man7/EVP_SIGNATURE-ED25519.pod +++ b/doc/man7/EVP_SIGNATURE-ED25519.pod @@ -134,6 +134,9 @@ since version 1.1.1. Valid algorithm names are B<ed25519>, B<ed448> and B<eddsa>. If B<eddsa> is specified, then both Ed25519 and Ed448 are benchmarked. +Since Ed25519ctx is not included in FIPS 186-5, it is not present +in the FIPS provider. + =head1 EXAMPLES To sign a message using an ED25519 EVP_PKEY structure: diff --git a/doc/man7/EVP_SIGNATURE-ML-DSA.pod b/doc/man7/EVP_SIGNATURE-ML-DSA.pod index 3b6e795f0709..c9ccf1aafb8e 100644 --- a/doc/man7/EVP_SIGNATURE-ML-DSA.pod +++ b/doc/man7/EVP_SIGNATURE-ML-DSA.pod @@ -17,7 +17,7 @@ L<FIPS 204|https://csrc.nist.gov/pubs/fips/204/final> 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. -L<EVP_SIGNATURE_fetch(3)> can be used to explicitely fetch one of the 3 +L<EVP_SIGNATURE_fetch(3)> can be used to explicitly fetch one of the 3 algorithms which can then be used with L<EVP_PKEY_sign_message_init(3)>, L<EVP_PKEY_sign(3)>, L<EVP_PKEY_verify_message_init(3)>, and L<EVP_PKEY_verify(3)> to perform one-shot message signing or signature verification. @@ -87,7 +87,7 @@ See L<EVP_PKEY-ML-DSA(7)> for information related to B<ML-DSA> keys. =head1 NOTES -For backwards compatability reasons EVP_DigestSignInit_ex(), EVP_DigestSign(), +For backwards compatibility reasons EVP_DigestSignInit_ex(), EVP_DigestSign(), EVP_DigestVerifyInit_ex() and EVP_DigestVerify() may also be used, but the digest passed in I<mdname> must be NULL. diff --git a/doc/man7/EVP_SIGNATURE-SLH-DSA.pod b/doc/man7/EVP_SIGNATURE-SLH-DSA.pod index de2be646ed64..c1699793ce3b 100644 --- a/doc/man7/EVP_SIGNATURE-SLH-DSA.pod +++ b/doc/man7/EVP_SIGNATURE-SLH-DSA.pod @@ -28,7 +28,7 @@ C<s> types have smaller signature sizes, and the C<f> 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. -L<EVP_SIGNATURE_fetch(3)> can be used to explicitely fetch one of the 12 +L<EVP_SIGNATURE_fetch(3)> can be used to explicitly fetch one of the 12 algorithms which can then be used with L<EVP_PKEY_sign_message_init(3)>, L<EVP_PKEY_sign(3)>, L<EVP_PKEY_verify_message_init(3)>, and L<EVP_PKEY_verify(3)> to perform one-shot message signing or verification. @@ -38,7 +38,7 @@ encodes the message internally as 0x00 || len(ctx) || ctx || message. where B<ctx> 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 chosing +may be done by the user by doing Pre hash encoding externally and then choosing the option to not encode the message. =head2 SLH-DSA Signature Parameters diff --git a/doc/man7/openssl-env.pod b/doc/man7/openssl-env.pod index 78043d5bd68a..218eb93632ca 100644 --- a/doc/man7/openssl-env.pod +++ b/doc/man7/openssl-env.pod @@ -61,7 +61,7 @@ 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. -The value of this environment varialble is a comma-separated list of names, +The value of this environment variable is a comma-separated list of names, with the following available: =over 4 @@ -173,7 +173,8 @@ 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 L<OPENSSL_ia32cap(3)>, L<OPENSSL_s390xcap(3)> and L<OPENSSL_riscvcap(3)>. +See L<OPENSSL_ia32cap(3)>, L<OPENSSL_ppccap(3)>, L<OPENSSL_riscvcap(3)>, +and L<OPENSSL_s390xcap(3)>. =item B<NO_PROXY>, B<HTTPS_PROXY>, B<HTTP_PROXY> diff --git a/doc/man7/openssl-quic-concurrency.pod b/doc/man7/openssl-quic-concurrency.pod index ded22a1e8b92..e79dd2a3a2c6 100644 --- a/doc/man7/openssl-quic-concurrency.pod +++ b/doc/man7/openssl-quic-concurrency.pod @@ -196,7 +196,7 @@ Specifying this flag configures the Single-Threaded Concurrency Model (SCM). =item B<SSL_DOMAIN_FLAG_MULTI_THREAD> -Speciyfing this flag configures the Contentive Concurrency Model (CCM) (unless +Specifying this flag configures the Contentive Concurrency Model (CCM) (unless B<SSL_DOMAIN_FLAG_THREAD_ASSISTED> is also specified). =item B<SSL_DOMAIN_FLAG_THREAD_ASSISTED> diff --git a/doc/man7/openssl-quic.pod b/doc/man7/openssl-quic.pod index 2379ce7fb994..0e9e78b97625 100644 --- a/doc/man7/openssl-quic.pod +++ b/doc/man7/openssl-quic.pod @@ -566,7 +566,7 @@ L<SSL_accept_connection(3)>. =item L<SSL_accept_connection(3)> -Accepts a new incoming connection for a listner SSL object. A new SSL object +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. @@ -895,6 +895,20 @@ that a call to L<SSL_handle_events(3)> is performed after the specified timeout =back +=head1 WINDOWS APPLICATION NOTES + +QUIC protocol uses UDP sockets. The recvfrom() function on Windows may fail +with C<WSAECONNRESET> 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 + +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 C<WSAIoctl()> calls fail. Robust application should set those +options itself so it can handle error notifications from C<WSAIoctl()> properly. + =head1 SEE ALSO L<SSL_handle_events(3)>, L<SSL_get_event_timeout(3)>, @@ -914,7 +928,7 @@ L<SSL_is_domain(3)>, L<SSL_get0_domain(3)> =head1 COPYRIGHT -Copyright 2022-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2022-2026 The OpenSSL Project Authors. All Rights Reserved. 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 diff --git a/doc/man7/ossl-guide-migration.pod b/doc/man7/ossl-guide-migration.pod index aa60c129baa4..0be64bed8496 100644 --- a/doc/man7/ossl-guide-migration.pod +++ b/doc/man7/ossl-guide-migration.pod @@ -183,9 +183,9 @@ For more information, see L<OpenSSL_version(3)>. =head3 Other major new features -=head4 Certificate Management Protocol (CMP, RFC 4210) +=head4 Certificate Management Protocol (CMP, RFC 9810) -This also covers CRMF (RFC 4211) and HTTP transfer (RFC 6712) +This also covers CRMF (RFC 4211) and HTTP transfer (RFC 9811) See L<openssl-cmp(1)> and L<OSSL_CMP_exec_certreq(3)> as starting points. =head4 HTTP(S) client diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod index 61202b523640..3ef927feb594 100644 --- a/doc/man7/provider-signature.pod +++ b/doc/man7/provider-signature.pod @@ -178,26 +178,87 @@ set of "signature" functions, i.e. at least one of: =item OSSL_FUNC_signature_sign_init and OSSL_FUNC_signature_sign +Used via L<EVP_PKEY_sign_init(3)> and L<EVP_PKEY_sign(3)>. +These functions operate on pre-digested data (the "to be signed" or TBS value). + =item OSSL_FUNC_signature_sign_message_init and OSSL_FUNC_signature_sign +Used via L<EVP_PKEY_sign_message_init(3)> and L<EVP_PKEY_sign(3)> when signing a complete message. +The implementation internally handles message digesting. + =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 L<EVP_PKEY_sign_message_init(3)>, +L<EVP_PKEY_sign_message_update(3)>, and L<EVP_PKEY_sign_message_final(3)>. + =item OSSL_FUNC_signature_verify_init and OSSL_FUNC_signature_verify +Used via L<EVP_PKEY_verify_init(3)> and L<EVP_PKEY_verify(3)>. +These functions operate on pre-digested data. + =item OSSL_FUNC_signature_verify_message_init and OSSL_FUNC_signature_verify +Used via L<EVP_PKEY_verify_message_init(3)> and L<EVP_PKEY_verify(3)> when verifying a complete message. +The implementation internally handles message digesting. + =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 L<EVP_PKEY_verify_message_init(3)>, +L<EVP_PKEY_verify_message_update(3)>, and L<EVP_PKEY_verify_message_final(3)>. + =item OSSL_FUNC_signature_verify_recover_init and OSSL_FUNC_signature_verify_recover +Used via L<EVP_PKEY_verify_recover_init(3)> and L<EVP_PKEY_verify_recover(3)>. +Applicable only to signature schemes that support signature recovery (such as RSA). + =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 L<EVP_DigestSignInit(3)>, +L<EVP_DigestSignUpdate(3)>, and L<EVP_DigestSignFinal(3)>. + =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 L<EVP_DigestVerifyInit(3)>, +L<EVP_DigestVerifyUpdate(3)>, and L<EVP_DigestVerifyFinal(3)>. + =item OSSL_FUNC_signature_digest_sign_init and OSSL_FUNC_signature_digest_sign +One-shot digest-sign variant, used via L<EVP_DigestSign(3)>. + =item OSSL_FUNC_signature_digest_verify_init and OSSL_FUNC_signature_digest_verify +One-shot digest-verify variant, used via L<EVP_DigestVerify(3)>. + +=back + +B<Important Note for TLS Support:> For a provider signature implementation to +be usable within F<libssl> for TLS connections, it B<must> 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 F<libssl> 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). + +The choice of which function set to implement depends on your use case: + +=over 4 + +=item * + +For general-purpose signature operations and TLS support: implement the +digest-sign and digest-verify functions. + +=item * + +For operations on pre-digested data only: implement the basic sign and verify +functions. + +=item * + +For signature schemes with recovery capability: additionally implement the +verify-recover functions. + =back The OSSL_FUNC_signature_set_ctx_params() and @@ -633,8 +694,17 @@ L<EVP_SIGNATURE_is_a(3)>, L<ASN1_item_sign_ctx(3)> =head1 HISTORY The provider SIGNATURE interface was introduced in OpenSSL 3.0. -The Signature Parameters "fips-indicator", "key-check" and "digest-check" -were added in OpenSSL 3.4. + +The OSSL_FUNC_signature_sign_message_init(), OSSL_FUNC_signature_sign_message_update(), +OSSL_FUNC_signature_sign_message_final(), OSSL_FUNC_signature_verify_message_init(), +OSSL_FUNC_signature_verify_message_update() and OSSL_FUNC_signature_verify_message_final() +functions were added in OpenSSL 3.4. + +The Signature Parameters "fips-indicator", "key-check" and "digest-check" were added in +OpenSSL 3.4. + +Deterministic digital signature generation for ECDSA was added to the FIPS provider in OpenSSL +3.6. =head1 COPYRIGHT |