From: Rich Salz Date: Fri, 8 Jul 2016 16:55:45 +0000 (-0400) Subject: Replace all #define's in pod pages. X-Git-Tag: OpenSSL_1_1_0-pre6~250 X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=91da5e7710ba9cd36c5aef0a8056d5a0eb8bf524 Replace all #define's in pod pages. Function-like macros are replaced with prototypes and a note that they are implemented as macros. Constants are just referenced in-line in the text. Tweak BIO_TYPE_... documentation. Also fix RT4592. Reviewed-by: Matt Caswell --- diff --git a/doc/crypto/ASYNC_start_job.pod b/doc/crypto/ASYNC_start_job.pod index eb12da8cb9..edec50b573 100644 --- a/doc/crypto/ASYNC_start_job.pod +++ b/doc/crypto/ASYNC_start_job.pod @@ -182,8 +182,6 @@ The following example demonstrates how to use most of the core async APIs: #include #include - #define WAIT_SIGNAL_CHAR 'X' - int unique = 0; void cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw) @@ -200,7 +198,7 @@ The following example demonstrates how to use most of the core async APIs: unsigned char *msg; int pipefds[2] = {0, 0}; OSSL_ASYNC_FD *wptr; - char buf = WAIT_SIGNAL_CHAR; + char buf = 'X'; currjob = ASYNC_get_current_job(); if (currjob != NULL) { diff --git a/doc/crypto/BIO_ctrl.pod b/doc/crypto/BIO_ctrl.pod index d6d0df1c5a..17dc6ed903 100644 --- a/doc/crypto/BIO_ctrl.pod +++ b/doc/crypto/BIO_ctrl.pod @@ -11,27 +11,27 @@ BIO_get_info_callback, BIO_set_info_callback - BIO control operations #include - long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg); - long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long)); - char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg); - long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg); + typedef void (*bio_info_cb)(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3); + + long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg); + long BIO_callback_ctrl(BIO *b, int cmd, bio_info_cb cb); + char *BIO_ptr_ctrl(BIO *bp, int cmd, long larg); + long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg); int BIO_reset(BIO *b); int BIO_seek(BIO *b, int ofs); int BIO_tell(BIO *b); int BIO_flush(BIO *b); int BIO_eof(BIO *b); - int BIO_set_close(BIO *b,long flag); + int BIO_set_close(BIO *b, long flag); int BIO_get_close(BIO *b); int BIO_pending(BIO *b); int BIO_wpending(BIO *b); size_t BIO_ctrl_pending(BIO *b); size_t BIO_ctrl_wpending(BIO *b); - int BIO_get_info_callback(BIO *b,bio_info_cb **cbp); - int BIO_set_info_callback(BIO *b,bio_info_cb *cb); - - typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3); + int BIO_get_info_callback(BIO *b, bio_info_cb **cbp); + int BIO_set_info_callback(BIO *b, bio_info_cb *cb); =head1 DESCRIPTION diff --git a/doc/crypto/BIO_f_buffer.pod b/doc/crypto/BIO_f_buffer.pod index 286a39c9ed..3224710942 100644 --- a/doc/crypto/BIO_f_buffer.pod +++ b/doc/crypto/BIO_f_buffer.pod @@ -7,19 +7,20 @@ BIO_set_read_buffer_size, BIO_set_write_buffer_size, BIO_set_buffer_size, BIO_set_buffer_read_data, -BIO_f_buffer - buffering BIO +BIO_f_buffer +- buffering BIO =head1 SYNOPSIS #include - const BIO_METHOD * BIO_f_buffer(void); + const BIO_METHOD *BIO_f_buffer(void); - #define BIO_get_buffer_num_lines(b) - #define BIO_set_read_buffer_size(b,size) - #define BIO_set_write_buffer_size(b,size) - #define BIO_set_buffer_size(b,size) - #define BIO_set_buffer_read_data(b,buf,num) + long BIO_get_buffer_num_lines(BIO *b); + long BIO_set_read_buffer_size(BIO *b, long size); + long BIO_set_write_buffer_size(BIO *b, long size); + long BIO_set_buffer_size(BIO *b, long size); + long BIO_set_buffer_read_data(BIO *b, void *buf, long num); =head1 DESCRIPTION @@ -46,6 +47,8 @@ is expanded. =head1 NOTES +These functions, other than BIO_f_buffer(), are implemented as macros. + Buffering BIOs implement BIO_gets() by using BIO_read() operations on the next BIO in the chain. By prepending a buffering BIO to a chain it is therefore possible to provide BIO_gets() functionality if the following BIOs do not diff --git a/doc/crypto/BIO_f_ssl.pod b/doc/crypto/BIO_f_ssl.pod index 4007130150..1890852179 100644 --- a/doc/crypto/BIO_f_ssl.pod +++ b/doc/crypto/BIO_f_ssl.pod @@ -18,23 +18,20 @@ BIO_ssl_shutdown - SSL BIO const BIO_METHOD *BIO_f_ssl(void); - #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl) - #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp) - #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL) - #define BIO_set_ssl_renegotiate_bytes(b,num) \ - BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL); - #define BIO_set_ssl_renegotiate_timeout(b,seconds) \ - BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL); - #define BIO_get_num_renegotiates(b) \ - BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL); - - BIO *BIO_new_ssl(SSL_CTX *ctx,int client); + long BIO_set_ssl(BIO *b,SSL *ssl, long c); + long BIO_get_ssl(BIO *b, SSL **sslp); + long BIO_set_ssl_mode(BIO *b, long client); + long BIO_set_ssl_renegotiate_bytes(BIO *b, long num); + long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds); + long BIO_get_num_renegotiates(BIO *b); + + BIO *BIO_new_ssl(SSL_CTX *ctx, int client); BIO *BIO_new_ssl_connect(SSL_CTX *ctx); BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx); - int BIO_ssl_copy_session_id(BIO *to,BIO *from); + int BIO_ssl_copy_session_id(BIO *to, BIO *from); void BIO_ssl_shutdown(BIO *bio); - #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL) + long BIO_do_handshake(BIO *b); =head1 DESCRIPTION @@ -128,6 +125,10 @@ Applications do not have to call BIO_do_handshake() but may wish to do so to separate the handshake process from other I/O processing. +BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), +BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(), +BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros. + =head1 EXAMPLE This SSL/TLS client example, attempts to retrieve a page from an diff --git a/doc/crypto/BIO_find_type.pod b/doc/crypto/BIO_find_type.pod index f03071ad9b..77fe5597fb 100644 --- a/doc/crypto/BIO_find_type.pod +++ b/doc/crypto/BIO_find_type.pod @@ -2,58 +2,29 @@ =head1 NAME -BIO_TYPE_NONE, BIO_TYPE_MEM, BIO_TYPE_FILE, BIO_TYPE_FD, BIO_TYPE_SOCKET, -BIO_TYPE_NULL, BIO_TYPE_SSL, BIO_TYPE_MD, BIO_TYPE_BUFFER, BIO_TYPE_CIPHER, -BIO_TYPE_BASE64, BIO_TYPE_CONNECT, BIO_TYPE_ACCEPT, BIO_TYPE_PROXY_CLIENT, -BIO_TYPE_PROXY_SERVER, BIO_TYPE_NBIO_TEST, BIO_TYPE_NULL_FILTER, -BIO_TYPE_BER, BIO_TYPE_BIO, BIO_TYPE_DESCRIPTOR, BIO_TYPE_FILTER, -BIO_TYPE_SOURCE_SINK, BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal =head1 SYNOPSIS #include - BIO * BIO_find_type(BIO *b,int bio_type); - BIO * BIO_next(BIO *b); - - #define BIO_method_type(b) ((b)->method->type) - - #define BIO_TYPE_NONE 0 - #define BIO_TYPE_MEM (1|0x0400) - #define BIO_TYPE_FILE (2|0x0400) - - #define BIO_TYPE_FD (4|0x0400|0x0100) - #define BIO_TYPE_SOCKET (5|0x0400|0x0100) - #define BIO_TYPE_NULL (6|0x0400) - #define BIO_TYPE_SSL (7|0x0200) - #define BIO_TYPE_MD (8|0x0200) - #define BIO_TYPE_BUFFER (9|0x0200) - #define BIO_TYPE_CIPHER (10|0x0200) - #define BIO_TYPE_BASE64 (11|0x0200) - #define BIO_TYPE_CONNECT (12|0x0400|0x0100) - #define BIO_TYPE_ACCEPT (13|0x0400|0x0100) - #define BIO_TYPE_PROXY_CLIENT (14|0x0200) - #define BIO_TYPE_PROXY_SERVER (15|0x0200) - #define BIO_TYPE_NBIO_TEST (16|0x0200) - #define BIO_TYPE_NULL_FILTER (17|0x0200) - #define BIO_TYPE_BER (18|0x0200) - #define BIO_TYPE_BIO (19|0x0400) - - #define BIO_TYPE_DESCRIPTOR 0x0100 - #define BIO_TYPE_FILTER 0x0200 - #define BIO_TYPE_SOURCE_SINK 0x0400 + BIO *BIO_find_type(BIO *b,int bio_type); + BIO *BIO_next(BIO *b); + int BIO_method_type(const BIO *b); =head1 DESCRIPTION The BIO_find_type() searches for a BIO of a given type in a chain, starting -at BIO B. If B is a specific type (such as BIO_TYPE_MEM) then a search +at BIO B. If B is a specific type (such as B) then a search is made for a BIO of that type. If B is a general type (such as B) then the next matching BIO of the given general type is searched for. BIO_find_type() returns the next matching BIO or NULL if none is found. -Note: not all the B types above have corresponding BIO implementations. +The following general types are defined: +B, B, and B. + +For a list of the defined types, see the B header file. BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs in a chain or used in conjunction with BIO_find_type() to find all BIOs of a diff --git a/doc/crypto/BIO_s_accept.pod b/doc/crypto/BIO_s_accept.pod index a9259ab217..724f1480df 100644 --- a/doc/crypto/BIO_s_accept.pod +++ b/doc/crypto/BIO_s_accept.pod @@ -2,7 +2,6 @@ =head1 NAME -BIO_BIND_NORMAL, BIO_BIND_REUSEADDR_IF_UNUSED, BIO_BIND_REUSEADDR, BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO @@ -24,10 +23,6 @@ BIO_get_bind_mode, BIO_do_accept - accept BIO long BIO_set_bind_mode(BIO *b, long mode); long BIO_get_bind_mode(BIO *b); - #define BIO_BIND_NORMAL 0 - #define BIO_BIND_REUSEADDR_IF_UNUSED 1 - #define BIO_BIND_REUSEADDR 2 - int BIO_do_accept(BIO *b); =head1 DESCRIPTION @@ -82,13 +77,13 @@ chain of BIOs must not be freed after this call, they will be automatically freed when the accept BIO is freed. BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve -the current bind mode. If BIO_BIND_NORMAL (the default) is set +the current bind mode. If B (the default) is set then another socket cannot be bound to the same port. If -BIO_BIND_REUSEADDR is set then other sockets can bind to the -same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and +B is set then other sockets can bind to the +same port. If B is set then and attempt is first made to use BIO_BIN_NORMAL, if this fails and the port is not in use then a second attempt is made -using BIO_BIND_REUSEADDR. +using B. BIO_do_accept() serves two functions. When it is first called, after the accept BIO has been setup, it will attempt diff --git a/doc/crypto/BIO_s_bio.pod b/doc/crypto/BIO_s_bio.pod index fb661979d8..cb46546e21 100644 --- a/doc/crypto/BIO_s_bio.pod +++ b/doc/crypto/BIO_s_bio.pod @@ -13,22 +13,20 @@ BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO const BIO_METHOD *BIO_s_bio(void); - #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2) - #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL) + int BIO_make_bio_pair(BIO *b1, BIO *b2); + int BIO_destroy_bio_pair(BIO *b); + int BIO_shutdown_wr(BIO *b); - #define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL) - #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL) - #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL) + int BIO_set_write_buf_size(BIO *b, long size); + size_t BIO_get_write_buf_size(BIO *b, long size); int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); - #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL) + int BIO_get_write_guarantee(BIO *b); size_t BIO_ctrl_get_write_guarantee(BIO *b); - - #define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL) + int BIO_get_read_request(BIO *b); size_t BIO_ctrl_get_read_request(BIO *b); - int BIO_ctrl_reset_read_request(BIO *b); =head1 DESCRIPTION @@ -123,6 +121,11 @@ never sent! BIO_eof() is true if no data is in the peer BIO and the peer BIO has been shutdown. +BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(), +BIO_set_write_buf_size(), BIO_get_write_buf_size(), +BIO_get_write_guarantee(), and BIO_get_read_request() are implemented +as macros. + =head1 RETURN VALUES BIO_new_bio_pair() returns 1 on success, with the new BIOs available in diff --git a/doc/crypto/BIO_s_fd.pod b/doc/crypto/BIO_s_fd.pod index 8002ad7754..aa7ba363ad 100644 --- a/doc/crypto/BIO_s_fd.pod +++ b/doc/crypto/BIO_s_fd.pod @@ -8,10 +8,10 @@ BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO #include - const BIO_METHOD * BIO_s_fd(void); + const BIO_METHOD *BIO_s_fd(void); - #define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd) - #define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c) + int BIO_set_fd(BIO *b, int fd, int c); + int BIO_get_fd(BIO *b, int *c); BIO *BIO_new_fd(int fd, int close_flag); @@ -27,19 +27,19 @@ If the close flag is set then close() is called on the underlying file descriptor when the BIO is freed. BIO_reset() attempts to change the file pointer to the start of file -using lseek(fd, 0, 0). +such as by using B. BIO_seek() sets the file pointer to position B from start of file -using lseek(fd, ofs, 0). +such as by using B. -BIO_tell() returns the current file position by calling lseek(fd, 0, 1). +BIO_tell() returns the current file position such as by calling +B. BIO_set_fd() sets the file descriptor of BIO B to B and the close flag to B. BIO_get_fd() places the file descriptor in B if it is not NULL, it also -returns the file descriptor. If B is not NULL it should be of type -(int *). +returns the file descriptor. BIO_new_fd() returns a file descriptor BIO using B and B. @@ -54,15 +54,12 @@ manual pages. File descriptor BIOs should not be used for socket I/O. Use socket BIOs instead. +BIO_set_fd() and BIO_get_fd() are implemented as macros. + =head1 RETURN VALUES BIO_s_fd() returns the file descriptor BIO method. -BIO_reset() returns zero for success and -1 if an error occurred. -BIO_seek() and BIO_tell() return the current file position or -1 -is an error occurred. These values reflect the underlying lseek() -behaviour. - BIO_set_fd() always returns 1. BIO_get_fd() returns the file descriptor or -1 if the BIO has not @@ -76,6 +73,7 @@ occurred. This is a file descriptor BIO version of "Hello World": BIO *out; + out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE); BIO_printf(out, "Hello World\n"); BIO_free(out); diff --git a/doc/crypto/BIO_set_callback.pod b/doc/crypto/BIO_set_callback.pod index 219a6dd3eb..42e4545d93 100644 --- a/doc/crypto/BIO_set_callback.pod +++ b/doc/crypto/BIO_set_callback.pod @@ -9,16 +9,17 @@ BIO_debug_callback - BIO callback functions #include - #define BIO_set_callback(b,cb) ((b)->callback=(cb)) - #define BIO_get_callback(b) ((b)->callback) - #define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg)) - #define BIO_get_callback_arg(b) ((b)->cb_arg) - long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi, - long argl,long ret); + typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi, + long argl, long ret); - typedef long (*callback)(BIO *b, int oper, const char *argp, - int argi, long argl, long retvalue); + void BIO_set_callback(BIO *b, BIO_callack_fn cb); + BIO_callack_fn BIO_get_callback(BIO *b); + void BIO_set_callback_arg(BIO *b, char *arg); + char *BIO_get_callback_arg(const BIO *b); + + long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi, + long argl, long ret); =head1 DESCRIPTION @@ -32,12 +33,13 @@ used to set and retrieve an argument for use in the callback. BIO_debug_callback() is a standard debugging callback which prints out information relating to each BIO operation. If the callback -argument is set if is interpreted as a BIO to send the information +argument is set it is interpreted as a BIO to send the information to, otherwise stderr is used. -callback() is the callback function itself. The meaning of each -argument is described below. +BIO_callback_fn() is the type of the callback function. The meaning of each +argument is described below: +=over The BIO the callback is attached to is passed in B. B is set to the operation being performed. For some operations @@ -47,19 +49,24 @@ operation, the latter case has B or'ed with BIO_CB_RETURN. The meaning of the arguments B, B and B depends on the value of B, that is the operation being performed. -B is the return value that would be returned to the +B is the return value that would be returned to the application if no callback were present. The actual value returned is the return value of the callback itself. In the case of callbacks -called before the actual BIO operation 1 is placed in retvalue, if +called before the actual BIO operation 1 is placed in B, if the return value is not positive it will be immediately returned to the application and the BIO operation will not be performed. -The callback should normally simply return B when it has -finished processing, unless if specifically wishes to modify the +=back + +The callback should normally simply return B when it has +finished processing, unless it specifically wishes to modify the value returned to the application. =head1 CALLBACK OPERATIONS +In the notes below, B defers to the actual callback +function that is called. + =over 4 =item B diff --git a/doc/crypto/BIO_should_retry.pod b/doc/crypto/BIO_should_retry.pod index 2a6485af9a..d6ddf48e2c 100644 --- a/doc/crypto/BIO_should_retry.pod +++ b/doc/crypto/BIO_should_retry.pod @@ -2,8 +2,6 @@ =head1 NAME -BIO_FLAGS_READ, BIO_FLAGS_WRITE, BIO_FLAGS_IO_SPECIAL, BIO_FLAGS_RWS, -BIO_FLAGS_SHOULD_RETRY, BIO_should_read, BIO_should_write, BIO_should_io_special, BIO_retry_type, BIO_should_retry, BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry @@ -13,17 +11,11 @@ functions #include - #define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ) - #define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE) - #define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL) - #define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS) - #define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY) - - #define BIO_FLAGS_READ 0x01 - #define BIO_FLAGS_WRITE 0x02 - #define BIO_FLAGS_IO_SPECIAL 0x04 - #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL) - #define BIO_FLAGS_SHOULD_RETRY 0x08 + int BIO_should_read(BIO *b); + int BIO_should_write(BIO *b); + int BIO_should_io_special(iBIO *b); + int BIO_retry_type(BIO *b); + int BIO_should_retry(BIO *b); BIO *BIO_get_retry_BIO(BIO *bio, int *reason); int BIO_get_retry_reason(BIO *bio); @@ -68,6 +60,9 @@ BIO. This would usually only be called by BIO implementations. =head1 NOTES +BIO_should_read(), BIO_should_write(), BIO_should_io_special(), +BIO_retry_type(), and BIO_should_retry(), are implemented as macros. + If BIO_should_retry() returns false then the precise "error condition" depends on the BIO type that caused it and the return code of the BIO operation. For example if a call to BIO_read() on a socket BIO returns diff --git a/doc/crypto/BN_new.pod b/doc/crypto/BN_new.pod index ab7c4e5ae4..0277614276 100644 --- a/doc/crypto/BN_new.pod +++ b/doc/crypto/BN_new.pod @@ -2,7 +2,7 @@ =head1 NAME -BN_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs +BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs =head1 SYNOPSIS @@ -10,6 +10,8 @@ BN_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs BIGNUM *BN_new(void); + BIGNUM *BN_secure_new(void); + void BN_clear(BIGNUM *a); void BN_free(BIGNUM *a); @@ -19,6 +21,8 @@ BN_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs =head1 DESCRIPTION BN_new() allocates and initializes a B structure. +BN_secure_new() does the same except that the secure heap +OPENSSL_secure_malloc(3) is used to store the value. BN_clear() is used to destroy sensitive data such as keys when they are no longer needed. It erases the memory used by B and sets it @@ -31,8 +35,9 @@ If B is NULL, nothing is done. =head1 RETURN VALUES -BN_new() returns a pointer to the B. If the allocation fails, -it returns B and sets an error code that can be obtained +BN_new() and BN_secure_new() +return a pointer to the B. If the allocation fails, +they return B and set an error code that can be obtained by L. BN_clear(), BN_free() and BN_clear_free() have no return values. diff --git a/doc/crypto/BUF_MEM_new.pod b/doc/crypto/BUF_MEM_new.pod index 1a975776aa..eb85bed896 100644 --- a/doc/crypto/BUF_MEM_new.pod +++ b/doc/crypto/BUF_MEM_new.pod @@ -2,7 +2,6 @@ =head1 NAME -BUF_MEM_FLAG_SECURE, BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow BUF_MEM_grow_clean, BUF_reverse - simple character array structure @@ -15,8 +14,6 @@ standard C library equivalents BUF_MEM *BUF_MEM_new(void); - #define BUF_MEM_FLAG_SECURE - BUF_MEM *BUF_MEM_new_ex(unsigned long flags); void BUF_MEM_free(BUF_MEM *a); diff --git a/doc/crypto/DEFINE_STACK_OF.pod b/doc/crypto/DEFINE_STACK_OF.pod index 94e483feff..5acc3e306e 100644 --- a/doc/crypto/DEFINE_STACK_OF.pod +++ b/doc/crypto/DEFINE_STACK_OF.pod @@ -3,6 +3,7 @@ =head1 NAME DEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF, +DEFINE_SPECIAL_STACK_OF_CONST, OPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr, OPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_free, OPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new, OPENSSL_sk_new_null, @@ -22,10 +23,11 @@ stack container #include - #define STACK_OF(TYPE) - #define DEFINE_STACK_OF - #define DEFINE_STACK_OF_CONST - #define DEFINE_SPECIAL_STACK_OF + STACK_OF(TYPE) + DEFINE_STACK_OF(TYPE) + DEFINE_STACK_OF_CONST(TYPE) + DEFINE_SPECIAL_STACK_OF(FUNCTYPE, TYPE) + DEFINE_SPECIAL_STACK_OF_CONST(FUNCTYPE, TYPE) typedef int (*sk_TYPE_compfunc)(const TYPE *const *a, const TYPE *const *b); typedef TYPE * (*sk_TYPE_copyfunc)(const TYPE *a); @@ -64,22 +66,28 @@ functions that wrap around the utility B API. In the description here, I is used as a placeholder for any of the OpenSSL datatypes, such as I. -DEFINE_STACK_OF(TYPE) creates set of functions for a stack of B. This +STACK_OF() returns the name for a stack of the specified B. +DEFINE_STACK_OF() creates set of functions for a stack of B. This will mean that type B is stored in each stack, the type is referenced by STACK_OF(TYPE) and each function name begins with I. For example: TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx); -DEFINE_STACK_OF_CONST(TYPE) is identical to DEFINE_STACK_OF(TYPE) except +DEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except each element is constant. For example: const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx); -DEFINE_SPECIAL_STACK_OF(FUNCNAME, TYPE) defines a stack of B but +DEFINE_SPECIAL_STACK_OF() defines a stack of B but each function uses B in the function name. For example: TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx); +DEFINE_SPECIAL_STACK_OF_CONST() is similar except that each element is +constant: + + const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx); + sk_TYPE_num() returns the number of elements in B or -1 if B is B. @@ -170,6 +178,9 @@ sk_TYPE_find() and sk_TYPE_find_ex(). They return an index to the matching element. In particular B<0> indicates a matching first element. A failed search is indicated by a B<-1> return value. +STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and +DEFINE_SPECIAL_STACK_OF() are implemented as macros. + =head1 RETURN VALUES sk_TYPE_num() returns the number of elements in the stack or B<-1> if the diff --git a/doc/crypto/ENGINE_add.pod b/doc/crypto/ENGINE_add.pod index 4e082bc7ef..da86532ad9 100644 --- a/doc/crypto/ENGINE_add.pod +++ b/doc/crypto/ENGINE_add.pod @@ -13,7 +13,7 @@ ENGINE_get_destroy_function, ENGINE_get_finish_function, ENGINE_get_init_function, ENGINE_get_load_privkey_function, ENGINE_get_load_pubkey_function, ENGINE_load_private_key, ENGINE_load_public_key, ENGINE_get_RAND, ENGINE_get_RSA, ENGINE_get_id, -ENGINE_get_name, ENGINE_get_cmd_defns, EVP_CIPHER ENGINE_get_cipher, +ENGINE_get_name, ENGINE_get_cmd_defns, ENGINE_get_cipher, ENGINE_get_digest, ENGINE_add, ENGINE_cmd_is_executable, ENGINE_ctrl, ENGINE_ctrl_cmd, ENGINE_ctrl_cmd_string, ENGINE_finish, ENGINE_free, ENGINE_get_flags, ENGINE_init, @@ -525,17 +525,17 @@ this symbol is considered a "generic" command is handled directly by the OpenSSL core routines. It is using these "core" control commands that one can discover the control -commands implemented by a given ENGINE, specifically the commands; - - #define ENGINE_HAS_CTRL_FUNCTION 10 - #define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11 - #define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12 - #define ENGINE_CTRL_GET_CMD_FROM_NAME 13 - #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14 - #define ENGINE_CTRL_GET_NAME_FROM_CMD 15 - #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16 - #define ENGINE_CTRL_GET_DESC_FROM_CMD 17 - #define ENGINE_CTRL_GET_CMD_FLAGS 18 +commands implemented by a given ENGINE, specifically the commands: + + ENGINE_HAS_CTRL_FUNCTION + ENGINE_CTRL_GET_FIRST_CMD_TYPE + ENGINE_CTRL_GET_NEXT_CMD_TYPE + ENGINE_CTRL_GET_CMD_FROM_NAME + ENGINE_CTRL_GET_NAME_LEN_FROM_CMD + ENGINE_CTRL_GET_NAME_FROM_CMD + ENGINE_CTRL_GET_DESC_LEN_FROM_CMD + ENGINE_CTRL_GET_DESC_FROM_CMD + ENGINE_CTRL_GET_CMD_FLAGS Whilst these commands are automatically processed by the OpenSSL framework code, they use various properties exposed by each ENGINE to process these @@ -569,12 +569,12 @@ return properties of the corresponding commands. All except ENGINE_CTRL_GET_FLAGS return the string length of a command name or description, or populate a supplied character buffer with a copy of the command name or description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following -possible values; +possible values: - #define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001 - #define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002 - #define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004 - #define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008 + ENGINE_CMD_FLAG_NUMERIC + ENGINE_CMD_FLAG_STRING + ENGINE_CMD_FLAG_NO_INPUT + ENGINE_CMD_FLAG_INTERNAL If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely informational to the caller - this flag will prevent the command being usable diff --git a/doc/crypto/ERR_put_error.pod b/doc/crypto/ERR_put_error.pod index 1ec3575f0d..9d2405e3d3 100644 --- a/doc/crypto/ERR_put_error.pod +++ b/doc/crypto/ERR_put_error.pod @@ -49,10 +49,6 @@ the capitalized form such as "SSL3_READ_BYTES" in the above example. The trailing section of a reason code (after the "_R_") is translated into lower case and underscores changed to spaces. -When you are using new function or reason codes, run B. -The necessary B<#define>s will then automatically be added to the -sub-library's header file. - Although a library will normally report errors using its own specific XXXerr macro, another library's macro can be used. This is normally only done when a library wants to include ASN1 code which must use diff --git a/doc/crypto/EVP_DigestInit.pod b/doc/crypto/EVP_DigestInit.pod index 405810ee24..d879ba1cd3 100644 --- a/doc/crypto/EVP_DigestInit.pod +++ b/doc/crypto/EVP_DigestInit.pod @@ -3,7 +3,7 @@ =head1 NAME EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy_ex, -EVP_DigestInit_ex, EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_MAX_MD_SIZE, +EVP_DigestInit_ex, EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_DigestInit, EVP_DigestFinal, EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5, EVP_sha1, @@ -32,8 +32,6 @@ EVP_get_digestbynid, EVP_get_digestbyobj - EVP digest routines int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); - #define EVP_MAX_MD_SIZE 64 /* SHA512 */ - int EVP_MD_type(const EVP_MD *md); int EVP_MD_pkey_type(const EVP_MD *md); int EVP_MD_size(const EVP_MD *md); diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod index 093618de9c..bffe72b73a 100644 --- a/doc/crypto/EVP_EncryptInit.pod +++ b/doc/crypto/EVP_EncryptInit.pod @@ -82,15 +82,16 @@ EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr); const EVP_CIPHER *EVP_get_cipherbyname(const char *name); - #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a)) - #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a)) - - #define EVP_CIPHER_nid(e) ((e)->nid) - #define EVP_CIPHER_block_size(e) ((e)->block_size) - #define EVP_CIPHER_key_length(e) ((e)->key_len) - #define EVP_CIPHER_iv_length(e) ((e)->iv_len) - #define EVP_CIPHER_flags(e) ((e)->flags) - #define EVP_CIPHER_mode(e) ((e)->flags) & EVP_CIPH_MODE) + const EVP_CIPHER *EVP_get_cipherbynid(int nid); + const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a); + + int EVP_CIPHER_nid(const EVP_CIPHER *e); + int EVP_CIPHER_block_size(const EVP_CIPHER *e); + int EVP_CIPHER_key_length(const EVP_CIPHER *e) + int EVP_CIPHER_key_length(const EVP_CIPHER *e); + int EVP_CIPHER_iv_length(const EVP_CIPHER *e); + unsigned long EVP_CIPHER_flags(const EVP_CIPHER *e); + unsigned long EVP_CIPHER_mode(const EVP_CIPHER *e); int EVP_CIPHER_type(const EVP_CIPHER *ctx); const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx); @@ -475,8 +476,6 @@ Sets the CCM nonce (IV) length: this call can only be made before specifying an nonce value. The nonce length is given by B<15 - L> so it is 7 by default for AES. - - =head1 NOTES Where possible the B interface to symmetric ciphers should be used in @@ -509,6 +508,8 @@ EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an existing context without allocating and freeing it up on each call. +EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros. + =head1 BUGS For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is diff --git a/doc/crypto/EVP_PKEY_HKDF.pod b/doc/crypto/EVP_PKEY_CTX_set_hkdf_md.pod similarity index 100% rename from doc/crypto/EVP_PKEY_HKDF.pod rename to doc/crypto/EVP_PKEY_CTX_set_hkdf_md.pod diff --git a/doc/crypto/EVP_PKEY_TLS1_PRF.pod b/doc/crypto/EVP_PKEY_CTX_set_tls1_prf_md similarity index 96% rename from doc/crypto/EVP_PKEY_TLS1_PRF.pod rename to doc/crypto/EVP_PKEY_CTX_set_tls1_prf_md index 5c8dd9ddaa..0d57f9fb6a 100644 --- a/doc/crypto/EVP_PKEY_TLS1_PRF.pod +++ b/doc/crypto/EVP_PKEY_CTX_set_tls1_prf_md @@ -2,7 +2,7 @@ =head1 NAME -EVP_PKEY_TLS1_PRF, EVP_PKEY_CTX_set_tls1_prf_md, +EVP_PKEY_CTX_set_tls1_prf_md, EVP_PKEY_CTX_set1_tls1_prf_secret, EVP_PKEY_CTX_add1_tls1_prf_seed - TLS PRF key derivation algorithm @@ -18,7 +18,7 @@ TLS PRF key derivation algorithm =head1 DESCRIPTION -The EVP_PKEY_TLS1_PRF algorithm implements the PRF key derivation function for +The B algorithm implements the PRF key derivation function for TLS. It has no associated private key and only implements key derivation using EVP_PKEY_derive(). diff --git a/doc/crypto/OPENSSL_LH_COMPFUNC.pod b/doc/crypto/OPENSSL_LH_COMPFUNC.pod index 372f0d952c..e760ae3be7 100644 --- a/doc/crypto/OPENSSL_LH_COMPFUNC.pod +++ b/doc/crypto/OPENSSL_LH_COMPFUNC.pod @@ -5,6 +5,7 @@ DECLARE_LHASH_OF, OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DOALL_FUNC, LHASH_DOALL_ARG_FN_TYPE, +IMPLEMENT_LHASH_HASH_FN, IMPLEMENT_LHASH_COMP_FN, lh_TYPE_new, lh_TYPE_free, lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve, lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table @@ -43,75 +44,52 @@ and value fields. In the description here, I is used a placeholder for any of the OpenSSL datatypes, such as I. lh_TYPE_new() creates a new B structure to store -arbitrary data entries, and provides the 'hash' and 'compare' +arbitrary data entries, and specifies the 'hash' and 'compare' callbacks to be used in organising the table's entries. The B callback takes a pointer to a table entry as its argument and returns an unsigned long hash value for its key field. The hash value is normally truncated to a power of 2, so make sure that your hash function returns well mixed low order bits. The B callback takes two arguments (pointers to two hash table entries), and returns -0 if their keys are equal, non-zero otherwise. If your hash table +0 if their keys are equal, non-zero otherwise. + +If your hash table will contain items of some particular type and the B and B callbacks hash/compare these types, then the -B and B macros can be +B and B macros can be used to create callback wrappers of the prototypes required by -lh_TYPE_new(). These provide per-variable casts before calling the -type-specific callbacks written by the application author. These -macros, as well as those used for the "doall" callbacks, are defined -as; - - #define DECLARE_LHASH_HASH_FN(name, o_type) \ - unsigned long name##_LHASH_HASH(const void *); - #define IMPLEMENT_LHASH_HASH_FN(name, o_type) \ - unsigned long name##_LHASH_HASH(const void *arg) { \ - const o_type *a = arg; \ - return name##_hash(a); } - #define LHASH_HASH_FN(name) name##_LHASH_HASH - - #define DECLARE_LHASH_COMP_FN(name, o_type) \ - int name##_LHASH_COMP(const void *, const void *); - #define IMPLEMENT_LHASH_COMP_FN(name, o_type) \ - int name##_LHASH_COMP(const void *arg1, const void *arg2) { \ - const o_type *a = arg1; \ - const o_type *b = arg2; \ - return name##_cmp(a,b); } - #define LHASH_COMP_FN(name) name##_LHASH_COMP - - #define DECLARE_LHASH_DOALL_FN(name, o_type) \ - void name##_LHASH_DOALL(void *); - #define IMPLEMENT_LHASH_DOALL_FN(name, o_type) \ - void name##_LHASH_DOALL(void *arg) { \ - o_type *a = arg; \ - name##_doall(a); } - #define LHASH_DOALL_FN(name) name##_LHASH_DOALL - - #define DECLARE_LHASH_DOALL_ARG_FN(name, o_type, a_type) \ - void name##_LHASH_DOALL_ARG(void *, void *); - #define IMPLEMENT_LHASH_DOALL_ARG_FN(name, o_type, a_type) \ - void name##_LHASH_DOALL_ARG(void *arg1, void *arg2) { \ - o_type *a = arg1; \ - a_type *b = arg2; \ - name##_doall_arg(a, b); } - #define LHASH_DOALL_ARG_FN(name) name##_LHASH_DOALL_ARG - - An example of a hash table storing (pointers to) structures of type 'STUFF' - could be defined as follows; - - /* Calculates the hash value of 'tohash' (implemented elsewhere) */ - unsigned long STUFF_hash(const STUFF *tohash); - /* Orders 'arg1' and 'arg2' (implemented elsewhere) */ - int stuff_cmp(const STUFF *arg1, const STUFF *arg2); - /* Create the type-safe wrapper functions for use in the LHASH internals */ - static IMPLEMENT_LHASH_HASH_FN(stuff, STUFF); - static IMPLEMENT_LHASH_COMP_FN(stuff, STUFF); - /* ... */ - int main(int argc, char *argv[]) { - /* Create the new hash table using the hash/compare wrappers */ - LHASH_OF(STUFF) *hashtable = lh_STUFF_new(LHASH_HASH_FN(STUFF_hash), - LHASH_COMP_FN(STUFF_cmp)); - /* ... */ +lh_TYPE_new() as shown in this example: + + /* + * Implement the hash and compare functions; "stuff" can be any word. + */ + static unsigned long stuff_hash(const TYPE *a) + { + ... + } + static int stuff_cmp(const TYPE *a, const TYPE *b) + { + ... } + /* + * Implement the wrapper functions. + */ + static IMPLEMENT_LHASH_HASH_FN(stuff, TYPE) + static IMPLEMENT_LHASH_COMP_FN(stuff, TYPE) + +If the type is going to be used in several places, the following macros +can be used in a common header file to declare the function wrappers: + + DECLARE_LHASH_HASH_FN(stuff, TYPE) + DECLARE_LHASH_COMP_FN(stuff, TYPE) + +Then a hash table of TYPE objects can be created using this: + + LHASH_OF(TYPE) *htable; + + htable = lh_TYPE_new(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff)); + lh_TYPE_free() frees the B structure B. Allocated hash table entries will not be freed; consider using lh_TYPE_doall() to deallocate any remaining entries in the @@ -129,24 +107,20 @@ is a structure with the key field(s) set; the function will return a pointer to a fully populated structure. lh_TYPE_doall() will, for every entry in the hash table, call -B with the data item as its parameter. For lh_TYPE_doall() -and lh_TYPE_doall_arg(), function pointer casting should be avoided -in the callbacks (see B) - instead use the declare/implement -macros to create type-checked wrappers that cast variables prior to -calling your type-specific callbacks. An example of this is -illustrated here where the callback is used to cleanup resources for -items in the hash table prior to the hashtable itself being -deallocated: +B with the data item as its parameter. +For example: /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */ - void STUFF_cleanup_doall(STUFF *a); - /* Implement a prototype-compatible wrapper for "STUFF_cleanup" */ - IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF) - /* ... then later in the code ... */ - /* So to run "STUFF_cleanup" against all items in a hash table ... */ - lh_STUFF_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup)); + void TYPE_cleanup_doall(TYPE *a); + + /* Implement a prototype-compatible wrapper for "TYPE_cleanup" */ + IMPLEMENT_LHASH_DOALL_FN(TYPE_cleanup, TYPE) + + /* Call "TYPE_cleanup" against all items in a hash table. */ + lh_TYPE_doall(hashtable, LHASH_DOALL_FN(TYPE_cleanup)); + /* Then the hash table itself can be deallocated */ - lh_STUFF_free(hashtable); + lh_TYPE_free(hashtable); When doing this, be careful if you delete entries from the hash table in your callbacks: the table may decrease in size, moving the item @@ -169,13 +143,14 @@ this is demonstrated here (printing all hash table entries to a BIO that is provided by the caller): /* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */ - void STUFF_print_doall_arg(const STUFF *a, BIO *output_bio); - /* Implement a prototype-compatible wrapper for "STUFF_print" */ - static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF, const STUFF, BIO) - /* ... then later in the code ... */ + void TYPE_print_doall_arg(const TYPE *a, BIO *output_bio); + + /* Implement a prototype-compatible wrapper for "TYPE_print" */ + static IMPLEMENT_LHASH_DOALL_ARG_FN(TYPE, const TYPE, BIO) + /* Print out the entire hashtable to a particular BIO */ - lh_STUFF_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), BIO, - logging_bio); + lh_TYPE_doall_arg(hashtable, LHASH_DOALL_ARG_FN(TYPE_print), BIO, + logging_bio); lh_TYPE_error() can be used to determine if an error occurred in the last @@ -226,7 +201,7 @@ elsewhere in their code) - in this case the LHASH prototypes are appropriate as-is. Conversely, if the caller is responsible for the life-time of the data in question, then they may well wish to make modifications to table item passed back in the lh_doall() or -lh_doall_arg() callbacks (see the "STUFF_cleanup" example above). If +lh_doall_arg() callbacks (see the "TYPE_cleanup" example above). If so, the caller can either cast the "const" away (if they're providing the raw callbacks themselves) or use the macros to declare/implement the wrapper functions without "const" types. diff --git a/doc/crypto/OPENSSL_ia32cap.pod b/doc/crypto/OPENSSL_ia32cap.pod index 7b8629def0..7ea70c0fae 100644 --- a/doc/crypto/OPENSSL_ia32cap.pod +++ b/doc/crypto/OPENSSL_ia32cap.pod @@ -126,6 +126,8 @@ requirements are summarized in below table: AVX2 | 2.22 | 2.10 | 3.1 AVX512 | 2.25 | 2.11.8 | 3.6 +B is a macro returning the first word of the vector. + =head1 COPYRIGHT Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/crypto/OPENSSL_malloc.pod b/doc/crypto/OPENSSL_malloc.pod index 9760135ee9..574db8a5f3 100644 --- a/doc/crypto/OPENSSL_malloc.pod +++ b/doc/crypto/OPENSSL_malloc.pod @@ -2,8 +2,6 @@ =head1 NAME -CRYPTO_MEM_CHECK_OFF, CRYPTO_MEM_CHECK_ON, -CRYPTO_MEM_CHECK_DISABLE, CRYPTO_MEM_CHECK_ENABLE, OPENSSL_malloc_init, OPENSSL_malloc, OPENSSL_zalloc, OPENSSL_realloc, OPENSSL_free, OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse, @@ -62,11 +60,6 @@ CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions int CRYPTO_set_mem_debug(int onoff) - #define CRYPTO_MEM_CHECK_OFF - #define CRYPTO_MEM_CHECK_ON - #define CRYPTO_MEM_CHECK_DISABLE - #define CRYPTO_MEM_CHECK_ENABLE - int CRYPTO_mem_ctrl(int mode); int OPENSSL_mem_debug_push(const char *info) @@ -150,9 +143,6 @@ To enable tracking call CRYPTO_mem_ctrl() with a B argument of the B. To disable tracking call CRYPTO_mem_ctrl() with a B argument of the B. -The B and B modes -are used internally within OpenSSL to temporarily suspend and resume -tracking. While checking memory, it can be useful to store additional context about what is being done. diff --git a/doc/crypto/PEM_read.pod b/doc/crypto/PEM_read.pod index 167693dec1..66cbc7d243 100644 --- a/doc/crypto/PEM_read.pod +++ b/doc/crypto/PEM_read.pod @@ -3,8 +3,7 @@ =head1 NAME PEM_write, PEM_write_bio, -PEM_read, PEM_read_bio, PEM_do_header, PEM_get_EVP_CIPHER_INFO, -pem_password_cb +PEM_read, PEM_read_bio, PEM_do_header, PEM_get_EVP_CIPHER_INFO - PEM encoding routines =head1 SYNOPSIS @@ -25,8 +24,6 @@ pem_password_cb int PEM_do_header(EVP_CIPHER_INFO *cinfo, unsigned char *data, long *len, pem_password_cb *cb, void *u); - typedef int (*pem_password_cb)(char *buf, int size, int rwflag, void *u); - =head1 DESCRIPTION These functions read and write PEM-encoded objects, using the PEM diff --git a/doc/crypto/PEM_read_CMS.pod b/doc/crypto/PEM_read_CMS.pod index 5a799f9e89..649c8089a9 100644 --- a/doc/crypto/PEM_read_CMS.pod +++ b/doc/crypto/PEM_read_CMS.pod @@ -2,6 +2,7 @@ =head1 NAME +DECLARE_PEM_rw, PEM_read_CMS, PEM_read_bio_CMS, PEM_write_CMS, @@ -43,7 +44,7 @@ PEM_write_bio_SSL_SESSION #include - #define DECLARE_PEM_rw(name, TYPE) ... + DECLARE_PEM_rw(name, TYPE) TYPE *PEM_read_TYPE(FILE *fp, TYPE **a, pem_password_cb *cb, void *u); TYPE *PEM_read_bio_TYPE(BIO *bp, TYPE **a, pem_password_cb *cb, void *u); @@ -54,6 +55,8 @@ PEM_write_bio_SSL_SESSION In the description below, I is used as a placeholder for any of the OpenSSL datatypes, such as I. +The macro B expands to the set of declarations shown in +the next four lines of the synopsis. These routines convert between local instances of ASN1 datatypes and the PEM encoding. For more information on the templates, see diff --git a/doc/crypto/PEM_read_bio_PrivateKey.pod b/doc/crypto/PEM_read_bio_PrivateKey.pod index dd5a230998..fbfe975be0 100644 --- a/doc/crypto/PEM_read_bio_PrivateKey.pod +++ b/doc/crypto/PEM_read_bio_PrivateKey.pod @@ -2,6 +2,7 @@ =head1 NAME +pem_password_cb, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, PEM_write_bio_PrivateKey_traditional, PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, @@ -29,6 +30,8 @@ PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines #include + typedef int (*pem_password_cb)(char *buf, int size, int rwflag, void *u); + EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, void *u); EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, diff --git a/doc/crypto/PKCS7_verify.pod b/doc/crypto/PKCS7_verify.pod index 6cf80df333..c34808eced 100644 --- a/doc/crypto/PKCS7_verify.pod +++ b/doc/crypto/PKCS7_verify.pod @@ -2,15 +2,12 @@ =head1 NAME -PKCS7_NO_DUAL_CONTENT, PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure =head1 SYNOPSIS #include - #define PKCS7_NO_DUAL_CONTENT - int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, int flags); STACK_OF(X509) *PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags); diff --git a/doc/crypto/UI_new.pod b/doc/crypto/UI_new.pod index 72a2ea7095..9abb697807 100644 --- a/doc/crypto/UI_new.pod +++ b/doc/crypto/UI_new.pod @@ -2,10 +2,7 @@ =head1 NAME -UI, UI_METHOD, UI_INPUT_FLAG_ECHO, -UI_INPUT_FLAG_DEFAULT_PWD, -UI_CTRL_PRINT_ERRORS, -UI_CTRL_IS_REDOABLE, +UI, UI_METHOD, UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string, UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean, UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string, @@ -44,10 +41,6 @@ UI_set_method, UI_OpenSSL, - user interface int UI_add_error_string(UI *ui, const char *text); int UI_dup_error_string(UI *ui, const char *text); - /* These are the possible flags. They can be or'ed together. */ - #define UI_INPUT_FLAG_ECHO 0x01 - #define UI_INPUT_FLAG_DEFAULT_PWD 0x02 - char *UI_construct_prompt(UI *ui_method, const char *object_desc, const char *object_name); @@ -59,8 +52,6 @@ UI_set_method, UI_OpenSSL, - user interface int UI_process(UI *ui); int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)()); - #define UI_CTRL_PRINT_ERRORS 1 - #define UI_CTRL_IS_REDOABLE 2 void UI_set_default_method(const UI_METHOD *meth); const UI_METHOD *UI_get_default_method(void); @@ -134,10 +125,10 @@ The difference between the two is only conceptual. With the builtin method, there's no technical difference between them. Other methods may make a difference between them, however. -The flags currently supported are UI_INPUT_FLAG_ECHO, which is relevant for +The flags currently supported are B, which is relevant for UI_add_input_string() and will have the users response be echoed (when prompting for a password, this flag should obviously not be used, and -UI_INPUT_FLAG_DEFAULT_PWD, which means that a default password of some +B, which means that a default password of some sort will be used (completely depending on the application and the UI method). @@ -170,9 +161,9 @@ UI_process() goes through the information given so far, does all the printing and prompting and returns. UI_ctrl() adds extra control for the application author. For now, it -understands two commands: UI_CTRL_PRINT_ERRORS, which makes UI_process() +understands two commands: B, which makes UI_process() print the OpenSSL error stack as part of processing the UI, and -UI_CTRL_IS_REDOABLE, which returns a flag saying if the used UI can +B, which returns a flag saying if the used UI can be used again or not. UI_set_default_method() changes the default UI method to the one given. diff --git a/doc/crypto/X509_dup.pod b/doc/crypto/X509_dup.pod index b93c228738..03a81f0731 100644 --- a/doc/crypto/X509_dup.pod +++ b/doc/crypto/X509_dup.pod @@ -239,8 +239,8 @@ X509_dup, #include - #define DECLARE_ASN1_FUNCTIONS(type) ... - #define IMPLEMENT_ASN1_FUNCTIONS(stname) ... + DECLARE_ASN1_FUNCTIONS(type) + IMPLEMENT_ASN1_FUNCTIONS(stname) typedef struct ASN1_ITEM_st ASN1_ITEM; @@ -250,7 +250,6 @@ X509_dup, void TYPE_free(TYPE *a); int TYPE_print_ctx(BIO *out, TYPE *a, int indent, const ASN1_PCTX *pctx); - =head1 DESCRIPTION In the description below, I is used diff --git a/doc/crypto/bio.pod b/doc/crypto/bio.pod index 5a305c6a29..1e1dd02106 100644 --- a/doc/crypto/bio.pod +++ b/doc/crypto/bio.pod @@ -6,6 +6,8 @@ bio - Basic I/O abstraction +=for comment generic + =head1 SYNOPSIS #include diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod index c199b317a7..29387d343f 100644 --- a/doc/ssl/SSL_CTX_new.pod +++ b/doc/ssl/SSL_CTX_new.pod @@ -24,9 +24,9 @@ functions const SSL_METHOD *TLS_server_method(void); const SSL_METHOD *TLS_client_method(void); - #define SSLv23_method TLS_method - #define SSLv23_server_method TLS_server_method - #define SSLv23_client_method TLS_client_method + const SSL_METHOD *SSLv23_method(void); + const SSL_METHOD *SSLv23_server_method(void); + const SSL_METHOD *SSLv23_client_method(void); #ifndef OPENSSL_NO_SSL3_METHOD const SSL_METHOD *SSLv3_method(void); diff --git a/doc/ssl/SSL_CTX_set_default_passwd_cb.pod b/doc/ssl/SSL_CTX_set_default_passwd_cb.pod index fb448073f9..2196906141 100644 --- a/doc/ssl/SSL_CTX_set_default_passwd_cb.pod +++ b/doc/ssl/SSL_CTX_set_default_passwd_cb.pod @@ -2,7 +2,6 @@ =head1 NAME -SSL_CTX_passwd_cb, SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata, SSL_CTX_get_default_passwd_cb, SSL_CTX_get_default_passwd_cb_userdata, SSL_set_default_passwd_cb, SSL_set_default_passwd_cb_userdata, @@ -13,18 +12,16 @@ get passwd callback for encrypted PEM file handling #include - void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, SSL_CTX_passwd_cb *cb); + void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb); void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u); - SSL_CTX_passwd_cb *SSL_CTX_get_default_passwd_cb(SSL_CTX *ctx); + pem_password_cb *SSL_CTX_get_default_passwd_cb(SSL_CTX *ctx); void *SSL_CTX_get_default_passwd_cb_userdata(SSL_CTX *ctx); - void SSL_set_default_passwd_cb(SSL *s, SSL_CTX_passwd_cb *cb); + void SSL_set_default_passwd_cb(SSL *s, pem_password_cb *cb); void SSL_set_default_passwd_cb_userdata(SSL *s, void *u); - SSL_CTX_passwd_cb *SSL_get_default_passwd_cb(SSL *s); + pem_password_cb *SSL_get_default_passwd_cb(SSL *s); void *SSL_get_default_passwd_cb_userdata(SSL *s); - typedef int (*SSL_CTX_passwd_cb)(char *buf, int size, int rwflag, void *u); - =head1 DESCRIPTION SSL_CTX_set_default_passwd_cb() sets the default password callback called @@ -46,12 +43,14 @@ SSL_get_default_passwd_cb() and SSL_get_default_passwd_cb_userdata() perform the same function as their SSL_CTX counterparts, but using an SSL object. The password callback, which must be provided by the application, hands back the -password to be used during decryption. On invocation a pointer to userdata +password to be used during decryption. +On invocation a pointer to userdata is provided. The function must store the password into the provided buffer B which is of size B. The actual length of the password must be returned to the calling function. B indicates whether the callback is used for reading/decryption (rwflag=0) or writing/encryption (rwflag=1). +For more details, see L. =head1 NOTES diff --git a/doc/ssl/SSL_CTX_set_read_ahead.pod b/doc/ssl/SSL_CTX_set_read_ahead.pod index d2b584d35c..bea8390085 100644 --- a/doc/ssl/SSL_CTX_set_read_ahead.pod +++ b/doc/ssl/SSL_CTX_set_read_ahead.pod @@ -2,21 +2,21 @@ =head1 NAME -SSL_CTX_set_read_ahead, SSL_CTX_set_default_read_ahead, SSL_CTX_get_read_ahead, -SSL_CTX_get_default_read_ahead, SSL_set_read_ahead, SSL_get_read_ahead +SSL_CTX_set_read_ahead, SSL_CTX_get_read_ahead, +SSL_set_read_ahead, SSL_get_read_ahead, +SSL_CTX_get_default_read_ahead - manage whether to read as many input bytes as possible =head1 SYNOPSIS #include - int SSL_get_read_ahead(const SSL *s); void SSL_set_read_ahead(SSL *s, int yes); + int SSL_get_read_ahead(const SSL *s); - #define SSL_CTX_get_default_read_ahead(ctx) - #define SSL_CTX_set_default_read_ahead(ctx,m) - #define SSL_CTX_get_read_ahead(ctx) - #define SSL_CTX_set_read_ahead(ctx,m) + SSL_CTX_set_read_ahead(SSL_CTX *ctx, int yes); + long SSL_CTX_get_read_ahead(SSL_CTX *ctx); + long SSL_CTX_get_default_read_ahead(SSL_CTX *ctx); =head1 DESCRIPTION @@ -27,9 +27,7 @@ the underlying BIO (where B > B), then OpenSSL will read all B bytes into its buffer (providing that the buffer is large enough) if reading ahead is on, or B bytes otherwise. The parameter B or B should be 0 to ensure reading ahead is off, or non zero otherwise. - -SSL_CTX_set_default_read_ahead is a synonym for SSL_CTX_set_read_ahead, and -SSL_CTX_get_default_read_ahead is a synonym for SSL_CTX_get_read_ahead. +SSL_CTX_set_default_read_ahead() is identical to SSL_CTX_set_read_ahead(). SSL_CTX_get_read_ahead() and SSL_get_read_ahead() indicate whether reading ahead has been set or not. diff --git a/doc/ssl/SSL_CTX_set_split_send_fragment.pod b/doc/ssl/SSL_CTX_set_split_send_fragment.pod index a1f42e2eaf..accf5af247 100644 --- a/doc/ssl/SSL_CTX_set_split_send_fragment.pod +++ b/doc/ssl/SSL_CTX_set_split_send_fragment.pod @@ -12,18 +12,14 @@ fragment sizes and pipelining operations #include - # define SSL_CTX_set_max_send_fragment(ctx,m) \ - SSL_CTX_ctrl(ctx,SSL_CTRL_SET_MAX_SEND_FRAGMENT,m,NULL) - # define SSL_set_max_send_fragment(ssl,m) \ - SSL_ctrl(ssl,SSL_CTRL_SET_MAX_SEND_FRAGMENT,m,NULL) - # define SSL_CTX_set_max_pipelines(ctx,m) \ - SSL_CTX_ctrl(ctx,SSL_CTRL_SET_MAX_PIPELINES,m,NULL) - # define SSL_set_max_pipelines(ssl,m) \ - SSL_ctrl(ssl,SSL_CTRL_SET_MAX_PIPELINES,m,NULL) - # define SSL_CTX_set_split_send_fragment(ctx,m) \ - SSL_CTX_ctrl(ctx,SSL_CTRL_SET_SPLIT_SEND_FRAGMENT,m,NULL) - # define SSL_set_split_send_fragment(ssl,m) \ - SSL_ctrl(ssl,SSL_CTRL_SET_SPLIT_SEND_FRAGMENT,m,NULL) + long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long); + long SSL_set_max_send_fragment(SSL *ssl, long m); + + long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m); + long SSL_set_max_pipelines(SSL_CTX *ssl, long m); + + long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m); + long SSL_set_split_send_fragment(SSL *ssl, long m); void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len); void SSL_set_default_read_buffer_len(SSL *s, size_t len); diff --git a/doc/ssl/SSL_get_current_cipher.pod b/doc/ssl/SSL_get_current_cipher.pod index 0fdf60f6c1..4b53063e08 100644 --- a/doc/ssl/SSL_get_current_cipher.pod +++ b/doc/ssl/SSL_get_current_cipher.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_get_current_cipher, SSL_get_cipher, SSL_get_cipher_name, +SSL_get_current_cipher, SSL_get_cipher_name, SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection =head1 SYNOPSIS @@ -10,32 +10,35 @@ SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection #include SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl); - #define SSL_get_cipher(s) \ - SSL_CIPHER_get_name(SSL_get_current_cipher(s)) - #define SSL_get_cipher_name(s) \ - SSL_CIPHER_get_name(SSL_get_current_cipher(s)) - #define SSL_get_cipher_bits(s,np) \ - SSL_CIPHER_get_bits(SSL_get_current_cipher(s),np) - #define SSL_get_cipher_version(s) \ - SSL_CIPHER_get_version(SSL_get_current_cipher(s)) + + const char *SSL_get_cipher_name(const SSL *s); + const char *SSL_get_cipher(const SSL *s); + int SSL_get_cipher_bits(const SSL *s, int *np) \ + const char *SSL_get_cipher_version(const SSL *s); =head1 DESCRIPTION SSL_get_current_cipher() returns a pointer to an SSL_CIPHER object containing the description of the actually used cipher of a connection established with the B object. +See L for more details. -SSL_get_cipher() and SSL_get_cipher_name() are identical macros to obtain the -name of the currently used cipher. SSL_get_cipher_bits() is a +SSL_get_cipher_name() obtains the +name of the currently used cipher. +SSL_get_cipher() is identical to SSL_get_cipher_name(). +SSL_get_cipher_bits() is a macro to obtain the number of secret/algorithm bits used and SSL_get_cipher_version() returns the protocol name. -See L for more details. =head1 RETURN VALUES -SSL_get_current_cipher() returns the cipher actually used or NULL, when +SSL_get_current_cipher() returns the cipher actually used, or NULL if no session has been established. +=head1 NOTES + +These are implemented as macros. + =head1 SEE ALSO L, L diff --git a/doc/ssl/SSL_library_init.pod b/doc/ssl/SSL_library_init.pod index 57b65d5d56..6b921f66e7 100644 --- a/doc/ssl/SSL_library_init.pod +++ b/doc/ssl/SSL_library_init.pod @@ -10,13 +10,15 @@ SSL_library_init, OpenSSL_add_ssl_algorithms, #include int SSL_library_init(void); - #define OpenSSL_add_ssl_algorithms() SSL_library_init() + + int OpenSSL_add_ssl_algorithms(void); =head1 DESCRIPTION SSL_library_init() registers the available SSL/TLS ciphers and digests. -OpenSSL_add_ssl_algorithms() is a synonym for SSL_library_init(). +OpenSSL_add_ssl_algorithms() is a synonym for SSL_library_init() and is +implemented as a macro. =head1 NOTES diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod index dfd83ead2d..eb63485b36 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -318,7 +318,7 @@ protocol context defined in the B structure. =item LHASH *B(SSL_CTX *ctx); -=item void B(SSL_CTX *ctx, void *arg); +=item int B(SSL_CTX *ctx, void *arg); =item void B(SSL_CTX *ctx, X509_STORE *cs); @@ -437,7 +437,7 @@ sessions defined in the B structures. =item int B(FILE *fp, const SSL_SESSION *x); -=item void B(SSL_SESSION *s, char *a); +=item int B(SSL_SESSION *s, char *a); =item int B(SSL_SESSION *s, int idx, char *arg); diff --git a/include/openssl/bio.h b/include/openssl/bio.h index 503fbcd5a8..d486d07199 100644 --- a/include/openssl/bio.h +++ b/include/openssl/bio.h @@ -87,7 +87,6 @@ extern "C" { # define BIO_CTRL_FLUSH 11/* opt - 'flush' buffered output */ # define BIO_CTRL_DUP 12/* man - extra stuff for 'duped' BIO */ # define BIO_CTRL_WPENDING 13/* opt - number of bytes still to write */ -/* callback is int cb(BIO *bio,state,ret); */ # define BIO_CTRL_SET_CALLBACK 14/* opt - set callback function */ # define BIO_CTRL_GET_CALLBACK 15/* opt - set callback function */ @@ -236,11 +235,10 @@ void BIO_clear_flags(BIO *b, int flags); # define BIO_cb_pre(a) (!((a)&BIO_CB_RETURN)) # define BIO_cb_post(a) ((a)&BIO_CB_RETURN) -long (*BIO_get_callback(const BIO *b)) (BIO *, int, const char *, - int, long, long); -void BIO_set_callback(BIO *b, - long (*callback) (BIO *, int, const char *, - int, long, long)); +typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi, + long argl, long ret); +BIO_callback_fn BIO_get_callback(const BIO *b); +void BIO_set_callback(BIO *b, BIO_callback_fn callback); char *BIO_get_callback_arg(const BIO *b); void BIO_set_callback_arg(BIO *b, char *arg); @@ -249,8 +247,7 @@ typedef struct bio_method_st BIO_METHOD; const char *BIO_method_name(const BIO *b); int BIO_method_type(const BIO *b); -typedef void bio_info_cb (BIO *, int, const char *, int, long, - long); +typedef void bio_info_cb(BIO *, int, const char *, int, long, long); DEFINE_STACK_OF(BIO) diff --git a/util/indent.pro b/util/indent.pro index 71997cb41b..8c93f0c517 100644 --- a/util/indent.pro +++ b/util/indent.pro @@ -571,6 +571,7 @@ -T asn1_ps_func -T bio_dgram_data -T bio_info_cb +-T BIO_callack_fn -T char_io -T conf_finish_func -T conf_init_func