diff options
author | Rich Salz <rsalz@openssl.org> | 2016-06-21 07:03:34 -0400 |
---|---|---|
committer | Rich Salz <rsalz@openssl.org> | 2016-06-21 07:03:34 -0400 |
commit | c952780c25f67d0645ef5e57a8ac7dae6ce2d586 (patch) | |
tree | 31c9e7f3c7e8f4b93337e58ab9370322e8d624e2 /doc | |
parent | 6feb3c587e4bcfd73cf72da65384c310f2ee9ff2 (diff) |
More doc cleanup
Add missing entries to NAME section
Add SYNOPSIS lines, remove old NAME entries
Update find-doc-nits; better regexp's for parsing SYNOPSIS sections.
Rename a couple of files to have an API name.
Remove RSA_private_decrypt; it was duplicate content
Update for recent doc additions
Reviewed-by: Matt Caswell <matt@openssl.org>
Diffstat (limited to 'doc')
74 files changed, 377 insertions, 266 deletions
diff --git a/doc/crypto/ASN1_STRING_length.pod b/doc/crypto/ASN1_STRING_length.pod index 78513f8a89..a51d984454 100644 --- a/doc/crypto/ASN1_STRING_length.pod +++ b/doc/crypto/ASN1_STRING_length.pod @@ -3,7 +3,7 @@ =head1 NAME ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, -ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data, ASN1_STRING_to_UTF8 - +ASN1_STRING_type, ASN1_STRING_data, ASN1_STRING_to_UTF8 - ASN1_STRING utility functions =head1 SYNOPSIS diff --git a/doc/crypto/ASYNC_start_job.pod b/doc/crypto/ASYNC_start_job.pod index b5139a34a9..20bc1ad2aa 100644 --- a/doc/crypto/ASYNC_start_job.pod +++ b/doc/crypto/ASYNC_start_job.pod @@ -2,8 +2,8 @@ =head1 NAME +ASYNC_get_wait_ctx, ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job, -ASYNC_in_job, ASYNC_get_wait_fd, ASYNC_set_wait_fd, ASYNC_clear_wait_fd, ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable - asynchronous job management functions diff --git a/doc/crypto/BIO_f_buffer.pod b/doc/crypto/BIO_f_buffer.pod index 68811c3c93..286a39c9ed 100644 --- a/doc/crypto/BIO_f_buffer.pod +++ b/doc/crypto/BIO_f_buffer.pod @@ -2,6 +2,11 @@ =head1 NAME +BIO_get_buffer_num_lines, +BIO_set_read_buffer_size, +BIO_set_write_buffer_size, +BIO_set_buffer_size, +BIO_set_buffer_read_data, BIO_f_buffer - buffering BIO =head1 SYNOPSIS diff --git a/doc/crypto/BIO_f_ssl.pod b/doc/crypto/BIO_f_ssl.pod index 4c9da6a2ca..4007130150 100644 --- a/doc/crypto/BIO_f_ssl.pod +++ b/doc/crypto/BIO_f_ssl.pod @@ -2,7 +2,9 @@ =head1 NAME -BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes, +BIO_do_handshake, +BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, +BIO_set_ssl_renegotiate_bytes, BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, BIO_ssl_shutdown - SSL BIO diff --git a/doc/crypto/BIO_find_type.pod b/doc/crypto/BIO_find_type.pod index c5029837b0..f03071ad9b 100644 --- a/doc/crypto/BIO_find_type.pod +++ b/doc/crypto/BIO_find_type.pod @@ -2,6 +2,12 @@ =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 diff --git a/doc/crypto/BIO_get_ex_new_index.pod b/doc/crypto/BIO_get_ex_new_index.pod index 21e5bb76ab..3e24f10bc3 100644 --- a/doc/crypto/BIO_get_ex_new_index.pod +++ b/doc/crypto/BIO_get_ex_new_index.pod @@ -15,28 +15,38 @@ ECDSA_get_ex_new_index, ECDSA_set_ex_data, ECDSA_get_ex_data, RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - application-specific data -=head1 SYNOPSIS +=for comment generic -The synopsis below is for the X509 structure, but is the same for all -crypto structures: +=head1 SYNOPSIS #include <openssl/x509.h> - int X509_get_ex_new_index(long argl, void *argp, + int TYPE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); - int X509_set_ex_data(X509 *d, int idx, void *arg); + int TYPE_set_ex_data(TYPE *d, int idx, void *arg); - void *X509_get_ex_data(X509 *d, int idx); + void *TYPE_get_ex_data(TYPE *d, int idx); =head1 DESCRIPTION -These functions handle application-specific data for OpenSSL crypto +In the description here, I<TYPE> is used a placeholder +for any of the OpenSSL datatypes listed in +L<CRYPTO_get_ex_new_index(3)>. + +These functions handle application-specific data for OpenSSL data structures. -For details, see L<CRYPTO_get_ex_new_index(3)>. +TYPE_get_new_ex_index() is a macro that calls CRYPTO_get_ex_new_index() +with the correct B<index> value. + +TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with +an offset into the opaque exdata part of the TYPE object. + +TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with an +an offset into the opaque exdata part of the TYPE object. =head1 SEE ALSO diff --git a/doc/crypto/BIO_s_accept.pod b/doc/crypto/BIO_s_accept.pod index ad7bfaac4b..a9259ab217 100644 --- a/doc/crypto/BIO_s_accept.pod +++ b/doc/crypto/BIO_s_accept.pod @@ -2,6 +2,7 @@ =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 diff --git a/doc/crypto/BIO_s_connect.pod b/doc/crypto/BIO_s_connect.pod index d97d5899a5..29192a6cf0 100644 --- a/doc/crypto/BIO_s_connect.pod +++ b/doc/crypto/BIO_s_connect.pod @@ -2,9 +2,10 @@ =head1 NAME +BIO_set_conn_address, BIO_get_conn_address, BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port, -BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname, -BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port, +BIO_get_conn_hostname, +BIO_get_conn_port, BIO_set_nbio, BIO_do_connect - connect BIO =head1 SYNOPSIS diff --git a/doc/crypto/BIO_s_mem.pod b/doc/crypto/BIO_s_mem.pod index 56d10bd8dd..afde930906 100644 --- a/doc/crypto/BIO_s_mem.pod +++ b/doc/crypto/BIO_s_mem.pod @@ -2,6 +2,7 @@ =head1 NAME +BIO_s_secmem, BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf, BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO diff --git a/doc/crypto/BIO_s_socket.pod b/doc/crypto/BIO_s_socket.pod index 88aaa88c49..ad0574aee6 100644 --- a/doc/crypto/BIO_s_socket.pod +++ b/doc/crypto/BIO_s_socket.pod @@ -10,9 +10,6 @@ BIO_s_socket, BIO_new_socket - socket BIO const BIO_METHOD *BIO_s_socket(void); - long BIO_set_fd(BIO *b, int fd, long close_flag); - long BIO_get_fd(BIO *b, int *c); - BIO *BIO_new_socket(int sock, int close_flag); =head1 DESCRIPTION @@ -26,12 +23,6 @@ BIO_puts() is supported but BIO_gets() is not. If the close flag is set then the socket is shut down and closed when the BIO is freed. -BIO_set_fd() sets the socket of BIO B<b> to B<fd> and the close -flag to B<close_flag>. - -BIO_get_fd() places the socket in B<c> if it is not NULL, it also -returns the socket. If B<c> is not NULL it should be of type (int *). - BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>. =head1 NOTES @@ -44,17 +35,10 @@ platforms sockets are not file descriptors and use distinct I/O routines, Windows is one such platform. Any code mixing the two will not work on all platforms. -BIO_set_fd() and BIO_get_fd() are macros. - =head1 RETURN VALUES BIO_s_socket() returns the socket BIO method. -BIO_set_fd() always returns 1. - -BIO_get_fd() returns the socket or -1 if the BIO has not been -initialized. - BIO_new_socket() returns the newly allocated BIO or NULL is an error occurred. diff --git a/doc/crypto/BIO_should_retry.pod b/doc/crypto/BIO_should_retry.pod index fc728ff9f2..2a6485af9a 100644 --- a/doc/crypto/BIO_should_retry.pod +++ b/doc/crypto/BIO_should_retry.pod @@ -2,6 +2,8 @@ =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 diff --git a/doc/crypto/BN_CTX_new.pod b/doc/crypto/BN_CTX_new.pod index f2edd49a97..ca54590517 100644 --- a/doc/crypto/BN_CTX_new.pod +++ b/doc/crypto/BN_CTX_new.pod @@ -2,7 +2,7 @@ =head1 NAME -BN_CTX_new, BN_CTX_secure_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures +BN_CTX_new, BN_CTX_secure_new, BN_CTX_free - allocate and free BN_CTX structures =head1 SYNOPSIS diff --git a/doc/crypto/BN_bn2bin.pod b/doc/crypto/BN_bn2bin.pod index b0a8b50d5e..14b152e430 100644 --- a/doc/crypto/BN_bn2bin.pod +++ b/doc/crypto/BN_bn2bin.pod @@ -2,6 +2,7 @@ =head1 NAME +BN_bn2binpad, BN_bn2bin, BN_bin2bn, BN_bn2lebinpad, BN_lebin2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn, BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn - format conversions diff --git a/doc/crypto/BN_mod_mul_montgomery.pod b/doc/crypto/BN_mod_mul_montgomery.pod index 152185f6f2..bf1ef343cd 100644 --- a/doc/crypto/BN_mod_mul_montgomery.pod +++ b/doc/crypto/BN_mod_mul_montgomery.pod @@ -2,7 +2,7 @@ =head1 NAME -BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_init, +BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy, BN_from_montgomery, BN_to_montgomery - Montgomery multiplication @@ -69,26 +69,6 @@ The error codes can be obtained by L<ERR_get_error(3)>. The inputs must be reduced modulo B<m>, otherwise the result will be outside the expected range. -=head1 REMOVED FUNCTIONALITY - - void BN_MONT_CTX_init(BN_MONT_CTX *c); - -BN_MONT_CTX_init() is no longer available as of OpenSSL 1.1.0. It was used to -initialize an existing uninitialized B<BN_MONT_CTX>. Typically this would be -done as follows: - - BN_MONT_CTX ctx; - BN_MONT_CTX_init(&ctx); - -Instead applications should create a BN_MONT_CTX structure using -BN_MONT_CTX_new: - - BN_MONT_CTX *ctx; - ctx = BN_MONT_CTX_new(); - if(!ctx) /* handle error */ - ... - BN_MONT_CTX_free(ctx); - =head1 SEE ALSO L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>, diff --git a/doc/crypto/BN_mod_mul_reciprocal.pod b/doc/crypto/BN_mod_mul_reciprocal.pod index 86fb486385..23832b3b6c 100644 --- a/doc/crypto/BN_mod_mul_reciprocal.pod +++ b/doc/crypto/BN_mod_mul_reciprocal.pod @@ -2,7 +2,7 @@ =head1 NAME -BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_init, +BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using reciprocal @@ -30,7 +30,6 @@ using B<recp>=1/B<m>, which is set as described below. B<ctx> is a previously allocated B<BN_CTX> used for temporary variables. BN_RECP_CTX_new() allocates and initializes a B<BN_RECP> structure. -BN_RECP_CTX_init() initializes an existing uninitialized B<BN_RECP>. BN_RECP_CTX_free() frees the components of the B<BN_RECP>, and, if it was created by BN_RECP_CTX_new(), also the structure itself. @@ -51,31 +50,11 @@ The B<BN_RECP_CTX> structure cannot be shared between threads. BN_RECP_CTX_new() returns the newly allocated B<BN_RECP_CTX>, and NULL on error. -BN_RECP_CTX_init() and BN_RECP_CTX_free() have no return values. +BN_RECP_CTX_free() has no return value. For the other functions, 1 is returned for success, 0 on error. The error codes can be obtained by L<ERR_get_error(3)>. -=head1 REMOVED FUNCTIONALITY - - void BN_RECP_CTX_init(BN_RECP_CTX *recp); - -BN_RECP_CTX_init() is no longer available as of OpenSSL 1.1.0. It was used to -initialize an existing uninitialized B<BN_RECP_CTX>. Typically this would be -done as follows: - - BN_RECP_CTX ctx; - BN_RECP_CTX_init(&ctx); - -Applications should replace use of BN_RECP_CTX_init with BN_RECP_CTX_new -instead: - - BN_RECP_CTX *ctx; - ctx = BN_RECP_CTX_new(); - if(!ctx) /* Handle error */ - ... - BN_RECP_CTX_free(ctx); - =head1 SEE ALSO L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>, @@ -83,7 +62,7 @@ L<BN_CTX_new(3)> =head1 HISTORY -BN_RECP_CTX_init was removed in OpenSSL 1.1.0 +BN_RECP_CTX_init() was removed in OpenSSL 1.1.0 =head1 COPYRIGHT diff --git a/doc/crypto/BUF_MEM_new.pod b/doc/crypto/BUF_MEM_new.pod index 16fe3daa84..1a975776aa 100644 --- a/doc/crypto/BUF_MEM_new.pod +++ b/doc/crypto/BUF_MEM_new.pod @@ -2,8 +2,10 @@ =head1 NAME -BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow - simple -character array structure +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 standard C library equivalents @@ -17,9 +19,12 @@ standard C library equivalents BUF_MEM *BUF_MEM_new_ex(unsigned long flags); - void BUF_MEM_free(BUF_MEM *a); + void BUF_MEM_free(BUF_MEM *a); - int BUF_MEM_grow(BUF_MEM *str, int len); + int BUF_MEM_grow(BUF_MEM *str, int len); + size_t BUF_MEM_grow_clean(BUF_MEM *str, size_t len); + + void BUF_reverse(unsigned char *out, const unsigne |