diff options
Diffstat (limited to 'crypto/openssl/doc/crypto')
116 files changed, 9898 insertions, 0 deletions
diff --git a/crypto/openssl/doc/crypto/BIO_ctrl.pod b/crypto/openssl/doc/crypto/BIO_ctrl.pod new file mode 100644 index 0000000..722e8b8 --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_ctrl.pod @@ -0,0 +1,128 @@ +=pod + +=head1 NAME + +BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset, +BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close, +BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending, +BIO_get_info_callback, BIO_set_info_callback - BIO control operations + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + 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); + + 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_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); + +=head1 DESCRIPTION + +BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl() +are BIO "control" operations taking arguments of various types. +These functions are not normally called directly, various macros +are used instead. The standard macros are described below, macros +specific to a particular type of BIO are described in the specific +BIOs manual page as well as any special features of the standard +calls. + +BIO_reset() typically resets a BIO to some initial state, in the case +of file related BIOs for example it rewinds the file pointer to the +start of the file. + +BIO_seek() resets a file related BIO's (that is file descriptor and +FILE BIOs) file position pointer to B<ofs> bytes from start of file. + +BIO_tell() returns the current file position of a file related BIO. + +BIO_flush() normally writes out any internally buffered data, in some +cases it is used to signal EOF and that no more data will be written. + +BIO_eof() returns 1 if the BIO has read EOF, the precise meaning of +"EOF" varies according to the BIO type. + +BIO_set_close() sets the BIO B<b> close flag to B<flag>. B<flag> can +take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used +in a source/sink BIO to indicate that the underlying I/O stream should +be closed when the BIO is freed. + +BIO_get_close() returns the BIOs close flag. + +BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() +return the number of pending characters in the BIOs read and write buffers. +Not all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending() +return a size_t type and are functions, BIO_pending() and BIO_wpending() are +macros which call BIO_ctrl(). + +=head1 RETURN VALUES + +BIO_reset() normally returns 1 for success and 0 or -1 for failure. File +BIOs are an exception, they return 0 for success and -1 for failure. + +BIO_seek() and BIO_tell() both return the current file position on success +and -1 for failure, except file BIOs which for BIO_seek() always return 0 +for success and -1 for failure. + +BIO_flush() returns 1 for success and 0 or -1 for failure. + +BIO_eof() returns 1 if EOF has been reached 0 otherwise. + +BIO_set_close() always returns 1. + +BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE. + +BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() +return the amount of pending data. + +=head1 NOTES + +BIO_flush(), because it can write data may return 0 or -1 indicating +that the call should be retried later in a similar manner to BIO_write(). +The BIO_should_retry() call should be used and appropriate action taken +is the call fails. + +The return values of BIO_pending() and BIO_wpending() may not reliably +determine the amount of pending data in all cases. For example in the +case of a file BIO some data may be available in the FILE structures +internal buffers but it is not possible to determine this in a +portably way. For other types of BIO they may not be supported. + +Filter BIOs if they do not internally handle a particular BIO_ctrl() +operation usually pass the operation to the next BIO in the chain. +This often means there is no need to locate the required BIO for +a particular operation, it can be called on a chain and it will +be automatically passed to the relevant BIO. However this can cause +unexpected results: for example no current filter BIOs implement +BIO_seek(), but this may still succeed if the chain ends in a FILE +or file descriptor BIO. + +Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl() +operation. + +=head1 BUGS + +Some of the return values are ambiguous and care should be taken. In +particular a return value of 0 can be returned if an operation is not +supported, if an error occurred, if EOF has not been reached and in +the case of BIO_seek() on a file BIO for a successful operation. + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_f_base64.pod b/crypto/openssl/doc/crypto/BIO_f_base64.pod new file mode 100644 index 0000000..fdb603b --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_f_base64.pod @@ -0,0 +1,82 @@ +=pod + +=head1 NAME + +BIO_f_base64 - base64 BIO filter + +=head1 SYNOPSIS + + #include <openssl/bio.h> + #include <openssl/evp.h> + + BIO_METHOD * BIO_f_base64(void); + +=head1 DESCRIPTION + +BIO_f_base64() returns the base64 BIO method. This is a filter +BIO that base64 encodes any data written through it and decodes +any data read through it. + +Base64 BIOs do not support BIO_gets() or BIO_puts(). + +BIO_flush() on a base64 BIO that is being written through is +used to signal that no more data is to be encoded: this is used +to flush the final block through the BIO. + +The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags() +to encode the data all on one line or expect the data to be all +on one line. + +=head1 NOTES + +Because of the format of base64 encoding the end of the encoded +block cannot always be reliably determined. + +=head1 RETURN VALUES + +BIO_f_base64() returns the base64 BIO method. + +=head1 EXAMPLES + +Base64 encode the string "Hello World\n" and write the result +to standard output: + + BIO *bio, *b64; + char message[] = "Hello World \n"; + + b64 = BIO_new(BIO_f_base64()); + bio = BIO_new_fp(stdout, BIO_NOCLOSE); + bio = BIO_push(b64, bio); + BIO_write(bio, message, strlen(message)); + BIO_flush(bio); + + BIO_free_all(bio); + +Read Base64 encoded data from standard input and write the decoded +data to standard output: + + BIO *bio, *b64, bio_out; + char inbuf[512]; + int inlen; + char message[] = "Hello World \n"; + + b64 = BIO_new(BIO_f_base64()); + bio = BIO_new_fp(stdin, BIO_NOCLOSE); + bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); + bio = BIO_push(b64, bio); + while((inlen = BIO_read(bio, inbuf, strlen(message))) > 0) + BIO_write(bio_out, inbuf, inlen); + + BIO_free_all(bio); + +=head1 BUGS + +The ambiguity of EOF in base64 encoded data can cause additional +data following the base64 encoded block to be misinterpreted. + +There should be some way of specifying a test that the BIO can perform +to reliably determine EOF (for example a MIME boundary). + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_f_buffer.pod b/crypto/openssl/doc/crypto/BIO_f_buffer.pod new file mode 100644 index 0000000..c9093c6 --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_f_buffer.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + +BIO_f_buffer - buffering BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO_METHOD * BIO_f_buffer(void); + + #define BIO_get_buffer_num_lines(b) BIO_ctrl(b,BIO_C_GET_BUFF_NUM_LINES,0,NULL) + #define BIO_set_read_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,0) + #define BIO_set_write_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,1) + #define BIO_set_buffer_size(b,size) BIO_ctrl(b,BIO_C_SET_BUFF_SIZE,size,NULL) + #define BIO_set_buffer_read_data(b,buf,num) BIO_ctrl(b,BIO_C_SET_BUFF_READ_DATA,num,buf) + +=head1 DESCRIPTION + +BIO_f_buffer() returns the buffering BIO method. + +Data written to a buffering BIO is buffered and periodically written +to the next BIO in the chain. Data read from a buffering BIO comes from +an internal buffer which is filled from the next BIO in the chain. +Both BIO_gets() and BIO_puts() are supported. + +Calling BIO_reset() on a buffering BIO clears any buffered data. + +BIO_get_buffer_num_lines() returns the number of lines currently buffered. + +BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() +set the read, write or both read and write buffer sizes to B<size>. The initial +buffer size is DEFAULT_BUFFER_SIZE, currently 1024. Any attempt to reduce the +buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared +when the buffer is resized. + +BIO_set_buffer_read_data() clears the read buffer and fills it with B<num> +bytes of B<buf>. If B<num> is larger than the current buffer size the buffer +is expanded. + +=head1 NOTES + +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 +support it (for example SSL BIOs). + +Data is only written to the next BIO in the chain when the write buffer fills +or when BIO_flush() is called. It is therefore important to call BIO_flush() +whenever any pending data should be written such as when removing a buffering +BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate +source/sink BIO is non blocking. + +=head1 RETURN VALUES + +BIO_f_buffer() returns the buffering BIO method. + +BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0). + +BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() +return 1 if the buffer was successfully resized or 0 for failure. + +BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if +there was an error. + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_f_cipher.pod b/crypto/openssl/doc/crypto/BIO_f_cipher.pod new file mode 100644 index 0000000..4182f2c --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_f_cipher.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + +BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter + +=head1 SYNOPSIS + + #include <openssl/bio.h> + #include <openssl/evp.h> + + BIO_METHOD * BIO_f_cipher(void); + void BIO_set_cipher(BIO *b,const EVP_CIPHER *cipher, + unsigned char *key, unsigned char *iv, int enc); + int BIO_get_cipher_status(BIO *b) + int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx) + +=head1 DESCRIPTION + +BIO_f_cipher() returns the cipher BIO method. This is a filter +BIO that encrypts any data written through it, and decrypts any data +read from it. It is a BIO wrapper for the cipher routines +EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal(). + +Cipher BIOs do not support BIO_gets() or BIO_puts(). + +BIO_flush() on an encryption BIO that is being written through is +used to signal that no more data is to be encrypted: this is used +to flush and possibly pad the final block through the BIO. + +BIO_set_cipher() sets the cipher of BIO <b> to B<cipher> using key B<key> +and IV B<iv>. B<enc> should be set to 1 for encryption and zero for +decryption. + +When reading from an encryption BIO the final block is automatically +decrypted and checked when EOF is detected. BIO_get_cipher_status() +is a BIO_ctrl() macro which can be called to determine whether the +decryption operation was successful. + +BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal +BIO cipher context. The retrieved context can be used in conjunction +with the standard cipher routines to set it up. This is useful when +BIO_set_cipher() is not flexible enough for the applications needs. + +=head1 NOTES + +When encrypting BIO_flush() B<must> be called to flush the final block +through the BIO. If it is not then the final block will fail a subsequent +decrypt. + +When decrypting an error on the final block is signalled by a zero +return value from the read operation. A successful decrypt followed +by EOF will also return zero for the final read. BIO_get_cipher_status() +should be called to determine if the decrypt was successful. + +As always, if BIO_gets() or BIO_puts() support is needed then it can +be achieved by preceding the cipher BIO with a buffering BIO. + +=head1 RETURN VALUES + +BIO_f_cipher() returns the cipher BIO method. + +BIO_set_cipher() does not return a value. + +BIO_get_cipher_status() returns 1 for a successful decrypt and 0 +for failure. + +BIO_get_cipher_ctx() currently always returns 1. + +=head1 EXAMPLES + +TBA + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_f_md.pod b/crypto/openssl/doc/crypto/BIO_f_md.pod new file mode 100644 index 0000000..c32504d --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_f_md.pod @@ -0,0 +1,138 @@ +=pod + +=head1 NAME + +BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter + +=head1 SYNOPSIS + + #include <openssl/bio.h> + #include <openssl/evp.h> + + BIO_METHOD * BIO_f_md(void); + int BIO_set_md(BIO *b,EVP_MD *md); + int BIO_get_md(BIO *b,EVP_MD **mdp); + int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp); + +=head1 DESCRIPTION + +BIO_f_md() returns the message digest BIO method. This is a filter +BIO that digests any data passed through it, it is a BIO wrapper +for the digest routines EVP_DigestInit(), EVP_DigestUpdate() +and EVP_DigestFinal(). + +Any data written or read through a digest BIO using BIO_read() and +BIO_write() is digested. + +BIO_gets(), if its B<size> parameter is large enough finishes the +digest calculation and returns the digest value. BIO_puts() is +not supported. + +BIO_reset() reinitializes a digest BIO. + +BIO_set_md() sets the message digest of BIO B<b> to B<md>: this +must be called to initialize a digest BIO before any data is +passed through it. It is a BIO_ctrl() macro. + +BIO_get_md() places the a pointer to the digest BIOs digest method +in B<mdp>, it is a BIO_ctrl() macro. + +BIO_get_md_ctx() returns the digest BIOs context into B<mdcp>. + +=head1 NOTES + +The context returned by BIO_get_md_ctx() can be used in calls +to EVP_DigestFinal() and also the signature routines EVP_SignFinal() +and EVP_VerifyFinal(). + +The context returned by BIO_get_md_ctx() is an internal context +structure. Changes made to this context will affect the digest +BIO itself and the context pointer will become invalid when the digest +BIO is freed. + +After the digest has been retrieved from a digest BIO it must be +reinitialized by calling BIO_reset(), or BIO_set_md() before any more +data is passed through it. + +If an application needs to call BIO_gets() or BIO_puts() through +a chain containing digest BIOs then this can be done by prepending +a buffering BIO. + +=head1 RETURN VALUES + +BIO_f_md() returns the digest BIO method. + +BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and +0 for failure. + +=head1 EXAMPLES + +The following example creates a BIO chain containing an SHA1 and MD5 +digest BIO and passes the string "Hello World" through it. Error +checking has been omitted for clarity. + + BIO *bio, *mdtmp; + char message[] = "Hello World"; + bio = BIO_new(BIO_s_null()); + mdtmp = BIO_new(BIO_f_md()); + BIO_set_md(mdtmp, EVP_sha1()); + /* For BIO_push() we want to append the sink BIO and keep a note of + * the start of the chain. + */ + bio = BIO_push(mdtmp, bio); + mdtmp = BIO_new(BIO_f_md()); + BIO_set_md(mdtmp, EVP_md5()); + bio = BIO_push(mdtmp, bio); + /* Note: mdtmp can now be discarded */ + BIO_write(bio, message, strlen(message)); + +The next example digests data by reading through a chain instead: + + BIO *bio, *mdtmp; + char buf[1024]; + int rdlen; + bio = BIO_new_file(file, "rb"); + mdtmp = BIO_new(BIO_f_md()); + BIO_set_md(mdtmp, EVP_sha1()); + bio = BIO_push(mdtmp, bio); + mdtmp = BIO_new(BIO_f_md()); + BIO_set_md(mdtmp, EVP_md5()); + bio = BIO_push(mdtmp, bio); + do { + rdlen = BIO_read(bio, buf, sizeof(buf)); + /* Might want to do something with the data here */ + } while(rdlen > 0); + +This next example retrieves the message digests from a BIO chain and +outputs them. This could be used with the examples above. + + BIO *mdtmp; + unsigned char mdbuf[EVP_MAX_MD_SIZE]; + int mdlen; + int i; + mdtmp = bio; /* Assume bio has previously been set up */ + do { + EVP_MD *md; + mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD); + if(!mdtmp) break; + BIO_get_md(mdtmp, &md); + printf("%s digest", OBJ_nid2sn(EVP_MD_type(md))); + mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE); + for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]); + printf("\n"); + mdtmp = BIO_next(mdtmp); + } while(mdtmp); + + BIO_free_all(bio); + +=head1 BUGS + +The lack of support for BIO_puts() and the non standard behaviour of +BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets() +and BIO_puts() should be passed to the next BIO in the chain and digest +the data passed through and that digests should be retrieved using a +separate BIO_ctrl() call. + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_f_null.pod b/crypto/openssl/doc/crypto/BIO_f_null.pod new file mode 100644 index 0000000..b057c18 --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_f_null.pod @@ -0,0 +1,32 @@ +=pod + +=head1 NAME + +BIO_f_null - null filter + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO_METHOD * BIO_f_null(void); + +=head1 DESCRIPTION + +BIO_f_null() returns the null filter BIO method. This is a filter BIO +that does nothing. + +All requests to a null filter BIO are passed through to the next BIO in +the chain: this means that a BIO chain containing a null filter BIO +behaves just as though the BIO was not there. + +=head1 NOTES + +As may be apparent a null filter BIO is not particularly useful. + +=head1 RETURN VALUES + +BIO_f_null() returns the null filter BIO method. + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_f_ssl.pod b/crypto/openssl/doc/crypto/BIO_f_ssl.pod new file mode 100644 index 0000000..a56ee2b --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_f_ssl.pod @@ -0,0 +1,313 @@ +=pod + +=head1 NAME + +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 + +=head1 SYNOPSIS + + #include <openssl/bio.h> + #include <openssl/ssl.h> + + 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); + 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); + void BIO_ssl_shutdown(BIO *bio); + + #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL) + +=head1 DESCRIPTION + +BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which +is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to +SSL I/O. + +I/O performed on an SSL BIO communicates using the SSL protocol with +the SSLs read and write BIOs. If an SSL connection is not established +then an attempt is made to establish one on the first I/O call. + +If a BIO is appended to an SSL BIO using BIO_push() it is automatically +used as the SSL BIOs read and write BIOs. + +Calling BIO_reset() on an SSL BIO closes down any current SSL connection +by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in +the chain: this will typically disconnect the underlying transport. +The SSL BIO is then reset to the initial accept or connect state. + +If the close flag is set when an SSL BIO is freed then the internal +SSL structure is also freed using SSL_free(). + +BIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using +the close flag B<c>. + +BIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be +manipulated using the standard SSL library functions. + +BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client> +is 1 client mode is set. If B<client> is 0 server mode is set. + +BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count +to B<num>. When set after every B<num> bytes of I/O (read and write) +the SSL session is automatically renegotiated. B<num> must be at +least 512 bytes. + +BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to +B<seconds>. When the renegotiate timeout elapses the session is +automatically renegotiated. + +BIO_get_num_renegotiates() returns the total number of session +renegotiations due to I/O or timeout. + +BIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using +client mode if B<client> is non zero. + +BIO_new_ssl_connect() creates a new BIO chain consisting of an +SSL BIO (using B<ctx>) followed by a connect BIO. + +BIO_new_buffer_ssl_connect() creates a new BIO chain consisting +of a buffering BIO, an SSL BIO (using B<ctx>) and a connect +BIO. + +BIO_ssl_copy_session_id() copies an SSL session id between +BIO chains B<from> and B<to>. It does this by locating the +SSL BIOs in each chain and calling SSL_copy_session_id() on +the internal SSL pointer. + +BIO_ssl_shutdown() closes down an SSL connection on BIO +chain B<bio>. It does this by locating the SSL BIO in the +chain and calling SSL_shutdown() on its internal SSL +pointer. + +BIO_do_handshake() attempts to complete an SSL handshake on the +supplied BIO and establish the SSL connection. It returns 1 +if the connection was established successfully. A zero or negative +value is returned if the connection could not be established, the +call BIO_should_retry() should be used for non blocking connect BIOs +to determine if the call should be retried. If an SSL connection has +already been established this call has no effect. + +=head1 NOTES + +SSL BIOs are exceptional in that if the underlying transport +is non blocking they can still request a retry in exceptional +circumstances. Specifically this will happen if a session +renegotiation takes place during a BIO_read() operation, one +case where this happens is when SGC or step up occurs. + +In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be +set to disable this behaviour. That is when this flag is set +an SSL BIO using a blocking transport will never request a +retry. + +Since unknown BIO_ctrl() operations are sent through filter +BIOs the servers name and port can be set using BIO_set_host() +on the BIO returned by BIO_new_ssl_connect() without having +to locate the connect BIO first. + +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. + +=head1 RETURN VALUES + +TBA + +=head1 EXAMPLE + +This SSL/TLS client example, attempts to retrieve a page from an +SSL/TLS web server. The I/O routines are identical to those of the +unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>. + + BIO *sbio, *out; + int len; + char tmpbuf[1024]; + SSL_CTX *ctx; + SSL *ssl; + + ERR_load_crypto_strings(); + ERR_load_SSL_strings(); + OpenSSL_add_all_algorithms(); + + /* We would seed the PRNG here if the platform didn't + * do it automatically + */ + + ctx = SSL_CTX_new(SSLv23_client_method()); + + /* We'd normally set some stuff like the verify paths and + * mode here because as things stand this will connect to + * any server whose certificate is signed by any CA. + */ + + sbio = BIO_new_ssl_connect(ctx); + + BIO_get_ssl(sbio, &ssl); + + if(!ssl) { + fprintf(stderr, "Can't locate SSL pointer\n"); + /* whatever ... */ + } + + /* Don't want any retries */ + SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); + + /* We might want to do other things with ssl here */ + + BIO_set_conn_hostname(sbio, "localhost:https"); + + out = BIO_new_fp(stdout, BIO_NOCLOSE); + if(BIO_do_connect(sbio) <= 0) { + fprintf(stderr, "Error connecting to server\n"); + ERR_print_errors_fp(stderr); + /* whatever ... */ + } + + if(BIO_do_handshake(sbio) <= 0) { + fprintf(stderr, "Error establishing SSL connection\n"); + ERR_print_errors_fp(stderr); + /* whatever ... */ + } + + /* Could examine ssl here to get connection info */ + + BIO_puts(sbio, "GET / HTTP/1.0\n\n"); + for(;;) { + len = BIO_read(sbio, tmpbuf, 1024); + if(len <= 0) break; + BIO_write(out, tmpbuf, len); + } + BIO_free_all(sbio); + BIO_free(out); + +Here is a simple server example. It makes use of a buffering +BIO to allow lines to be read from the SSL BIO using BIO_gets. +It creates a pseudo web page containing the actual request from +a client and also echoes the request to standard output. + + BIO *sbio, *bbio, *acpt, *out; + int len; + char tmpbuf[1024]; + SSL_CTX *ctx; + SSL *ssl; + + ERR_load_crypto_strings(); + ERR_load_SSL_strings(); + OpenSSL_add_all_algorithms(); + + /* Might seed PRNG here */ + + ctx = SSL_CTX_new(SSLv23_server_method()); + + if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM) + || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM) + || !SSL_CTX_check_private_key(ctx)) { + + fprintf(stderr, "Error setting up SSL_CTX\n"); + ERR_print_errors_fp(stderr); + return 0; + } + + /* Might do other things here like setting verify locations and + * DH and/or RSA temporary key callbacks + */ + + /* New SSL BIO setup as server */ + sbio=BIO_new_ssl(ctx,0); + + BIO_get_ssl(sbio, &ssl); + + if(!ssl) { + fprintf(stderr, "Can't locate SSL pointer\n"); + /* whatever ... */ + } + + /* Don't want any retries */ + SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); + + /* Create the buffering BIO */ + + bbio = BIO_new(BIO_f_buffer()); + + /* Add to chain */ + sbio = BIO_push(bbio, sbio); + + acpt=BIO_new_accept("4433"); + + /* By doing this when a new connection is established + * we automatically have sbio inserted into it. The + * BIO chain is now 'swallowed' by the accept BIO and + * will be freed when the accept BIO is freed. + */ + + BIO_set_accept_bios(acpt,sbio); + + out = BIO_new_fp(stdout, BIO_NOCLOSE); + + /* Setup accept BIO */ + if(BIO_do_accept(acpt) <= 0) { + fprintf(stderr, "Error setting up accept BIO\n"); + ERR_print_errors_fp(stderr); + return 0; + } + + /* Now wait for incoming connection */ + if(BIO_do_accept(acpt) <= 0) { + fprintf(stderr, "Error in connection\n"); + ERR_print_errors_fp(stderr); + return 0; + } + + /* We only want one connection so remove and free + * accept BIO + */ + + sbio = BIO_pop(acpt); + + BIO_free_all(acpt); + + if(BIO_do_handshake(sbio) <= 0) { + fprintf(stderr, "Error in SSL handshake\n"); + ERR_print_errors_fp(stderr); + return 0; + } + + BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/html\r\n\r\n"); + BIO_puts(sbio, "<pre>\r\nConnection Established\r\nRequest headers:\r\n"); + BIO_puts(sbio, "--------------------------------------------------\r\n"); + + for(;;) { + len = BIO_gets(sbio, tmpbuf, 1024); + if(len <= 0) break; + BIO_write(sbio, tmpbuf, len); + BIO_write(out, tmpbuf, len); + /* Look for blank line signifying end of headers*/ + if((tmpbuf[0] == '\r') || (tmpbuf[0] == '\n')) break; + } + + BIO_puts(sbio, "--------------------------------------------------\r\n"); + BIO_puts(sbio, "</pre>\r\n"); + + /* Since there is a buffering BIO present we had better flush it */ + BIO_flush(sbio); + + BIO_free_all(sbio); + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_find_type.pod b/crypto/openssl/doc/crypto/BIO_find_type.pod new file mode 100644 index 0000000..bd3b256 --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_find_type.pod @@ -0,0 +1,98 @@ +=pod + +=head1 NAME + +BIO_find_type, BIO_next - BIO chain traversal + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + 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 + +=head1 DESCRIPTION + +The BIO_find_type() searches for a BIO of a given type in a chain, starting +at BIO B<b>. If B<type> is a specific type (such as BIO_TYPE_MEM) then a search +is made for a BIO of that type. If B<type> is a general type (such as +B<BIO_TYPE_SOURCE_SINK>) 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<BIO_TYPE_*> types above have corresponding BIO implementations. + +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 +certain type. + +BIO_method_type() returns the type of a BIO. + +=head1 RETURN VALUES + +BIO_find_type() returns a matching BIO or NULL for no match. + +BIO_next() returns the next BIO in a chain. + +BIO_method_type() returns the type of the BIO B<b>. + +=head1 NOTES + +BIO_next() was added to OpenSSL 0.9.6 to provide a 'clean' way to traverse a BIO +chain or find multiple matches using BIO_find_type(). Previous versions had to +use: + + next = bio->next_bio; + +=head1 BUGS + +BIO_find_type() in OpenSSL 0.9.5a and earlier could not be safely passed a +NULL pointer for the B<b> argument. + +=head1 EXAMPLE + +Traverse a chain looking for digest BIOs: + + BIO *btmp; + btmp = in_bio; /* in_bio is chain to search through */ + + do { + btmp = BIO_find_type(btmp, BIO_TYPE_MD); + if(btmp == NULL) break; /* Not found */ + /* btmp is a digest BIO, do something with it ...*/ + ... + + btmp = BIO_next(btmp); + } while(btmp); + + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_new.pod b/crypto/openssl/doc/crypto/BIO_new.pod new file mode 100644 index 0000000..2a245fc --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_new.pod @@ -0,0 +1,65 @@ +=pod + +=head1 NAME + +BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO * BIO_new(BIO_METHOD *type); + int BIO_set(BIO *a,BIO_METHOD *type); + int BIO_free(BIO *a); + void BIO_vfree(BIO *a); + void BIO_free_all(BIO *a); + +=head1 DESCRIPTION + +The BIO_new() function returns a new BIO using method B<type>. + +BIO_set() sets the method of an already existing BIO. + +BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO +but it does not return a value. Calling BIO_free() may also have some effect +on the underlying I/O structure, for example it may close the file being +referred to under certain circumstances. For more details see the individual +BIO_METHOD descriptions. + +BIO_free_all() frees up an entire BIO chain, it does not halt if an error +occurs freeing up an individual BIO in the chain. + +=head1 RETURN VALUES + +BIO_new() returns a newly created BIO or NULL if the call fails. + +BIO_set(), BIO_free() return 1 for success and 0 for failure. + +BIO_free_all() and BIO_vfree() do not return values. + +=head1 NOTES + +Some BIOs (such as memory BIOs) can be used immediately after calling +BIO_new(). Others (such as file BIOs) need some additional initialization, +and frequently a utility function exists to create and initialize such BIOs. + +If BIO_free() is called on a BIO chain it will only free one BIO resulting +in a memory leak. + +Calling BIO_free_all() a single BIO has the same effect as calling BIO_free() +on it other than the discarded return value. + +Normally the B<type> argument is supplied by a function which returns a +pointer to a BIO_METHOD. There is a naming convention for such functions: +a source/sink BIO is normally called BIO_s_*() and a filter BIO +BIO_f_*(); + +=head1 EXAMPLE + +Create a memory BIO: + + BIO *mem = BIO_new(BIO_s_mem()); + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_new_bio_pair.pod b/crypto/openssl/doc/crypto/BIO_new_bio_pair.pod new file mode 100644 index 0000000..2256ba9 --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_new_bio_pair.pod @@ -0,0 +1,102 @@ +=pod + +=head1 NAME + +BIO_new_bio_pair - create a new BIO pair + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); + +=head1 DESCRIPTION + +BIO_new_bio_pair() creates a buffering BIO pair. It has two endpoints between +data can be buffered. Its typical use is to connect one endpoint as underlying +input/output BIO to an SSL and access the other one controlled by the program +instead of accessing the network connection directly. + +The two new BIOs B<bio1> and B<bio2> are symmetric with respect to their +functionality. The size of their buffers is determined by B<writebuf1> and +B<writebuf2>. If the size give is 0, the default size is used. + +BIO_new_bio_pair() does not check whether B<bio1> or B<bio2> do point to +some other BIO, the values are overwritten, BIO_free() is not called. + +The two BIOs, even though forming a BIO pair and must be BIO_free()'ed +separately. This can be of importance, as some SSL-functions like SSL_set_bio() +or SSL_free() call BIO_free() implicitly, so that the peer-BIO is left +untouched and must also be BIO_free()'ed. + +=head1 EXAMPLE + +The BIO pair can be used to have full control over the network access of an +application. The application can call select() on the socket as required +without having to go through the SSL-interface. + + BIO *internal_bio, *network_bio; + ... + BIO_new_bio_pair(internal_bio, 0, network_bio, 0); + SSL_set_bio(ssl, internal_bio); + SSL_operations(); + ... + + application | TLS-engine + | | + +----------> SSL_operations() + | /\ || + | || \/ + | BIO-pair (internal_bio) + +----------< BIO-pair (network_bio) + | | + socket | + + ... + SSL_free(ssl); /* implicitly frees internal_bio */ + BIO_free(network_bio); + ... + +As the BIO pair will only buffer the data and never directly access the +connection, it behaves non-blocking and will return as soon as the write +buffer is full or the read buffer is drained. Then the application has to +flush the write buffer and/or fill the read buffer. + +Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO +and must be transfered to the network. Use BIO_ctrl_get_read_request() to +find out, how many bytes must be written into the buffer before the +SSL_operation() can successfully be continued. + +=head1 IMPORTANT + +As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ +condition, but there is still data in the write buffer. An application must +not rely on the error value of SSL_operation() but must assure that the +write buffer is always flushed first. Otherwise a deadlock may occur as +the peer might be waiting for the data before being able to continue. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 1 + +The BIO pair was created successfully. The new BIOs are available in +B<bio1> and B<bio2>. + +=item 0 + +The operation failed. The NULL pointer is stored into the locations for +B<bio1> and B<bio2>. Check the error stack for more information. + +=back + +=head1 SEE ALSO + +L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, +L<BIO_ctrl_pending(3)|BIO_ctrl_pending(3)>, +L<BIO_ctrl_get_read_request(3)|BIO_ctrl_get_read_request(3)> + +=cut diff --git a/crypto/openssl/doc/crypto/BIO_push.pod b/crypto/openssl/doc/crypto/BIO_push.pod new file mode 100644 index 0000000..8af1d3c --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_push.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + +BIO_push, BIO_pop - add and remove BIOs from a chain. + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO * BIO_push(BIO *b,BIO *append); + BIO * BIO_pop(BIO *b); + +=head1 DESCRIPTION + +The BIO_push() function appends the BIO B<append> to B<b>, it returns +B<b>. + +BIO_pop() removes the BIO B<b> from a chain and returns the next BIO +in the chain, or NULL if there is no next BIO. The removed BIO then +becomes a single BIO with no association with the original chain, +it can thus be freed or attached to a different chain. + +=head1 NOTES + +The names of these functions are perhaps a little misleading. BIO_push() +joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain, +the deleted BIO does not need to be at the end of a chain. + +The process of calling BIO_push() and BIO_pop() on a BIO may have additional +consequences (a control call is made to the affected BIOs) any effects will +be noted in the descriptions of individual BIOs. + +=head1 EXAMPLES + +For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is +a base64 BIO and B<f> is a file BIO. + +If the call: + + BIO_push(b64, f); + +is made then the new chain will be B<b64-chain>. After making the calls + + BIO_push(md2, b64); + BIO_push(md1, md2); + +the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested +by B<md1> and B<md2>, B<base64> encoded and written to B<f>. + +It should be noted that reading causes data to pass in the reverse +direction, that is data is read from B<f>, base64 B<decoded> and digested +by B<md1> and B<md2>. If the call: + + BIO_pop(md2); + +The call will return B<b64> and the new chain will be B<md1-b64-f> data can +be written to B<md1> as before. + +=head1 RETURN VALUES + +BIO_push() returns the end of the chain, B<b>. + +BIO_pop() returns the next BIO in the chain, or NULL if there is no next +BIO. + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_read.pod b/crypto/openssl/doc/crypto/BIO_read.pod new file mode 100644 index 0000000..b345281 --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_read.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + int BIO_read(BIO *b, void *buf, int len); + int BIO_gets(BIO *b,char *buf, int size); + int BIO_write(BIO *b, const void *buf, int len); + int BIO_puts(BIO *b,const char *buf); + +=head1 DESCRIPTION + +BIO_read() attempts to read B<len> bytes from BIO B<b> and places +the data in B<buf>. + +BIO_gets() performs the BIOs "gets" operation and places the data +in B<buf>. Usually this operation will attempt to read a line of data +from the BIO of maximum length B<len>. There are exceptions to this +however, for example BIO_gets() on a digest BIO will calculate and +return the digest and other BIOs may not support BIO_gets() at all. + +BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>. + +BIO_puts() attempts to write a null terminated string B<buf> to BIO B<b> + +=head1 RETURN VALUES + +All these functions return either the amount of data successfully read or +written (if the return value is positive) or that no data was successfully +read or written if the result is 0 or -1. If the return value is -2 then +the operation is not implemented in the specific BIO type. + +=head1 NOTES + +A 0 or -1 return is not necessarily an indication of an error. In +particular when the source/sink is non-blocking or of a certain type +it may merely be an indication that no data is currently available and that +the application should retry the operation later. + +One technique sometimes used with blocking sockets is to use a system call +(such as select(), poll() or equivalent) to determine when data is available +and then call read() to read the data. The equivalent with BIOs (that is call +select() on the underlying I/O structure and then call BIO_read() to +read the data) should B<not> be used because a single call to BIO_read() +can cause several reads (and writes in the case of SSL BIOs) on the underlying +I/O structure and may block as a result. Instead select() (or equivalent) +should be combined with non blocking I/O so successive reads will request +a retry instead of blocking. + +See L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to +determine the cause of a retry and other I/O issues. + +If the BIO_gets() function is not supported by a BIO then it possible to +work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)> +to the chain. + +=head1 SEE ALSO + +L<BIO_should_retry(3)|BIO_should_retry(3)> + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_s_accept.pod b/crypto/openssl/doc/crypto/BIO_s_accept.pod new file mode 100644 index 0000000..c49da7f --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_s_accept.pod @@ -0,0 +1,184 @@ +=pod + +=head1 NAME + +BIO_s_accept, BIO_set_nbio, BIO_set_accept_port, BIO_get_accept_port, +BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode, +BIO_get_bind_mode, BIO_do_accept - accept BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO_METHOD * BIO_s_accept(void); + + #define BIO_set_accept_port(b,name) BIO_ctrl(b,BIO_C_SET_ACCEPT,0,(char *)name) + #define BIO_get_accept_port(b) BIO_ptr_ctrl(b,BIO_C_GET_ACCEPT,0) + + BIO *BIO_new_accept(char *host_port); + + #define BIO_set_nbio_accept(b,n) BIO_ctrl(b,BIO_C_SET_ACCEPT,1,(n)?"a":NULL) + #define BIO_set_accept_bios(b,bio) BIO_ctrl(b,BIO_C_SET_ACCEPT,2,(char *)bio) + + #define BIO_set_bind_mode(b,mode) BIO_ctrl(b,BIO_C_SET_BIND_MODE,mode,NULL) + #define BIO_get_bind_mode(b,mode) BIO_ctrl(b,BIO_C_GET_BIND_MODE,0,NULL) + + #define BIO_BIND_NORMAL 0 + #define BIO_BIND_REUSEADDR_IF_UNUSED 1 + #define BIO_BIND_REUSEADDR 2 + + #define BIO_do_accept(b) BIO_do_handshake(b) + +=head1 DESCRIPTION + +BIO_s_accept() returns the accept BIO method. This is a wrapper +round the platform's TCP/IP socket accept routines. + +Using accept BIOs TCP/IP connections can be accepted and data +transferred using only BIO routines. In this way any platform +specific operations are hidden by the BIO abstraction. + +Read and write operations on an accept BIO will perform I/O +on the underlying connection. If no connection is established +and the port (see below) is set up properly then the BIO +waits for an incoming connection. + +Accept BIOs support BIO_puts() but not BIO_gets(). + +If the close flag is set on an accept BIO then any active +connection on that chain is shutdown and the socket closed when +the BIO is freed. + +Calling BIO_reset() on a accept BIO will close any active +connection and reset the BIO into a state where it awaits another +incoming connection. + +BIO_get_fd() and BIO_set_fd() can be called to retrieve or set +the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)> + +BIO_set_accept_port() uses the string B<name> to set the accept +port. The port is represented as a string of the form "host:port", +where "host" is the interface to use and "port" is the port. +Either or both values can be "*" which is interpreted as meaning +any interface or port respectively. "port" has the same syntax +as the port specified in BIO_set_conn_port() for connect BIOs, +that is it can be a numerical port string or a string to lookup +using getservbyname() and a string table. + +BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into +a single call: that is it creates a new accept BIO with port +B<host_port>. + +BIO_set_nbio_accept() sets the accept socket to blocking mode +(the default) if B<n> is 0 or non blocking mode if B<n> is 1. + +BIO_set_accept_bios() can be used to set a chain of BIOs which +will be duplicated and prepended to the chain when an incoming +connection is received. This is useful if, for example, a +buffering or SSL BIO is required for each connection. The +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 +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 +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. + +BIO_do_accept() serves two functions. When it is first +called, after the accept BIO has been setup, it will attempt +to create the accept socket and bind an address to it. Second +and subsequent calls to BIO_do_accept() will await an incoming +connection. + +=head1 NOTES + +When an accept BIO is at the end of a chain it will await an +incoming connection before processing I/O calls. When an accept +BIO is not at then end of a chain it passes I/O calls to the next +BIO in the chain. + +When a connection is established a new socket BIO is created for +the connection and appended to the chain. That is the chain is now +accept->socket. This effectively means that attempting I/O on +an initial accept socket will await an incoming connection then +perform I/O on it. + +If any additional BIOs have been set using BIO_set_accept_bios() +then they are placed between the socket and the accept BIO, +that is the chain will be accept->otherbios->socket. + +If a server wishes to process multiple connections (as is normally +the case) then the accept BIO must be made available for further +incoming connections. This can be done by waiting for a connection and +then calling: + + connection = BIO_pop(accept); + +After this call B<connection> will contain a BIO for the recently +established connection and B<accept> will now be a single BIO +again which can be used to await further incoming connections. +If no further connections will be accepted the B<accept> can +be freed using BIO_free(). + +If only a single connection will be processed it is possible to +perform I/O using the accept BIO itself. This is often undesirable +however because the accept BIO will still accept additional incoming +connections. This can be resolved by using BIO_pop() (see above) +and freeing up the accept BIO after the initial connection. + +=head1 RETURN VALUES + +TBA + +=head1 EXAMPLE + +This example accepts two connections on port 4444, sends messages +down each and finally closes both down. + + BIO *abio, *cbio, *cbio2; + ERR_load_crypto_strings(); + abio = BIO_new_accept("4444"); + + /* First call to BIO_accept() sets up accept BIO */ + if(BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error setting up accept\n"); + ERR_print_errors_fp(stderr); + exit(0); + } + + /* Wait for incoming connection */ + if(BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error accepting connection\n"); + ERR_print_errors_fp(stderr); + exit(0); + } + fprintf(stderr, "Connection 1 established\n"); + /* Retrieve BIO for connection */ + cbio = BIO_pop(abio); + BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n"); + fprintf(stderr, "Sent out data on connection 1\n"); + /* Wait for another connection */ + if(BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error accepting connection\n"); + ERR_print_errors_fp(stderr); + exit(0); + } + fprintf(stderr, "Connection 2 established\n"); + /* Close accept BIO to refuse further connections */ + cbio2 = BIO_pop(abio); + BIO_free(abio); + BIO_puts(cbio2, "Connection 2: Sending out Data on second\n"); + fprintf(stderr, "Sent out data on connection 2\n"); + + BIO_puts(cbio, "Connection 1: Second connection established\n"); + /* Close the two established connections */ + BIO_free(cbio); + BIO_free(cbio2); + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_s_bio.pod b/crypto/openssl/doc/crypto/BIO_s_bio.pod new file mode 100644 index 0000000..95ae802 --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_s_bio.pod @@ -0,0 +1,130 @@ +=pod + +=head1 NAME + +BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, +BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, +BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, +BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + 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) + + #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_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) + 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) + size_t BIO_ctrl_get_read_request(BIO *b); + + int BIO_ctrl_reset_read_request(BIO *b); + +=head1 DESCRIPTION + +BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink +BIOs where data written to either half of the pair is buffered and can be read from +the other half. Both halves must usually by handled by the same application thread +since no locking is done on the internal data structures. + +Since BIO chains typically end in a source/sink BIO it is possible to make this +one half of a BIO pair and have all the data processed by the chain under application +control. + +One typical use of BIO pairs is to place TLS/SSL I/O under application control, this +can be used when the application wishes to use a non standard transport for +TLS/SSL or the normal socket routines are inappropriate. + +Calls to BIO_read() will read data from the buffer or request a retry if no +data is available. + +Calls to BIO_write() will place data in the buffer or request a retry if the +buffer is full. + +The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to +determine the amount of pending data in the read or write buffer. + +BIO_reset() clears any data in the write buffer. + +BIO_make_bio_pair() joins two separate BIOs into a connected pair. + +BIO_destroy_pair() destroys the association between two connected BIOs. Freeing +up any half of the pair will automatically destroy the association. + +BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further +writes on BIO B<b> are allowed (they will return an error). Reads on the other +half of the pair will return any pending data or EOF when all pending data has +been read. + +BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>. +If the size is not initialized a default value is used. This is currently +17K, sufficient for a maximum size TLS record. + +BIO_get_write_buf_size() returns the size of the write buffer. + +BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and +BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2> +with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is +zero then the default size is used. + +BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum +length of data that can be currently written to the BIO. Writes larger than this +value will return a value from BIO_write() less than the amount requested or if the +buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function +whereas BIO_get_write_guarantee() is a macro. + +BIO_get_read_request() and BIO_ctrl_get_read_request() return the +amount of data requested, or the buffer size if it is less, if the +last read attempt at the other half of the BIO pair failed due to an +empty buffer. This can be used to determine how much data should be +written to the BIO so the next read will succeed: this is most useful +in TLS/SSL applications where the amount of data read is usually +meaningful rather than just a buffer size. After a successful read +this call will return zero. It also will return zero once new data +has been written satisfying the read request or part of it. +Note that BIO_get_read_request() never returns an amount larger +than that returned by BIO_get_write_guarantee(). + +BIO_ctrl_reset_read_request() can also be used to reset the value returned by +BIO_get_read_request() to zero. + +=head1 NOTES + +Both halves of a BIO pair should be freed. That is even if one half is implicit +freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed. + +When used in bidirectional applications (such as TLS/SSL) care should be taken to +flush any data in the write buffer. This can be done by calling BIO_pending() +on the other half of the pair and, if any data is pending, reading it and sending +it to the underlying transport. This must be done before any normal processing +(such as calling select() ) due to a request and BIO_should_read() being true. + +To see why this is important consider a case where a request is sent using +BIO_write() and a response read with BIO_read(), this can occur during an +TLS/SSL handshake for example. BIO_write() will succeed and place data in the write +buffer. BIO_read() will initially fail and BIO_should_read() will be true. If +the application then waits for data to be available on the underlying transport +before flushing the write buffer it will never succeed because the request was +never sent! + +=head1 EXAMPLE + +TBA + +=head1 SEE ALSO + +L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, +L<BIO_should_retry(3)|BIO_should_retry(3)>, L<BIO_read(3)|BIO_read(3)> + +=cut diff --git a/crypto/openssl/doc/crypto/BIO_s_connect.pod b/crypto/openssl/doc/crypto/BIO_s_connect.pod new file mode 100644 index 0000000..fe1aa67 --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_s_connect.pod @@ -0,0 +1,182 @@ +=pod + +=head1 NAME + +BIO_s_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_set_nbio, BIO_do_connect - connect BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO_METHOD * BIO_s_connect(void); + + #define BIO_set_conn_hostname(b,name) BIO_ctrl(b,BIO_C_SET_CONNECT,0,(char *)name) + #define BIO_set_conn_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,1,(char *)port) + #define BIO_set_conn_ip(b,ip) BIO_ctrl(b,BIO_C_SET_CONNECT,2,(char *)ip) + #define BIO_set_conn_int_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,3,(char *)port) + #define BIO_get_conn_hostname(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,0) + #define BIO_get_conn_port(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,1) + #define BIO_get_conn_ip(b,ip) BIO_ptr_ctrl(b,BIO_C_SET_CONNECT,2) + #define BIO_get_conn_int_port(b,port) BIO_int_ctrl(b,BIO_C_SET_CONNECT,3,port) + + #define BIO_set_nbio(b,n) BIO_ctrl(b,BIO_C_SET_NBIO,(n),NULL) + + #define BIO_do_connect(b) BIO_do_handshake(b) + +=head1 DESCRIPTION + +BIO_s_connect() returns the connect BIO method. This is a wrapper +round the platform's TCP/IP socket connection routines. + +Using connect BIOs TCP/IP connections can be made and data +transferred using only BIO routines. In this way any platform +specific operations are hidden by the BIO abstraction. + +Read and write operations on a connect BIO will perform I/O +on the underlying connection. If no connection is established +and the port and hostname (see below) is set up properly then +a connection is established first. + +Connect BIOs support BIO_puts() but not BIO_gets(). + +If the close flag is set on a connect BIO then any active +connection is shutdown and the socket closed when the BIO +is freed. + +Calling BIO_reset() on a connect BIO will close any active +connection and reset the BIO into a state where it can connect +to the same host again. + +BIO_get_fd() places the underlying 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_set_conn_hostname() uses the string B<name> to set the hostname +The hostname can be an IP address. The hostname can also include the +port in the form hostname:port . It is also acceptable to use the +form "hostname/any/other/path" or "hostname:port/any/other/path". + +BIO_set_conn_port() sets the port to B<port>. B<port> can be the +numerical form or a string such as "http". A string will be looked +up first using getservbyname() on the host platform but if that +fails a standard table of port names will be used. Currently the +list is http, telnet, socks, https, ssl, ftp, gopher and wais. + +BIO_set_conn_ip() sets the IP address to B<ip> using binary form, +that is four bytes specifying the IP address in big-endian form. + +BIO_set_conn_int_port() sets the port using B<port>. B<port> should +be of type (int *). + +BIO_get_conn_hostname() returns the hostname of the connect BIO or +NULL if the BIO is initialized but no hostname is set. +This return value is an internal pointer which should not be modified. + +BIO_get_conn_port() returns the port as a string. + +BIO_get_conn_ip() returns the IP address in binary form. + +BIO_get_conn_int_port() returns the port as an int. + +BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is +zero then blocking I/O is set. If B<n> is 1 then non blocking I/O +is set. Blocking I/O is the default. The call to BIO_set_nbio() +should be made before the connection is established because +non blocking I/O is set during the connect process. + +BIO_do_connect() attempts to connect the supplied BIO. It returns 1 +if the connection was established successfully. A zero or negative +value is returned if the connection could not be established, the +call BIO_should_retry() should be used for non blocking connect BIOs +to determine if the call should be retried. + +=head1 NOTES + +If blocking I/O is set then a non positive return value from any +I/O call is caused by an error condition, although a zero return +will normally mean that the connection was closed. + +If the port name is supplied as part of the host name then this will +override any value set with BIO_set_conn_port(). This may be undesirable +if the application does not wish to allow connection to arbitrary +ports. This can be avoided by checking for the presence of the ':' +character in the passed hostname and either indicating an error or +truncating the string at that point. + +The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(), +BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a +connection attempt is made. Before any connection attempt the values +returned are those set by the application itself. + +Applications do not have to call BIO_do_connect() but may wish to do +so to separate the connection process from other I/O processing. + +If non blocking I/O is set then retries will be requested as appropriate. + +It addition to BIO_should_read() and BIO_should_write() it is also +possible for BIO_should_io_special() to be true during the initial +connection process with the reason BIO_RR_CONNECT. If this is returned +then this is an indication that a connection attempt would block, +the application should then take appropriate action to wait until +the underlying socket has connected and retry the call. + +=head1 RETURN VALUES + +BIO_s_connect() returns the connect BIO method. + +BIO_get_fd() returns the socket or -1 if the BIO has not +been initialized. + +BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and +BIO_set_conn_int_port() always return 1. + +BIO_get_conn_hostname() returns the connected hostname or NULL is +none was set. + +BIO_get_conn_port() returns a string representing the connected +port or NULL if not set. + +BIO_get_conn_ip() returns a pointer to the connected IP address in +binary form or all zeros if not set. + +BIO_get_conn_int_port() returns the connected port or 0 if none was +set. + +BIO_set_nbio() always returns 1. + +BIO_do_connect() returns 1 if the connection was successfully +established and 0 or -1 if the connection failed. + +=head1 EXAMPLE + +This is example connects to a webserver on the local host and attempts +to retrieve a page and copy the result to standard output. + + + BIO *cbio, *out; + int len; + char tmpbuf[1024]; + ERR_load_crypto_strings(); + cbio = BIO_new_connect("localhost:http"); + out = BIO_new_fp(stdout, BIO_NOCLOSE); + if(BIO_do_connect(cbio) <= 0) { + fprintf(stderr, "Error connecting to server\n"); + ERR_print_errors_fp(stderr); + /* whatever ... */ + } + BIO_puts(cbio, "GET / HTTP/1.0\n\n"); + for(;;) { + len = BIO_read(cbio, tmpbuf, 1024); + if(len <= 0) break; + BIO_write(out, tmpbuf, len); + } + BIO_free(cbio); + BIO_free(out); + + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_s_fd.pod b/crypto/openssl/doc/crypto/BIO_s_fd.pod new file mode 100644 index 0000000..b1de1d1 --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_s_fd.pod @@ -0,0 +1,89 @@ +=pod + +=head1 NAME + +BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + 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) + + BIO *BIO_new_fd(int fd, int close_flag); + +=head1 DESCRIPTION + +BIO_s_fd() returns the file descriptor BIO method. This is a wrapper +round the platforms file descriptor routines such as read() and write(). + +BIO_read() and BIO_write() read or write the underlying descriptor. +BIO_puts() is supported but BIO_gets() is not. + +If the close flag is set then 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). + +BIO_seek() sets the file pointer to position B<ofs> from start of file +using lseek(fd, ofs, 0). + +BIO_tell() returns the current file position by calling lseek(fd, 0, 1). + +BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close +flag to B<c>. + +BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also +returns the file descriptor. If B<c> is not NULL it should be of type +(int *). + +BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>. + +=head1 NOTES + +The behaviour of BIO_read() and BIO_write() depends on the behavior of the +platforms read() and write() calls on the descriptor. If the underlying +file descriptor is in a non blocking mode then the BIO will behave in the +manner described in the L<BIO_read(3)|BIO_read(3)> and L<BIO_should_retry(3)|BIO_should_retry(3)> +manual pages. + +File descriptor BIOs should not be used for socket I/O. Use socket BIOs +instead. + +=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 +been initialized. + +BIO_new_fd() returns the newly allocated BIO or NULL is an error +occurred. + +=head1 EXAMPLE + +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); + +=head1 SEE ALSO + +L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>, +L<BIO_reset(3)|BIO_reset(3)>, L<BIO_read(3)|BIO_read(3)>, +L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>, +L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>, +L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)> diff --git a/crypto/openssl/doc/crypto/BIO_s_file.pod b/crypto/openssl/doc/crypto/BIO_s_file.pod new file mode 100644 index 0000000..b2a2926 --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_s_file.pod @@ -0,0 +1,144 @@ +=pod + +=head1 NAME + +BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp, +BIO_read_filename, BIO_write_filename, BIO_append_filename, +BIO_rw_filename - FILE bio + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO_METHOD * BIO_s_file(void); + BIO *BIO_new_file(const char *filename, const char *mode); + BIO *BIO_new_fp(FILE *stream, int flags); + + BIO_set_fp(BIO *b,FILE *fp, int flags); + BIO_get_fp(BIO *b,FILE **fpp); + + int BIO_read_filename(BIO *b, char *name) + int BIO_write_filename(BIO *b, char *name) + int BIO_append_filename(BIO *b, char *name) + int BIO_rw_filename(BIO *b, char *name) + +=head1 DESCRIPTION + +BIO_s_file() returns the BIO file method. As its name implies it +is a wrapper round the stdio FILE structure and it is a +source/sink BIO. + +Calls to BIO_read() and BIO_write() read and write data to the +underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs. + +BIO_flush() on a file BIO calls the fflush() function on the wrapped +stream. + +BIO_reset() attempts to change the file pointer to the start of file +using fseek(stream, 0, 0). + +BIO_seek() sets the file pointer to position B<ofs> from start of file +using fseek(stream, ofs, 0). + +BIO_eof() calls feof(). + +Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO +is freed. + +BIO_new_file() creates a new file BIO with mode B<mode> the meaning +of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE +flag is set on the returned BIO. + +BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be: +BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying +stream to text mode, default is binary: this only has any effect under +Win32). + +BIO_set_fp() set the fp of a file BIO to B<fp>. B<flags> has the same +meaning as in BIO_new_fp(), it is a macro. + +BIO_get_fp() retrieves the fp of a file BIO, it is a macro. + +BIO_seek() is a macro that sets the position pointer to B<offset> bytes +from the start of file. + +BIO_tell() returns the value of the position pointer. + +BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and +BIO_rw_filename() set the file BIO B<b> to use file B<name> for +reading, writing, append or read write respectively. + +=head1 NOTES + +When wrapping stdout, stdin or stderr the underlying stream should not +normally be closed so the BIO_NOCLOSE flag should be set. + +Because the file BIO calls the underlying stdio functions any quirks +in stdio behaviour will be mirrored by the corresponding BIO. + +=head1 EXAMPLES + +File BIO "hello world": + + BIO *bio_out; + bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); + BIO_printf(bio_out, "Hello World\n"); + +Alternative technique: + + BIO *bio_out; + bio_out = BIO_new(BIO_s_file()); + if(bio_out == NULL) /* Error ... */ + if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */ + BIO_printf(bio_out, "Hello World\n"); + +Write to a file: + + BIO *out; + out = BIO_new_file("filename.txt", "w"); + if(!out) /* Error occurred */ + BIO_printf(out, "Hello World\n"); + BIO_free(out); + +Alternative technique: + + BIO *out; + out = BIO_new(BIO_s_file()); + if(out == NULL) /* Error ... */ + if(!BIO_write_filename(out, "filename.txt")) /* Error ... */ + BIO_printf(out, "Hello World\n"); + BIO_free(out); + +=head1 RETURN VALUES + +BIO_s_file() returns the file BIO method. + +BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error +occurred. + +BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure +(although the current implementation never return 0). + +BIO_seek() returns the same value as the underlying fseek() function: +0 for success or -1 for failure. + +BIO_tell() returns the current file position. + +BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and +BIO_rw_filename() return 1 for success or 0 for failure. + +=head1 BUGS + +BIO_reset() and BIO_seek() are implemented using fseek() on the underlying +stream. The return value for fseek() is 0 for success or -1 if an error +occurred this differs from other types of BIO which will typically return +1 for success and a non positive value if an error occurred. + +=head1 SEE ALSO + +L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>, +L<BIO_reset(3)|BIO_reset(3)>, L<BIO_flush(3)|BIO_flush(3)>, +L<BIO_read(3)|BIO_read(3)>, +L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>, +L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>, +L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)> diff --git a/crypto/openssl/doc/crypto/BIO_s_mem.pod b/crypto/openssl/doc/crypto/BIO_s_mem.pod new file mode 100644 index 0000000..19648ac --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_s_mem.pod @@ -0,0 +1,115 @@ +=pod + +=head1 NAME + +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 + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO_METHOD * BIO_s_mem(void); + + BIO_set_mem_eof_return(BIO *b,int v) + long BIO_get_mem_data(BIO *b, char **pp) + BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c) + BIO_get_mem_ptr(BIO *b,BUF_MEM **pp) + + BIO *BIO_new_mem_buf(void *buf, int len); + +=head1 DESCRIPTION + +BIO_s_mem() return the memory BIO method function. + +A memory BIO is a source/sink BIO which uses memory for its I/O. Data +written to a memory BIO is stored in a BUF_MEM structure which is extended +as appropriate to accommodate the stored data. + +Any data written to a memory BIO can be recalled by reading from it. +Unless the memory BIO is read only any data read from it is deleted from +the BIO. + +Memory BIOs support BIO_gets() and BIO_puts(). + +If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying +BUF_MEM structure is also freed. + +Calling BIO_reset() on a read write memory BIO clears any data in it. On a +read only BIO it restores the BIO to its original state and the read only +data can be read again. + +BIO_eof() is true if no data is in the BIO. + +BIO_ctrl_pending() returns the number of bytes currently stored. + +BIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is +empty. If the B<v> is zero then an empty memory BIO will return EOF (that is +it will return zero and BIO_should_retry(b) will be false. If B<v> is non +zero then it will return B<v> when it is empty and it will set the read retry +flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal +positive return value B<v> should be set to a negative value, typically -1. + +BIO_get_mem_data() sets B<pp> to a pointer to the start of the memory BIOs data +and returns the total amount of data available. It is implemented as a macro. + +BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the +close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE. +It is a macro. + +BIO_get_mem_ptr() places the underlying BUF_MEM structure in B<pp>. It is +a macro. + +BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>, +if B<len> is -1 then the B<buf> is assumed to be null terminated and its +length is determined by B<strlen>. The BIO is set to a read only state and +as a result cannot be written to. This is useful when some data needs to be +made available from a static area of memory in the form of a BIO. The +supplied data is read directly from the supplied buffer: it is B<not> copied +first, so the supplied area of memory must be unchanged until the BIO is freed. + +=head1 NOTES + +Writes to memory BIOs will always succeed if memory is available: that is +their size can grow indefinitely. + +Every read from a read write memory BIO will remove the data just read with +an internal copy operation, if a BIO contains a lots of data and it is +read in small chunks the operation can be very slow. The use of a read only +memory BIO avoids this problem. If the BIO must be read write then adding +a buffering BIO to the chain will speed up the process. + +=head1 BUGS + +There should be an option to set the maximum size of a memory BIO. + +There should be a way to "rewind" a read write BIO without destroying +its contents. + +The copying operation should not occur after every small read of a large BIO +to improve efficiency. + +=head1 EXAMPLE + +Create a memory BIO and write some data to it: + + BIO *mem = BIO_new(BIO_s_mem()); + BIO_puts(mem, "Hello World\n"); + +Create a read only memory BIO: + + char data[] = "Hello World"; + BIO *mem; + mem = BIO_new_mem_buf(data, -1); + +Extract the BUF_MEM structure from a memory BIO and then free up the BIO: + + BUF_MEM *bptr; + BIO_get_mem_ptr(mem, &bptr); + BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */ + BIO_free(mem); + + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_s_null.pod b/crypto/openssl/doc/crypto/BIO_s_null.pod new file mode 100644 index 0000000..e5514f7 --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_s_null.pod @@ -0,0 +1,37 @@ +=pod + +=head1 NAME + +BIO_s_null - null data sink + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO_METHOD * BIO_s_null(void); + +=head1 DESCRIPTION + +BIO_s_null() returns the null sink BIO method. Data written to +the null sink is discarded, reads return EOF. + +=head1 NOTES + +A null sink BIO behaves in a similar manner to the Unix /dev/null +device. + +A null bio can be placed on the end of a chain to discard any data +passed through it. + +A null sink is useful if, for example, an application wishes to digest some +data by writing through a digest bio but not send the digested data anywhere. +Since a BIO chain must normally include a source/sink BIO this can be achieved +by adding a null sink BIO to the end of the chain + +=head1 RETURN VALUES + +BIO_s_null() returns the null sink BIO method. + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_s_socket.pod b/crypto/openssl/doc/crypto/BIO_s_socket.pod new file mode 100644 index 0000000..2531851 --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_s_socket.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +BIO_s_socket, BIO_new_socket - socket BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO_METHOD * BIO_s_socket(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) + + BIO *BIO_new_socket(int sock, int close_flag); + +=head1 DESCRIPTION + +BIO_s_socket() returns the socket BIO method. This is a wrapper +round the platform's socket routines. + +BIO_read() and BIO_write() read or write the underlying socket. +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<c>. + +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 + +Socket BIOs also support any relevant functionality of file descriptor +BIOs. + +The reason for having separate file descriptor and socket BIOs is that on some +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. + +=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. + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_set_callback.pod b/crypto/openssl/doc/crypto/BIO_set_callback.pod new file mode 100644 index 0000000..9b6961c --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_set_callback.pod @@ -0,0 +1,108 @@ +=pod + +=head1 NAME + +BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, +BIO_debug_callback - BIO callback functions + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + #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 callback(BIO *b, int oper, const char *argp, + int argi, long argl, long retvalue); + +=head1 DESCRIPTION + +BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback, +they are both macros. The callback is called during most high level BIO +operations. It can be used for debugging purposes to trace operations on +a BIO or to modify its operation. + +BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be +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 +to, otherwise stderr is used. + +callback() is the callback function itself. The meaning of each +argument is described below. + +The BIO the callback is attached to is passed in B<b>. + +B<oper> is set to the operation being performed. For some operations +the callback is called twice, once before and once after the actual +operation, the latter case has B<oper> or'ed with BIO_CB_RETURN. + +The meaning of the arguments B<argp>, B<argi> and B<argl> depends on +the value of B<oper>, that is the operation being performed. + +B<retvalue> 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 +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<retvalue> when it has +finished processing, unless if specifically wishes to modify the +value returned to the application. + +=head1 CALLBACK OPERATIONS + +=over 4 + +=item B<BIO_free(b)> + +callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the +free operation. + +=item B<BIO_read(b, out, outl)> + +callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before +the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue) +after. + +=item B<BIO_write(b, in, inl)> + +callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before +the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue) +after. + +=item B<BIO_gets(b, out, outl)> + +callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before +the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue) +after. + +=item B<BIO_puts(b, in)> + +callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before +the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue) +after. + +=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)> + +callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and +callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after. + +=back + +=head1 EXAMPLE + +The BIO_debug_callback() function is a good example, its source is +in crypto/bio/bio_cb.c + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BIO_should_retry.pod b/crypto/openssl/doc/crypto/BIO_should_retry.pod new file mode 100644 index 0000000..539c391 --- /dev/null +++ b/crypto/openssl/doc/crypto/BIO_should_retry.pod @@ -0,0 +1,114 @@ +=pod + +=head1 NAME + +BIO_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 retry functions + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + #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 + + BIO * BIO_get_retry_BIO(BIO *bio, int *reason); + int BIO_get_retry_reason(BIO *bio); + +=head1 DESCRIPTION + +These functions determine why a BIO is not able to read or write data. +They will typically be called after a failed BIO_read() or BIO_write() +call. + +BIO_should_retry() is true if the call that produced this condition +should then be retried at a later time. + +If BIO_should_retry() is false then the cause is an error condition. + +BIO_should_read() is true if the cause of the condition is that a BIO +needs to read data. + +BIO_should_write() is true if the cause of the condition is that a BIO +needs to read data. + +BIO_should_io_special() is true if some "special" condition, that is a +reason other than reading or writing is the cause of the condition. + +BIO_get_retry_reason() returns a mask of the cause of a retry condition +consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>, +B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of +these. + +BIO_get_retry_BIO() determines the precise reason for the special +condition, it returns the BIO that caused this condition and if +B<reason> is not NULL it contains the reason code. The meaning of +the reason code and the action that should be taken depends on +the type of BIO that resulted in this condition. + +BIO_get_retry_reason() returns the reason for a special condition if +passed the relevant BIO, for example as returned by BIO_get_retry_BIO(). + +=head1 NOTES + +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 +0 and BIO_should_retry() is false then the cause will be that the +connection closed. A similar condition on a file BIO will mean that it +has reached EOF. Some BIO types may place additional information on +the error queue. For more details see the individual BIO type manual +pages. + +If the underlying I/O structure is in a blocking mode almost all current +BIO types will not request a retry, because the underlying I/O +calls will not. If the application knows that the BIO type will never +signal a retry then it need not call BIO_should_retry() after a failed +BIO I/O call. This is typically done with file BIOs. + +SSL BIOs are the only current exception to this rule: they can request a +retry even if the underlying I/O structure is blocking, if a handshake +occurs during a call to BIO_read(). An application can retry the failed +call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY +on the underlying SSL structure. + +While an application may retry a failed non blocking call immediately +this is likely to be very inefficient because the call will fail +repeatedly until data can be processed or is available. An application +will normally wait until the necessary condition is satisfied. How +this is done depends on the underlying I/O structure. + +For example if the cause is ultimately a socket and BIO_should_read() +is true then a call to select() may be made to wait until data is +available and then retry the BIO operation. By combining the retry +conditions of several non blocking BIOs in a single select() call +it is possible to service several BIOs in a single thread, though +the performance may be poor if SSL BIOs are present because long delays +can occur during the initial handshake process. + +It is possible for a BIO to block indefinitely if the underlying I/O +structure cannot process or return any data. This depends on the behaviour of +the platforms I/O functions. This is often not desirable: one solution +is to use non blocking I/O and use a timeout on the select() (or +equivalent) call. + +=head1 BUGS + +The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O: +that is they cannot retry after a partial read or write. This is usually +worked around by only passing the relevant data to ASN1 functions when +the entire structure can be read or written. + +=head1 SEE ALSO + +TBA diff --git a/crypto/openssl/doc/crypto/BN_CTX_new.pod b/crypto/openssl/doc/crypto/BN_CTX_new.pod new file mode 100644 index 0000000..c94d8c6 --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_CTX_new.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BN_CTX *BN_CTX_new(void); + + void BN_CTX_init(BN_CTX *c); + + void BN_CTX_free(BN_CTX *c); + +=head1 DESCRIPTION + +A B<BN_CTX> is a structure that holds B<BIGNUM> temporary variables used by +library functions. Since dynamic memory allocation to create B<BIGNUM>s +is rather expensive when used in conjunction with repeated subroutine +calls, the B<BN_CTX> structure is used. + +BN_CTX_new() allocates and initializes a B<BN_CTX> +structure. BN_CTX_init() initializes an existing uninitialized +B<BN_CTX>. + +BN_CTX_free() frees the components of the B<BN_CTX>, and if it was +created by BN_CTX_new(), also the structure itself. +If L<BN_CTX_start(3)|BN_CTX_start(3)> has been used on the B<BN_CTX>, +L<BN_CTX_end(3)|BN_CTX_end(3)> must be called before the B<BN_CTX> +may be freed by BN_CTX_free(). + + +=head1 RETURN VALUES + +BN_CTX_new() returns a pointer to the B<BN_CTX>. If the allocation fails, +it returns B<NULL> and sets an error code that can be obtained by +L<ERR_get_error(3)|ERR_get_error(3)>. + +BN_CTX_init() and BN_CTX_free() have no return values. + +=head1 SEE ALSO + +L<bn(3)|bn(3)>, L<err(3)|err(3)>, L<BN_add(3)|BN_add(3)>, +L<BN_CTX_start(3)|BN_CTX_start(3)> + +=head1 HISTORY + +BN_CTX_new() and BN_CTX_free() are available in all versions on SSLeay +and OpenSSL. BN_CTX_init() was added in SSLeay 0.9.1b. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_CTX_start.pod b/crypto/openssl/doc/crypto/BN_CTX_start.pod new file mode 100644 index 0000000..dfcefe1 --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_CTX_start.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + void BN_CTX_start(BN_CTX *ctx); + + BIGNUM *BN_CTX_get(BN_CTX *ctx); + + void BN_CTX_end(BN_CTX *ctx); + +=head1 DESCRIPTION + +These functions are used to obtain temporary B<BIGNUM> variables from +a B<BN_CTX> (which can been created by using L<BN_CTX_new(3)|BN_CTX_new(3)>) +in order to save the overhead of repeatedly creating and +freeing B<BIGNUM>s in functions that are called from inside a loop. + +A function must call BN_CTX_start() first. Then, BN_CTX_get() may be +called repeatedly to obtain temporary B<BIGNUM>s. All BN_CTX_get() +calls must be made before calling any other functions that use the +B<ctx> as an argument. + +Finally, BN_CTX_end() must be called before returning from the function. +When BN_CTX_end() is called, the B<BIGNUM> pointers obtained from +BN_CTX_get() become invalid. + +=head1 RETURN VALUES + +BN_CTX_start() and BN_CTX_end() return no values. + +BN_CTX_get() returns a pointer to the B<BIGNUM>, or B<NULL> on error. +Once BN_CTX_get() has failed, the subsequent calls will return B<NULL> +as well, so it is sufficient to check the return value of the last +BN_CTX_get() call. In case of an error, an error code is set, which +can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + + +=head1 SEE ALSO + +L<BN_CTX_new(3)|BN_CTX_new(3)> + +=head1 HISTORY + +BN_CTX_start(), BN_CTX_get() and BN_CTX_end() were added in OpenSSL 0.9.5. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_add.pod b/crypto/openssl/doc/crypto/BN_add.pod new file mode 100644 index 0000000..0541d45 --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_add.pod @@ -0,0 +1,99 @@ +=pod + +=head1 NAME + +BN_add, BN_sub, BN_mul, BN_div, BN_sqr, BN_mod, BN_mod_mul, BN_exp, +BN_mod_exp, BN_gcd - arithmetic operations on BIGNUMs + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); + + int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); + + int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); + + int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d, + BN_CTX *ctx); + + int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); + + int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); + + int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, + BN_CTX *ctx); + + int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx); + + int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx); + + int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); + +=head1 DESCRIPTION + +BN_add() adds B<a> and B<b> and places the result in B<r> (C<r=a+b>). +B<r> may be the same B<BIGNUM> as B<a> or B<b>. + +BN_sub() subtracts B<b> from B<a> and places the result in B<r> (C<r=a-b>). + +BN_mul() multiplies B<a> and B<b> and places the result in B<r> (C<r=a*b>). +B<r> may be the same B<BIGNUM> as B<a> or B<b>. +For multiplication by powers of 2, use L<BN_lshift(3)|BN_lshift(3)>. + +BN_div() divides B<a> by B<d> and places the result in B<dv> and the +remainder in B<rem> (C<dv=a/d, rem=a%d>). Either of B<dv> and B<rem> may +be NULL, in which case the respective value is not returned. +For division by powers of 2, use BN_rshift(3). + +BN_sqr() takes the square of B<a> and places the result in B<r> +(C<r=a^2>). B<r> and B<a> may be the same B<BIGNUM>. +This function is faster than BN_mul(r,a,a). + +BN_mod() find the remainder of B<a> divided by B<m> and places it in +B<rem> (C<rem=a%m>). + +BN_mod_mul() multiplies B<a> by B<b> and finds the remainder when +divided by B<m> (C<r=(a*b)%m>). B<r> may be the same B<BIGNUM> as B<a> +or B<b>. For a more efficient algorithm, see +L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>; for repeated +computations using the same modulus, see L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>. + +BN_exp() raises B<a> to the B<p>-th power and places the result in B<r> +(C<r=a^p>). This function is faster than repeated applications of +BN_mul(). + +BN_mod_exp() computes B<a> to the B<p>-th power modulo B<m> (C<r=a^p % +m>). This function uses less time and space than BN_exp(). + +BN_gcd() computes the greatest common divisor of B<a> and B<b> and +places the result in B<r>. B<r> may be the same B<BIGNUM> as B<a> or +B<b>. + +For all functions, B<ctx> is a previously allocated B<BN_CTX> used for +temporary variables; see L<BN_CTX_new(3)|BN_CTX_new(3)>. + +Unless noted otherwise, the result B<BIGNUM> must be different from +the arguments. + +=head1 RETURN VALUES + +For all functions, 1 is returned for success, 0 on error. The return +value should always be checked (e.g., C<if (!BN_add(r,a,b)) goto err;>). +The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<bn(3)|bn(3)>, L<err(3)|err(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>, +L<BN_add_word(3)|BN_add_word(3)>, L<BN_set_bit(3)|BN_set_bit(3)> + +=head1 HISTORY + +BN_add(), BN_sub(), BN_div(), BN_sqr(), BN_mod(), BN_mod_mul(), +BN_mod_exp() and BN_gcd() are available in all versions of SSLeay and +OpenSSL. The B<ctx> argument to BN_mul() was added in SSLeay +0.9.1b. BN_exp() appeared in SSLeay 0.9.0. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_add_word.pod b/crypto/openssl/doc/crypto/BN_add_word.pod new file mode 100644 index 0000000..66bedfb --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_add_word.pod @@ -0,0 +1,57 @@ +=pod + +=head1 NAME + +BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word - arithmetic +functions on BIGNUMs with integers + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_add_word(BIGNUM *a, BN_ULONG w); + + int BN_sub_word(BIGNUM *a, BN_ULONG w); + + int BN_mul_word(BIGNUM *a, BN_ULONG w); + + BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w); + + BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w); + +=head1 DESCRIPTION + +These functions perform arithmetic operations on BIGNUMs with unsigned +integers. They are much more efficient than the normal BIGNUM +arithmetic operations. + +BN_add_word() adds B<w> to B<a> (C<a+=w>). + +BN_sub_word() subtracts B<w> from B<a> (C<a-=w>). + +BN_mul_word() multiplies B<a> and B<w> (C<a*=b>). + +BN_div_word() divides B<a> by B<w> (C<a/=w>) and returns the remainder. + +BN_mod_word() returns the remainder of B<a> divided by B<w> (C<a%m>). + +For BN_div_word() and BN_mod_word(), B<w> must not be 0. + +=head1 RETURN VALUES + +BN_add_word(), BN_sub_word() and BN_mul_word() return 1 for success, 0 +on error. The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +BN_mod_word() and BN_div_word() return B<a>%B<w>. + +=head1 SEE ALSO + +L<bn(3)|bn(3)>, L<err(3)|err(3)>, L<BN_add(3)|BN_add(3)> + +=head1 HISTORY + +BN_add_word() and BN_mod_word() are available in all versions of +SSLeay and OpenSSL. BN_div_word() was added in SSLeay 0.8, and +BN_sub_word() and BN_mul_word() in SSLeay 0.9.0. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_bn2bin.pod b/crypto/openssl/doc/crypto/BN_bn2bin.pod new file mode 100644 index 0000000..c12af9c --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_bn2bin.pod @@ -0,0 +1,95 @@ +=pod + +=head1 NAME + +BN_bn2bin, BN_bin2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn, +BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn - format conversions + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_bn2bin(const BIGNUM *a, unsigned char *to); + BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret); + + char *BN_bn2hex(const BIGNUM *a); + char *BN_bn2dec(const BIGNUM *a); + int BN_hex2bn(BIGNUM **a, const char *str); + int BN_dec2bn(BIGNUM **a, const char *str); + + int BN_print(BIO *fp, const BIGNUM *a); + int BN_print_fp(FILE *fp, const BIGNUM *a); + + int BN_bn2mpi(const BIGNUM *a, unsigned char *to); + BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret); + +=head1 DESCRIPTION + +BN_bn2bin() converts the absolute value of B<a> into big-endian form +and stores it at B<to>. B<to> must point to BN_num_bytes(B<a>) bytes of +memory. + +BN_bin2bn() converts the positive integer in big-endian form of length +B<len> at B<s> into a B<BIGNUM> and places it in B<ret>. If B<ret> is +NULL, a new B<BIGNUM> is created. + +BN_bn2hex() and BN_bn2dec() return printable strings containing the +hexadecimal and decimal encoding of B<a> respectively. For negative +numbers, the string is prefaced with a leading '-'. The string must be +freed later using OPENSSL_free(). + +BN_hex2bn() converts the string B<str> containing a hexadecimal number +to a B<BIGNUM> and stores it in **B<bn>. If *B<bn> is NULL, a new +B<BIGNUM> is created. If B<bn> is NULL, it only computes the number's +length in hexadecimal digits. If the string starts with '-', the +number is negative. BN_dec2bn() is the same using the decimal system. + +BN_print() and BN_print_fp() write the hexadecimal encoding of B<a>, +with a leading '-' for negative numbers, to the B<BIO> or B<FILE> +B<fp>. + +BN_bn2mpi() and BN_mpi2bn() convert B<BIGNUM>s from and to a format +that consists of the number's length in bytes represented as a 3-byte +big-endian number, and the number itself in big-endian format, where +the most significant bit signals a negative number (the representation +of numbers with the MSB set is prefixed with null byte). + +BN_bn2mpi() stores the representation of B<a> at B<to>, where B<to> +must be large enough to hold the result. The size can be determined by +calling BN_bn2mpi(B<a>, NULL). + +BN_mpi2bn() converts the B<len> bytes long representation at B<s> to +a B<BIGNUM> and stores it at B<ret>, or in a newly allocated B<BIGNUM> +if B<ret> is NULL. + +=head1 RETURN VALUES + +BN_bn2bin() returns the length of the big-endian number placed at B<to>. +BN_bin2bn() returns the B<BIGNUM>, NULL on error. + +BN_bn2hex() and BN_bn2dec() return a null-terminated string, or NULL +on error. BN_hex2bn() and BN_dec2bn() return the number's length in +hexadecimal or decimal digits, and 0 on error. + +BN_print_fp() and BN_print() return 1 on success, 0 on write errors. + +BN_bn2mpi() returns the length of the representation. BN_mpi2bn() +returns the B<BIGNUM>, and NULL on error. + +The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<bn(3)|bn(3)>, L<err(3)|err(3)>, L<BN_zero(3)|BN_zero(3)>, +L<ASN1_INTEGER_to_BN(3)|ASN1_INTEGER_to_BN(3)>, +L<BN_num_bytes(3)|BN_num_bytes(3)> + +=head1 HISTORY + +BN_bn2bin(), BN_bin2bn(), BN_print_fp() and BN_print() are available +in all versions of SSLeay and OpenSSL. + +BN_bn2hex(), BN_bn2dec(), BN_hex2bn(), BN_dec2bn(), BN_bn2mpi() and +BN_mpi2bn() were added in SSLeay 0.9.0. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_cmp.pod b/crypto/openssl/doc/crypto/BN_cmp.pod new file mode 100644 index 0000000..23e9ed0 --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_cmp.pod @@ -0,0 +1,48 @@ +=pod + +=head1 NAME + +BN_cmp, BN_ucmp, BN_is_zero, BN_is_one, BN_is_word, BN_is_odd - BIGNUM comparison and test functions + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_cmp(BIGNUM *a, BIGNUM *b); + int BN_ucmp(BIGNUM *a, BIGNUM *b); + + int BN_is_zero(BIGNUM *a); + int BN_is_one(BIGNUM *a); + int BN_is_word(BIGNUM *a, BN_ULONG w); + int BN_is_odd(BIGNUM *a); + +=head1 DESCRIPTION + +BN_cmp() compares the numbers B<a> and B<b>. BN_ucmp() compares their +absolute values. + +BN_is_zero(), BN_is_one() and BN_is_word() test if B<a> equals 0, 1, +or B<w> respectively. BN_is_odd() tests if a is odd. + +BN_is_zero(), BN_is_one(), BN_is_word() and BN_is_odd() are macros. + +=head1 RETURN VALUES + +BN_cmp() returns -1 if B<a> E<lt> B<b>, 0 if B<a> == B<b> and 1 if +B<a> E<gt> B<b>. BN_ucmp() is the same using the absolute values +of B<a> and B<b>. + +BN_is_zero(), BN_is_one() BN_is_word() and BN_is_odd() return 1 if +the condition is true, 0 otherwise. + +=head1 SEE ALSO + +L<bn(3)|bn(3)> + +=head1 HISTORY + +BN_cmp(), BN_ucmp(), BN_is_zero(), BN_is_one() and BN_is_word() are +available in all versions of SSLeay and OpenSSL. +BN_is_odd() was added in SSLeay 0.8. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_copy.pod b/crypto/openssl/doc/crypto/BN_copy.pod new file mode 100644 index 0000000..8ad25e7 --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_copy.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +BN_copy, BN_dup - copy BIGNUMs + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from); + + BIGNUM *BN_dup(const BIGNUM *from); + +=head1 DESCRIPTION + +BN_copy() copies B<from> to B<to>. BN_dup() creates a new B<BIGNUM> +containing the value B<from>. + +=head1 RETURN VALUES + +BN_copy() returns B<to> on success, NULL on error. BN_dup() returns +the new B<BIGNUM>, and NULL on error. The error codes can be obtained +by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<bn(3)|bn(3)>, L<err(3)|err(3)> + +=head1 HISTORY + +BN_copy() and BN_dup() are available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_generate_prime.pod b/crypto/openssl/doc/crypto/BN_generate_prime.pod new file mode 100644 index 0000000..638f651 --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_generate_prime.pod @@ -0,0 +1,102 @@ +=pod + +=head1 NAME + +BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test for primality + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add, + BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); + + int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int, + void *), BN_CTX *ctx, void *cb_arg); + + int BN_is_prime_fasttest(const BIGNUM *a, int checks, + void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg, + int do_trial_division); + +=head1 DESCRIPTION + +BN_generate_prime() generates a pseudo-random prime number of B<num> +bits. +If B<ret> is not B<NULL>, it will be used to store the number. + +If B<callback> is not B<NULL>, it is called as follows: + +=over 4 + +=item * + +B<callback(0, i, cb_arg)> is called after generating the i-th +potential prime number. + +=item * + +While the number is being tested for primality, B<callback(1, j, +cb_arg)> is called as described below. + +=item * + +When a prime has been found, B<callback(2, i, cb_arg)> is called. + +=back + +The prime may have to fulfill additional requirements for use in +Diffie-Hellman key exchange: + +If B<add> is not B<NULL>, the prime will fulfill the condition p % B<add> +== B<rem> (p % B<add> == 1 if B<rem> == B<NULL>) in order to suit a given +generator. + +If B<safe> is true, it will be a safe prime (i.e. a prime p so +that (p-1)/2 is also prime). + +The PRNG must be seeded prior to calling BN_generate_prime(). +The prime number generation has a negligible error probability. + +BN_is_prime() and BN_is_prime_fasttest() test if the number B<a> is +prime. The following tests are performed until one of them shows that +B<a> is composite; if B<a> passes all these tests, it is considered +prime. + +BN_is_prime_fasttest(), when called with B<do_trial_division == 1>, +first attempts trial division by a number of small primes; +if no divisors are found by this test and B<callback> is not B<NULL>, +B<callback(1, -1, cb_arg)> is called. +If B<do_trial_division == 0>, this test is skipped. + +Both BN_is_prime() and BN_is_prime_fasttest() perform a Miller-Rabin +probabilistic primality test with B<checks> iterations. If +B<checks == BN_prime_check>, a number of iterations is used that +yields a false positive rate of at most 2^-80 for random input. + +If B<callback> is not B<NULL>, B<callback(1, j, cb_arg)> is called +after the j-th iteration (j = 0, 1, ...). B<ctx> is a +pre-allocated B<BN_CTX> (to save the overhead of allocating and +freeing the structure in a loop), or B<NULL>. + +=head1 RETURN VALUES + +BN_generate_prime() returns the prime number on success, B<NULL> otherwise. + +BN_is_prime() returns 0 if the number is composite, 1 if it is +prime with an error probability of less than 0.25^B<checks>, and +-1 on error. + +The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<bn(3)|bn(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)> + +=head1 HISTORY + +The B<cb_arg> arguments to BN_generate_prime() and to BN_is_prime() +were added in SSLeay 0.9.0. The B<ret> argument to BN_generate_prime() +was added in SSLeay 0.9.1. +BN_is_prime_fasttest() was added in OpenSSL 0.9.5. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_mod_inverse.pod b/crypto/openssl/doc/crypto/BN_mod_inverse.pod new file mode 100644 index 0000000..49e62da --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_mod_inverse.pod @@ -0,0 +1,36 @@ +=pod + +=head1 NAME + +BN_mod_inverse - compute inverse modulo n + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n, + BN_CTX *ctx); + +=head1 DESCRIPTION + +BN_mod_inverse() computes the inverse of B<a> modulo B<n> +places the result in B<r> (C<(a*r)%n==1>). If B<r> is NULL, +a new B<BIGNUM> is created. + +B<ctx> is a previously allocated B<BN_CTX> used for temporary +variables. B<r> may be the same B<BIGNUM> as B<a> or B<n>. + +=head1 RETURN VALUES + +BN_mod_inverse() returns the B<BIGNUM> containing the inverse, and +NULL on error. The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<bn(3)|bn(3)>, L<err(3)|err(3)>, L<BN_add(3)|BN_add(3)> + +=head1 HISTORY + +BN_mod_inverse() is available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_mod_mul_montgomery.pod b/crypto/openssl/doc/crypto/BN_mod_mul_montgomery.pod new file mode 100644 index 0000000..0b8ab51 --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_mod_mul_montgomery.pod @@ -0,0 +1,95 @@ +=pod + +=head1 NAME + +BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_init, +BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy, +BN_from_montgomery, BN_to_montgomery - Montgomery multiplication + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BN_MONT_CTX *BN_MONT_CTX_new(void); + void BN_MONT_CTX_init(BN_MONT_CTX *ctx); + void BN_MONT_CTX_free(BN_MONT_CTX *mont); + + int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); + BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from); + + int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b, + BN_MONT_CTX *mont, BN_CTX *ctx); + + int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, + BN_CTX *ctx); + + int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, + BN_CTX *ctx); + +=head1 DESCRIPTION + +These functions implement Montgomery multiplication. They are used +automatically when L<BN_mod_exp(3)|BN_mod_exp(3)> is called with suitable input, +but they may be useful when several operations are to be performed +using the same modulus. + +BN_MONT_CTX_new() allocates and initializes a B<BN_MONT_CTX> structure. +BN_MONT_CTX_init() initializes an existing uninitialized B<BN_MONT_CTX>. + +BN_MONT_CTX_set() sets up the B<mont> structure from the modulus B<m> +by precomputing its inverse and a value R. + +BN_MONT_CTX_copy() copies the B<BN_MONT_CTX> B<from> to B<to>. + +BN_MONT_CTX_free() frees the components of the B<BN_MONT_CTX>, and, if +it was created by BN_MONT_CTX_new(), also the structure itself. + +BN_mod_mul_montgomery() computes Mont(B<a>,B<b>):=B<a>*B<b>*R^-1 and places +the result in B<r>. + +BN_from_montgomery() performs the Montgomery reduction B<r> = B<a>*R^-1. + +BN_to_montgomery() computes Mont(B<a>,R^2), i.e. B<a>*R. + +For all functions, B<ctx> is a previously allocated B<BN_CTX> used for +temporary variables. + +The B<BN_MONT_CTX> structure is defined as follows: + + typedef struct bn_mont_ctx_st + { + int ri; /* number of bits in R */ + BIGNUM RR; /* R^2 (used to convert to Montgomery form) */ + BIGNUM N; /* The modulus */ + BIGNUM Ni; /* R*(1/R mod N) - N*Ni = 1 + * (Ni is only stored for bignum algorithm) */ + BN_ULONG n0; /* least significant word of Ni */ + int flags; + } BN_MONT_CTX; + +BN_to_montgomery() is a macro. + +=head1 RETURN VALUES + +BN_MONT_CTX_new() returns the newly allocated B<BN_MONT_CTX>, and NULL +on error. + +BN_MONT_CTX_init() and BN_MONT_CTX_free() have no return values. + +For the other functions, 1 is returned for success, 0 on error. +The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<bn(3)|bn(3)>, L<err(3)|err(3)>, L<BN_add(3)|BN_add(3)>, +L<BN_CTX_new(3)|BN_CTX_new(3)> + +=head1 HISTORY + +BN_MONT_CTX_new(), BN_MONT_CTX_free(), BN_MONT_CTX_set(), +BN_mod_mul_montgomery(), BN_from_montgomery() and BN_to_montgomery() +are available in all versions of SSLeay and OpenSSL. + +BN_MONT_CTX_init() and BN_MONT_CTX_copy() were added in SSLeay 0.9.1b. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_mod_mul_reciprocal.pod b/crypto/openssl/doc/crypto/BN_mod_mul_reciprocal.pod new file mode 100644 index 0000000..a28925f --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_mod_mul_reciprocal.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_init, +BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using +reciprocal + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BN_RECP_CTX *BN_RECP_CTX_new(void); + void BN_RECP_CTX_init(BN_RECP_CTX *recp); + void BN_RECP_CTX_free(BN_RECP_CTX *recp); + + int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx); + + int BN_div_recp(BIGNUM *dv, BIGNUM *rem, BIGNUM *a, BN_RECP_CTX *recp, + BN_CTX *ctx); + + int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b, + BN_RECP_CTX *recp, BN_CTX *ctx); + +=head1 DESCRIPTION + +BN_mod_mul_reciprocal() can be used to perform an efficient +L<BN_mod_mul(3)|BN_mod_mul(3)> operation when the operation will be performed +repeatedly with the same modulus. It computes B<r>=(B<a>*B<b>)%B<m> +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. + +BN_RECP_CTX_set() stores B<m> in B<recp> and sets it up for computing +1/B<m> and shifting it left by BN_num_bits(B<m>)+1 to make it an +integer. The result and the number of bits it was shifted left will +later be stored in B<recp>. + +BN_div_recp() divides B<a> by B<m> using B<recp>. It places the quotient +in B<dv> and the remainder in B<rem>. + +The B<BN_RECP_CTX> structure is defined as follows: + + typedef struct bn_recp_ctx_st + { + BIGNUM N; /* the divisor */ + BIGNUM Nr; /* the reciprocal */ + int num_bits; + int shift; + int flags; + } BN_RECP_CTX; + +It cannot be shared between threads. + +=head1 RETURN VALUES + +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. + +For the other functions, 1 is returned for success, 0 on error. +The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<bn(3)|bn(3)>, L<err(3)|err(3)>, L<BN_add(3)|BN_add(3)>, +L<BN_CTX_new(3)|BN_CTX_new(3)> + +=head1 HISTORY + +B<BN_RECP_CTX> was added in SSLeay 0.9.0. Before that, the function +BN_reciprocal() was used instead, and the BN_mod_mul_reciprocal() +arguments were different. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_new.pod b/crypto/openssl/doc/crypto/BN_new.pod new file mode 100644 index 0000000..c1394ff --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_new.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BIGNUM *BN_new(void); + + void BN_init(BIGNUM *); + + void BN_clear(BIGNUM *a); + + void BN_free(BIGNUM *a); + + void BN_clear_free(BIGNUM *a); + +=head1 DESCRIPTION + +BN_new() allocated and initializes a B<BIGNUM> structure. BN_init() +initializes an existing uninitialized B<BIGNUM>. + +BN_clear() is used to destroy sensitive data such as keys when they +are no longer needed. It erases the memory used by B<a> and sets it +to the value 0. + +BN_free() frees the components of the B<BIGNUM>, and if it was created +by BN_new(), also the structure itself. BN_clear_free() additionally +overwrites the data before the memory is returned to the system. + +=head1 RETURN VALUES + +BN_new() returns a pointer to the B<BIGNUM>. If the allocation fails, +it returns B<NULL> and sets an error code that can be obtained +by L<ERR_get_error(3)|ERR_get_error(3)>. + +BN_init(), BN_clear(), BN_free() and BN_clear_free() have no return +values. + +=head1 SEE ALSO + +L<bn(3)|bn(3)>, L<err(3)|err(3)> + +=head1 HISTORY + +BN_new(), BN_clear(), BN_free() and BN_clear_free() are available in +all versions on SSLeay and OpenSSL. BN_init() was added in SSLeay +0.9.1b. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_num_bytes.pod b/crypto/openssl/doc/crypto/BN_num_bytes.pod new file mode 100644 index 0000000..61589fb --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_num_bytes.pod @@ -0,0 +1,37 @@ +=pod + +=head1 NAME + +BN_num_bits, BN_num_bytes, BN_num_bits_word - get BIGNUM size + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_num_bytes(const BIGNUM *a); + + int BN_num_bits(const BIGNUM *a); + + int BN_num_bits_word(BN_ULONG w); + +=head1 DESCRIPTION + +These functions return the size of a B<BIGNUM> in bytes or bits, +and the size of an unsigned integer in bits. + +BN_num_bytes() is a macro. + +=head1 RETURN VALUES + +The size. + +=head1 SEE ALSO + +L<bn(3)|bn(3)> + +=head1 HISTORY + +BN_num_bytes(), BN_num_bits() and BN_num_bits_word() are available in +all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_rand.pod b/crypto/openssl/doc/crypto/BN_rand.pod new file mode 100644 index 0000000..33363c9 --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_rand.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + +BN_rand, BN_pseudo_rand - generate pseudo-random number + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); + + int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); + +=head1 DESCRIPTION + +BN_rand() generates a cryptographically strong pseudo-random number of +B<bits> bits in length and stores it in B<rnd>. If B<top> is true, the +two most significant bits of the number will be set to 1, so that the +product of two such random numbers will always have 2*B<bits> length. +If B<bottom> is true, the number will be odd. + +BN_pseudo_rand() does the same, but pseudo-random numbers generated by +this function are not necessarily unpredictable. They can be used for +non-cryptographic purposes and for certain purposes in cryptographic +protocols, but usually not for key generation etc. + +The PRNG must be seeded prior to calling BN_rand(). + +=head1 RETURN VALUES + +BN_rand() and BN_pseudo_rand() return 1 on success, 0 on error. +The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<bn(3)|bn(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, +L<RAND_add(3)|RAND_add(3)>, L<RAND_bytes(3)|RAND_bytes(3)> + +=head1 HISTORY + +BN_rand() is available in all versions of SSLeay and OpenSSL. +BN_pseudo_rand() was added in OpenSSL 0.9.5. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_set_bit.pod b/crypto/openssl/doc/crypto/BN_set_bit.pod new file mode 100644 index 0000000..b7c47b9 --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_set_bit.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +BN_set_bit, BN_clear_bit, BN_is_bit_set, BN_mask_bits, BN_lshift, +BN_lshift1, BN_rshift, BN_rshift1 - bit operations on BIGNUMs + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_set_bit(BIGNUM *a, int n); + int BN_clear_bit(BIGNUM *a, int n); + + int BN_is_bit_set(const BIGNUM *a, int n); + + int BN_mask_bits(BIGNUM *a, int n); + + int BN_lshift(BIGNUM *r, const BIGNUM *a, int n); + int BN_lshift1(BIGNUM *r, BIGNUM *a); + + int BN_rshift(BIGNUM *r, BIGNUM *a, int n); + int BN_rshift1(BIGNUM *r, BIGNUM *a); + +=head1 DESCRIPTION + +BN_set_bit() sets bit B<n> in B<a> to 1 (C<a|=(1E<lt>E<lt>n)>). The +number is expanded if necessary. + +BN_clear_bit() sets bit B<n> in B<a> to 0 (C<a&=~(1E<lt>E<lt>n)>). An +error occurs if B<a> is shorter than B<n> bits. + +BN_is_bit_set() tests if bit B<n> in B<a> is set. + +BN_mask_bits() truncates B<a> to an B<n> bit number +(C<a&=~((~0)E<gt>E<gt>n)>). An error occurs if B<a> already is +shorter than B<n> bits. + +BN_lshift() shifts B<a> left by B<n> bits and places the result in +B<r> (C<r=a*2^n>). BN_lshift1() shifts B<a> left by one and places +the result in B<r> (C<r=2*a>). + +BN_rshift() shifts B<a> right by B<n> bits and places the result in +B<r> (C<r=a/2^n>). BN_rshift1() shifts B<a> right by one and places +the result in B<r> (C<r=a/2>). + +For the shift functions, B<r> and B<a> may be the same variable. + +=head1 RETURN VALUES + +BN_is_bit_set() returns 1 if the bit is set, 0 otherwise. + +All other functions return 1 for success, 0 on error. The error codes +can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<bn(3)|bn(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, L<BN_add(3)|BN_add(3)> + +=head1 HISTORY + +BN_set_bit(), BN_clear_bit(), BN_is_bit_set(), BN_mask_bits(), +BN_lshift(), BN_lshift1(), BN_rshift(), and BN_rshift1() are available +in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/BN_zero.pod b/crypto/openssl/doc/crypto/BN_zero.pod new file mode 100644 index 0000000..2f33876 --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_zero.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word - BIGNUM assignment +operations + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_zero(BIGNUM *a); + int BN_one(BIGNUM *a); + + BIGNUM *BN_value_one(void); + + int BN_set_word(BIGNUM *a, unsigned long w); + unsigned long BN_get_word(BIGNUM *a); + +=head1 DESCRIPTION + +BN_zero(), BN_one() and BN_set_word() set B<a> to the values 0, 1 and +B<w> respectively. BN_zero() and BN_one() are macros. + +BN_value_one() returns a B<BIGNUM> constant of value 1. This constant +is useful for use in comparisons and assignment. + +BN_get_word() returns B<a>, if it can be represented as an unsigned +long. + +=head1 RETURN VALUES + +BN_get_word() returns the value B<a>, and 0xffffffffL if B<a> cannot +be represented as an unsigned long. + +BN_zero(), BN_one() and BN_set_word() return 1 on success, 0 otherwise. +BN_value_one() returns the constant. + +=head1 BUGS + +Someone might change the constant. + +If a B<BIGNUM> is equal to 0xffffffffL it can be represented as an +unsigned long but this value is also returned on error. + +=head1 SEE ALSO + +L<bn(3)|bn(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)> + +=head1 HISTORY + +BN_zero(), BN_one() and BN_set_word() are available in all versions of +SSLeay and OpenSSL. BN_value_one() and BN_get_word() were added in +SSLeay 0.8. + +=cut diff --git a/crypto/openssl/doc/crypto/CRYPTO_set_ex_data.pod b/crypto/openssl/doc/crypto/CRYPTO_set_ex_data.pod new file mode 100644 index 0000000..1bd5bed --- /dev/null +++ b/crypto/openssl/doc/crypto/CRYPTO_set_ex_data.pod @@ -0,0 +1,51 @@ +=pod + +=head1 NAME + +CRYPTO_set_ex_data, CRYPTO_get_ex_data - internal application specific data functions + +=head1 SYNOPSIS + + int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg); + + void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx); + +=head1 DESCRIPTION + +Several OpenSSL structures can have application specific data attached to them. +These functions are used internally by OpenSSL to manipulate application +specific data attached to a specific structure. + +These functions should only be used by applications to manipulate +B<CRYPTO_EX_DATA> structures passed to the B<new_func()>, B<free_func()> and +B<dup_func()> callbacks: as passed to B<RSA_get_ex_new_index()> for example. + +B<CRYPTO_set_ex_data()> is used to set application specific data, the data is +supplied in the B<arg> parameter and its precise meaning is up to the +application. + +B<CRYPTO_get_ex_data()> is used to retrieve application specific data. The data +is returned to the application, this will be the same value as supplied to +a previous B<CRYPTO_set_ex_data()> call. + +=head1 RETURN VALUES + +B<CRYPTO_set_ex_data()> returns 1 on success or 0 on failure. + +B<CRYPTO_get_ex_data()> returns the application data or 0 on failure. 0 may also +be valid application data but currently it can only fail if given an invalid B<idx> +parameter. + +On failure an error code can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, +L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>, +L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)> + +=head1 HISTORY + +CRYPTO_set_ex_data() and CRYPTO_get_ex_data() have been available since SSLeay 0.9.0. + +=cut diff --git a/crypto/openssl/doc/crypto/DH_generate_key.pod b/crypto/openssl/doc/crypto/DH_generate_key.pod new file mode 100644 index 0000000..920995b --- /dev/null +++ b/crypto/openssl/doc/crypto/DH_generate_key.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +DH_generate_key, DH_compute_key - perform Diffie-Hellman key exchange + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + int DH_generate_key(DH *dh); + + int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); + +=head1 DESCRIPTION + +DH_generate_key() performs the first step of a Diffie-Hellman key +exchange by generating private and public DH values. By calling +DH_compute_key(), these are combined with the other party's public +value to compute the shared key. + +DH_generate_key() expects B<dh> to contain the shared parameters +B<dh-E<gt>p> and B<dh-E<gt>g>. It generates a random private DH value +unless B<dh-E<gt>priv_key> is already set, and computes the +corresponding public value B<dh-E<gt>pub_key>, which can then be +published. + +DH_compute_key() computes the shared secret from the private DH value +in B<dh> and the other party's public value in B<pub_key> and stores +it in B<key>. B<key> must point to B<DH_size(dh)> bytes of memory. + +=head1 RETURN VALUES + +DH_generate_key() returns 1 on success, 0 otherwise. + +DH_compute_key() returns the size of the shared secret on success, -1 +on error. + +The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<DH_size(3)|DH_size(3)> + +=head1 HISTORY + +DH_generate_key() and DH_compute_key() are available in all versions +of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/DH_generate_parameters.pod b/crypto/openssl/doc/crypto/DH_generate_parameters.pod new file mode 100644 index 0000000..a7d0c75 --- /dev/null +++ b/crypto/openssl/doc/crypto/DH_generate_parameters.pod @@ -0,0 +1,72 @@ +=pod + +=head1 NAME + +DH_generate_parameters, DH_check - generate and check Diffie-Hellman parameters + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + DH *DH_generate_parameters(int prime_len, int generator, + void (*callback)(int, int, void *), void *cb_arg); + + int DH_check(DH *dh, int *codes); + +=head1 DESCRIPTION + +DH_generate_parameters() generates Diffie-Hellman parameters that can +be shared among a group of users, and returns them in a newly +allocated B<DH> structure. The pseudo-random number generator must be +seeded prior to calling DH_generate_parameters(). + +B<prime_len> is the length in bits of the safe prime to be generated. +B<generator> is a small number E<gt> 1, typically 2 or 5. + +A callback function may be used to provide feedback about the progress +of the key generation. If B<callback> is not B<NULL>, it will be +called as described in L<BN_generate_prime(3)|BN_generate_prime(3)> while a random prime +number is generated, and when a prime has been found, B<callback(3, +0, cb_arg)> is called. + +DH_check() validates Diffie-Hellman parameters. It checks that B<p> is +a safe prime, and that B<g> is a suitable generator. In the case of an +error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or +DH_NOT_SUITABLE_GENERATOR are set in B<*codes>. +DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be +checked, i.e. it does not equal 2 or 5. + +=head1 RETURN VALUES + +DH_generate_parameters() returns a pointer to the DH structure, or +NULL if the parameter generation fails. The error codes can be +obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +DH_check() returns 1 if the check could be performed, 0 otherwise. + +=head1 NOTES + +DH_generate_parameters() may run for several hours before finding a +suitable prime. + +The parameters generated by DH_generate_parameters() are not to be +used in signature schemes. + +=head1 BUGS + +If B<generator> is not 2 or 5, B<dh-E<gt>g>=B<generator> is not +a usable generator. + +=head1 SEE ALSO + +L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<DH_free(3)|DH_free(3)> + +=head1 HISTORY + +DH_check() is available in all versions of SSLeay and OpenSSL. +The B<cb_arg> argument to DH_generate_parameters() was added in SSLeay 0.9.0. + +In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used +instead of DH_CHECK_P_NOT_SAFE_PRIME. + +=cut diff --git a/crypto/openssl/doc/crypto/DH_get_ex_new_index.pod b/crypto/openssl/doc/crypto/DH_get_ex_new_index.pod new file mode 100644 index 0000000..82e2548 --- /dev/null +++ b/crypto/openssl/doc/crypto/DH_get_ex_new_index.pod @@ -0,0 +1,36 @@ +=pod + +=head1 NAME + +DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data - add application specific data to DH structures + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + int DH_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + int DH_set_ex_data(DH *d, int idx, void *arg); + + char *DH_get_ex_data(DH *d, int idx); + +=head1 DESCRIPTION + +These functions handle application specific data in DH +structures. Their usage is identical to that of +RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() +as described in L<RSA_get_ex_new_index(3)>. + +=head1 SEE ALSO + +L<RSA_get_ex_new_index()|RSA_get_ex_new_index()>, L<dh(3)|dh(3)> + +=head1 HISTORY + +DH_get_ex_new_index(), DH_set_ex_data() and DH_get_ex_data() are +available since OpenSSL 0.9.5. + +=cut diff --git a/crypto/openssl/doc/crypto/DH_new.pod b/crypto/openssl/doc/crypto/DH_new.pod new file mode 100644 index 0000000..64624b9 --- /dev/null +++ b/crypto/openssl/doc/crypto/DH_new.pod @@ -0,0 +1,40 @@ +=pod + +=head1 NAME + +DH_new, DH_free - allocate and free DH objects + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + DH* DH_new(void); + + void DH_free(DH *dh); + +=head1 DESCRIPTION + +DH_new() allocates and initializes a B<DH> structure. + +DH_free() frees the B<DH> structure and its components. The values are +erased before the memory is returned to the system. + +=head1 RETURN VALUES + +If the allocation fails, DH_new() returns B<NULL> and sets an error +code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns +a pointer to the newly allocated structure. + +DH_free() returns no value. + +=head1 SEE ALSO + +L<dh(3)|dh(3)>, L<err(3)|err(3)>, +L<DH_generate_parameters(3)|DH_generate_parameters(3)>, +L<DH_generate_key(3)|DH_generate_key(3)> + +=head1 HISTORY + +DH_new() and DH_free() are available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/DH_set_method.pod b/crypto/openssl/doc/crypto/DH_set_method.pod new file mode 100644 index 0000000..b9a61d5 --- /dev/null +++ b/crypto/openssl/doc/crypto/DH_set_method.pod @@ -0,0 +1,96 @@ +=pod + +=head1 NAME + +DH_set_default_method, DH_get_default_method, DH_set_method, +DH_new_method, DH_OpenSSL - select DH method + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + void DH_set_default_method(DH_METHOD *meth); + + DH_METHOD *DH_get_default_method(void); + + DH_METHOD *DH_set_method(DH *dh, DH_METHOD *meth); + + DH *DH_new_method(DH_METHOD *meth); + + DH_METHOD *DH_OpenSSL(void); + +=head1 DESCRIPTION + +A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman +operations. By modifying the method, alternative implementations +such as hardware accelerators may be used. + +Initially, the default is to use the OpenSSL internal implementation. +DH_OpenSSL() returns a pointer to that method. + +DH_set_default_method() makes B<meth> the default method for all B<DH> +structures created later. + +DH_get_default_method() returns a pointer to the current default +method. + +DH_set_method() selects B<meth> for all operations using the structure B<dh>. + +DH_new_method() allocates and initializes a B<DH> structure so that +B<method> will be used for the DH operations. If B<method> is B<NULL>, +the default method is used. + +=head1 THE DH_METHOD STRUCTURE + + typedef struct dh_meth_st + { + /* name of the implementation */ + const char *name; + + /* generate private and public DH values for key agreement */ + int (*generate_key)(DH *dh); + + /* compute shared secret */ + int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh); + + /* compute r = a ^ p mod m (May be NULL for some implementations) */ + int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx, + BN_MONT_CTX *m_ctx); + + /* called at DH_new */ + int (*init)(DH *dh); + + /* called at DH_free */ + int (*finish)(DH *dh); + + int flags; + + char *app_data; /* ?? */ + + } DH_METHOD; + +=head1 RETURN VALUES + +DH_OpenSSL() and DH_get_default_method() return pointers to the respective +B<DH_METHOD>s. + +DH_set_default_method() returns no value. + +DH_set_method() returns a pointer to the B<DH_METHOD> previously +associated with B<dh>. + +DH_new_method() returns B<NULL> and sets an error code that can be +obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise it +returns a pointer to the newly allocated structure. + +=head1 SEE ALSO + +L<dh(3)|dh(3)>, L<DH_new(3)|DH_new(3)> + +=head1 HISTORY + +DH_set_default_method(), DH_get_default_method(), DH_set_method(), +DH_new_method() and DH_OpenSSL() were added in OpenSSL 0.9.4. + +=cut diff --git a/crypto/openssl/doc/crypto/DH_size.pod b/crypto/openssl/doc/crypto/DH_size.pod new file mode 100644 index 0000000..97f26fd --- /dev/null +++ b/crypto/openssl/doc/crypto/DH_size.pod @@ -0,0 +1,33 @@ +=pod + +=head1 NAME + +DH_size - get Diffie-Hellman prime size + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + int DH_size(DH *dh); + +=head1 DESCRIPTION + +This function returns the Diffie-Hellman size in bytes. It can be used +to determine how much memory must be allocated for the shared secret +computed by DH_compute_key(). + +B<dh-E<gt>p> must not be B<NULL>. + +=head1 RETURN VALUE + +The size in bytes. + +=head1 SEE ALSO + +L<dh(3)|dh(3)>, L<DH_generate_key(3)|DH_generate_key(3)> + +=head1 HISTORY + +DH_size() is available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/DSA_SIG_new.pod b/crypto/openssl/doc/crypto/DSA_SIG_new.pod new file mode 100644 index 0000000..6716555 --- /dev/null +++ b/crypto/openssl/doc/crypto/DSA_SIG_new.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + DSA_SIG *DSA_SIG_new(void); + + void DSA_SIG_free(DSA_SIG *a); + +=head1 DESCRIPTION + +DSA_SIG_new() allocates and initializes a B<DSA_SIG> structure. + +DSA_SIG_free() frees the B<DSA_SIG> structure and its components. The +values are erased before the memory is returned to the system. + +=head1 RETURN VALUES + +If the allocation fails, DSA_SIG_new() returns B<NULL> and sets an +error code that can be obtained by +L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer +to the newly allocated structure. + +DSA_SIG_free() returns no value. + +=head1 SEE ALSO + +L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<DSA_do_sign(3)|DSA_do_sign(3)> + +=head1 HISTORY + +DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3. + +=cut diff --git a/crypto/openssl/doc/crypto/DSA_do_sign.pod b/crypto/openssl/doc/crypto/DSA_do_sign.pod new file mode 100644 index 0000000..a24fd57 --- /dev/null +++ b/crypto/openssl/doc/crypto/DSA_do_sign.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + +DSA_do_sign, DSA_do_verify - raw DSA signature operations + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); + + int DSA_do_verify(const unsigned char *dgst, int dgst_len, + DSA_SIG *sig, DSA *dsa); + +=head1 DESCRIPTION + +DSA_do_sign() computes a digital signature on the B<len> byte message +digest B<dgst> using the private key B<dsa> and returns it in a +newly allocated B<DSA_SIG> structure. + +L<DSA_sign_setup(3)|DSA_sign_setup(3)> may be used to precompute part +of the signing operation in case signature generation is +time-critical. + +DSA_do_verify() verifies that the signature B<sig> matches a given +message digest B<dgst> of size B<len>. B<dsa> is the signer's public +key. + +=head1 RETURN VALUES + +DSA_do_sign() returns the signature, NULL on error. DSA_do_verify() +returns 1 for a valid signature, 0 for an incorrect signature and -1 +on error. The error codes can be obtained by +L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, +L<DSA_SIG_new(3)|DSA_SIG_new(3)>, +L<DSA_sign(3)|DSA_sign(3)> + +=head1 HISTORY + +DSA_do_sign() and DSA_do_verify() were added in OpenSSL 0.9.3. + +=cut diff --git a/crypto/openssl/doc/crypto/DSA_dup_DH.pod b/crypto/openssl/doc/crypto/DSA_dup_DH.pod new file mode 100644 index 0000000..29cb107 --- /dev/null +++ b/crypto/openssl/doc/crypto/DSA_dup_DH.pod @@ -0,0 +1,36 @@ +=pod + +=head1 NAME + +DSA_dup_DH - create a DH structure out of DSA structure + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + DH * DSA_dup_DH(DSA *r); + +=head1 DESCRIPTION + +DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q +is lost during that conversion, but the resulting DH parameters +contain its length. + +=head1 RETURN VALUE + +DSA_dup_DH() returns the new B<DH> structure, and NULL on error. The +error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 NOTE + +Be careful to avoid small subgroup attacks when using this. + +=head1 SEE ALSO + +L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<err(3)|err(3)> + +=head1 HISTORY + +DSA_dup_DH() was added in OpenSSL 0.9.4. + +=cut diff --git a/crypto/openssl/doc/crypto/DSA_generate_key.pod b/crypto/openssl/doc/crypto/DSA_generate_key.pod new file mode 100644 index 0000000..52890db --- /dev/null +++ b/crypto/openssl/doc/crypto/DSA_generate_key.pod @@ -0,0 +1,33 @@ +=pod + +=head1 NAME + +DSA_generate_key - generate DSA key pair + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + int DSA_generate_key(DSA *a); + +=head1 DESCRIPTION + +DSA_generate_key() expects B<a> to contain DSA parameters. It generates +a new key pair and stores it in B<a-E<gt>pub_key> and B<a-E<gt>priv_key>. + +The PRNG must be seeded prior to calling DSA_generate_key(). + +=head1 RETURN VALUE + +DSA_generate_key() returns 1 on success, 0 otherwise. +The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<DSA_generate_parameters(3)|DSA_generate_parameters(3)> + +=head1 HISTORY + +DSA_generate_key() is available since SSLeay 0.8. + +=cut diff --git a/crypto/openssl/doc/crypto/DSA_generate_parameters.pod b/crypto/openssl/doc/crypto/DSA_generate_parameters.pod new file mode 100644 index 0000000..43f60b0 --- /dev/null +++ b/crypto/openssl/doc/crypto/DSA_generate_parameters.pod @@ -0,0 +1,105 @@ +=pod + +=head1 NAME + +DSA_generate_parameters - generate DSA parameters + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + DSA *DSA_generate_parameters(int bits, unsigned char *seed, + int seed_len, int *counter_ret, unsigned long *h_ret, + void (*callback)(int, int, void *), void *cb_arg); + +=head1 DESCRIPTION + +DSA_generate_parameters() generates primes p and q and a generator g +for use in the DSA. + +B<bits> is the length of the prime to be generated; the DSS allows a +maximum of 1024 bits. + +If B<seed> is B<NULL> or B<seed_len> E<lt> 20, the primes will be +generated at random. Otherwise, the seed is used to generate +them. If the given seed does not yield a prime q, a new random +seed is chosen and placed at B<seed>. + +DSA_generate_parameters() places the iteration count in +*B<counter_ret> and a counter used for finding a generator in +*B<h_ret>, unless these are B<NULL>. + +A callback function may be used to provide feedback about the progress +of the key generation. If B<callback> is not B<NULL>, it will be +called as follows: + +=over 4 + +=item * + +When a candidate for q is generated, B<callback(0, m++, cb_arg)> is called +(m is 0 for the first candidate). + +=item * + +When a candidate for q has passed a test by trial division, +B<callback(1, -1, cb_arg)> is called. +While a candidate for q is tested by Miller-Rabin primality tests, +B<callback(1, i, cb_arg)> is called in the outer loop +(once for each witness that confirms that the candidate may be prime); +i is the loop counter (starting at 0). + +=item * + +When a prime q has been found, B<callback(2, 0, cb_arg)> and +B<callback(3, 0, cb_arg)> are called. + +=item * + +Before a candidate for p (other than the first) is generated and tested, +B<callback(0, counter, cb_arg)> is called. + +=item * + +When a candidate for p has passed the test by trial division, +B<callback(1, -1, cb_arg)> is called. +While it is tested by the Miller-Rabin primality test, +B<callback(1, i, cb_arg)> is called in the outer loop +(once for each witness that confirms that the candidate may be prime). +i is the loop counter (starting at 0). + +=item * + +When p has been found, B<callback(2, 1, cb_arg)> is called. + +=item * + +When the generator has been found, B<callback(3, 1, cb_arg)> is called. + +=back + +=head1 RETURN VALUE + +DSA_generate_parameters() returns a pointer to the DSA structure, or +B<NULL> if the parameter generation fails. The error codes can be +obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 BUGS + +Seed lengths E<gt> 20 are not supported. + +=head1 SEE ALSO + +L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, +L<DSA_free(3)|DSA_free(3)> + +=head1 HISTORY + +DSA_generate_parameters() appeared in SSLeay 0.8. The B<cb_arg> +argument was added in SSLeay 0.9.0. +In versions up to OpenSSL 0.9.4, B<callback(1, ...)> was called +in the inner loop of the Miller-Rabin test whenever it reached the +squaring step (the parameters to B<callback> did not reveal how many +witnesses had been tested); since OpenSSL 0.9.5, B<callback(1, ...)> +is called as in BN_is_prime(3), i.e. once for each witness. +=cut diff --git a/crypto/openssl/doc/crypto/DSA_get_ex_new_index.pod b/crypto/openssl/doc/crypto/DSA_get_ex_new_index.pod new file mode 100644 index 0000000..4612e70 --- /dev/null +++ b/crypto/openssl/doc/crypto/DSA_get_ex_new_index.pod @@ -0,0 +1,36 @@ +=pod + +=head1 NAME + +DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application specific data to DSA structures + +=head1 SYNOPSIS + + #include <openssl/DSA.h> + + int DSA_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + int DSA_set_ex_data(DSA *d, int idx, void *arg); + + char *DSA_get_ex_data(DSA *d, int idx); + +=head1 DESCRIPTION + +These functions handle application specific data in DSA +structures. Their usage is identical to that of +RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() +as described in L<RSA_get_ex_new_index(3)>. + +=head1 SEE ALSO + +L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dsa(3)|dsa(3)> + +=head1 HISTORY + +DSA_get_ex_new_index(), DSA_set_ex_data() and DSA_get_ex_data() are +available since OpenSSL 0.9.5. + +=cut diff --git a/crypto/openssl/doc/crypto/DSA_new.pod b/crypto/openssl/doc/crypto/DSA_new.pod new file mode 100644 index 0000000..7dde544 --- /dev/null +++ b/crypto/openssl/doc/crypto/DSA_new.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + +DSA_new, DSA_free - allocate and free DSA objects + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + DSA* DSA_new(void); + + void DSA_free(DSA *dsa); + +=head1 DESCRIPTION + +DSA_new() allocates and initializes a B<DSA> structure. + +DSA_free() frees the B<DSA> structure and its components. The values are +erased before the memory is returned to the system. + +=head1 RETURN VALUES + +If the allocation fails, DSA_new() returns B<NULL> and sets an error +code that can be obtained by +L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer +to the newly allocated structure. + +DSA_free() returns no value. + +=head1 SEE ALSO + +L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, +L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>, +L<DSA_generate_key(3)|DSA_generate_key(3)> + +=head1 HISTORY + +DSA_new() and DSA_free() are available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/DSA_set_method.pod b/crypto/openssl/doc/crypto/DSA_set_method.pod new file mode 100644 index 0000000..cabc3c0 --- /dev/null +++ b/crypto/openssl/doc/crypto/DSA_set_method.pod @@ -0,0 +1,109 @@ +=pod + +=head1 NAME + +DSA_set_default_method, DSA_get_default_method, DSA_set_method, +DSA_new_method, DSA_OpenSSL - select DSA method + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + void DSA_set_default_method(DSA_METHOD *meth); + + DSA_METHOD *DSA_get_default_method(void); + + DSA_METHOD *DSA_set_method(DSA *dsa, DSA_METHOD *meth); + + DSA *DSA_new_method(DSA_METHOD *meth); + + DSA_METHOD *DSA_OpenSSL(void); + +=head1 DESCRIPTION + +A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA +operations. By modifying the method, alternative implementations +such as hardware accelerators may be used. + +Initially, the default is to use the OpenSSL internal implementation. +DSA_OpenSSL() returns a pointer to that method. + +DSA_set_default_method() makes B<meth> the default method for all B<DSA> +structures created later. + +DSA_get_default_method() returns a pointer to the current default +method. + +DSA_set_method() selects B<meth> for all operations using the structure B<dsa>. + +DSA_new_method() allocates and initializes a B<DSA> structure so that +B<method> will be used for the DSA operations. If B<method> is B<NULL>, +the default method is used. + +=head1 THE DSA_METHOD STRUCTURE + +struct + { + /* name of the implementation */ + const char *name; + + /* sign */ + DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen, + DSA *dsa); + + /* pre-compute k^-1 and r */ + int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp, + BIGNUM **rp); + + /* verify */ + int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len, + DSA_SIG *sig, DSA *dsa); + + /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some + implementations) */ + int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, + BIGNUM *a2, BIGNUM *p2, BIGNUM *m, + BN_CTX *ctx, BN_MONT_CTX *in_mont); + + /* compute r = a ^ p mod m (May be NULL for some implementations) */ + int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a, + const BIGNUM *p, const BIGNUM *m, + BN_CTX *ctx, BN_MONT_CTX *m_ctx); + + /* called at DSA_new */ + int (*init)(DSA *DSA); + + /* called at DSA_free */ + int (*finish)(DSA *DSA); + + int flags; + + char *app_data; /* ?? */ + + } DSA_METHOD; + +=head1 RETURN VALUES + +DSA_OpenSSL() and DSA_get_default_method() return pointers to the +respective B<DSA_METHOD>s. + +DSA_set_default_method() returns no value. + +DSA_set_method() returns a pointer to the B<DSA_METHOD> previously +associated with B<dsa>. + +DSA_new_method() returns B<NULL> and sets an error code that can be +obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation +fails. Otherwise it returns a pointer to the newly allocated +structure. + +=head1 SEE ALSO + +L<dsa(3)|dsa(3)>, L<DSA_new(3)|DSA_new(3)> + +=head1 HISTORY + +DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(), +DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4. + +=cut diff --git a/crypto/openssl/doc/crypto/DSA_sign.pod b/crypto/openssl/doc/crypto/DSA_sign.pod new file mode 100644 index 0000000..f6e60a8 --- /dev/null +++ b/crypto/openssl/doc/crypto/DSA_sign.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + int DSA_sign(int type, const unsigned char *dgst, int len, + unsigned char *sigret, unsigned int *siglen, DSA *dsa); + + int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, + BIGNUM **rp); + + int DSA_verify(int type, const unsigned char *dgst, int len, + unsigned char *sigbuf, int siglen, DSA *dsa); + +=head1 DESCRIPTION + +DSA_sign() computes a digital signature on the B<len> byte message +digest B<dgst> using the private key B<dsa> and places its ASN.1 DER +encoding at B<sigret>. The length of the signature is places in +*B<siglen>. B<sigret> must point to DSA_size(B<dsa>) bytes of memory. + +DSA_sign_setup() may be used to precompute part of the signing +operation in case signature generation is time-critical. It expects +B<dsa> to contain DSA parameters. It places the precomputed values +in newly allocated B<BIGNUM>s at *B<kinvp> and *B<rp>, after freeing +the old ones unless *B<kinvp> and *B<rp> are NULL. These values may +be passed to DSA_sign() in B<dsa-E<gt>kinv> and B<dsa-E<gt>r>. +B<ctx> is a pre-allocated B<BN_CTX> or NULL. + +DSA_verify() verifies that the signature B<sigbuf> of size B<siglen> +matches a given message digest B<dgst> of size B<len>. +B<dsa> is the signer's public key. + +The B<type> parameter is ignored. + +The PRNG must be seeded before DSA_sign() (or DSA_sign_setup()) +is called. + +=head1 RETURN VALUES + +DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error. +DSA_verify() returns 1 for a valid signature, 0 for an incorrect +signature and -1 on error. The error codes can be obtained by +L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 CONFORMING TO + +US Federal Information Processing Standard FIPS 186 (Digital Signature +Standard, DSS), ANSI X9.30 + +=head1 SEE ALSO + +L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, +L<DSA_do_sign(3)|DSA_do_sign(3)> + +=head1 HISTORY + +DSA_sign() and DSA_verify() are available in all versions of SSLeay. +DSA_sign_setup() was added in SSLeay 0.8. + +=cut diff --git a/crypto/openssl/doc/crypto/DSA_size.pod b/crypto/openssl/doc/crypto/DSA_size.pod new file mode 100644 index 0000000..23b6320 --- /dev/null +++ b/crypto/openssl/doc/crypto/DSA_size.pod @@ -0,0 +1,33 @@ +=pod + +=head1 NAME + +DSA_size - get DSA signature size + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + int DSA_size(DSA *dsa); + +=head1 DESCRIPTION + +This function returns the size of an ASN.1 encoded DSA signature in +bytes. It can be used to determine how much memory must be allocated +for a DSA signature. + +B<dsa-E<gt>q> must not be B<NULL>. + +=head1 RETURN VALUE + +The size in bytes. + +=head1 SEE ALSO + +L<dsa(3)|dsa(3)>, L<DSA_sign(3)|DSA_sign(3)> + +=head1 HISTORY + +DSA_size() is available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/ERR_GET_LIB.pod b/crypto/openssl/doc/crypto/ERR_GET_LIB.pod new file mode 100644 index 0000000..2a129da --- /dev/null +++ b/crypto/openssl/doc/crypto/ERR_GET_LIB.pod @@ -0,0 +1,51 @@ +=pod + +=head1 NAME + +ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON - get library, function and +reason code + +=head1 SYNOPSIS + + #include <openssl/err.h> + + int ERR_GET_LIB(unsigned long e); + + int ERR_GET_FUNC(unsigned long e); + + int ERR_GET_REASON(unsigned long e); + +=head1 DESCRIPTION + +The error code returned by ERR_get_error() consists of a library +number, function code and reason code. ERR_GET_LIB(), ERR_GET_FUNC() +and ERR_GET_REASON() can be used to extract these. + +The library number and function code describe where the error +occurred, the reason code is the information about what went wrong. + +Each sub-library of OpenSSL has a unique library number; function and +reason codes are unique within each sub-library. Note that different +libraries may use the same value to signal different functions and +reasons. + +B<ERR_R_...> reason codes such as B<ERR_R_MALLOC_FAILURE> are globally +unique. However, when checking for sub-library specific reason codes, +be sure to also compare the library number. + +ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are macros. + +=head1 RETURN VALUES + +The library number, function code and reason code respectively. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)> + +=head1 HISTORY + +ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in +all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/ERR_clear_error.pod b/crypto/openssl/doc/crypto/ERR_clear_error.pod new file mode 100644 index 0000000..566e1f4 --- /dev/null +++ b/crypto/openssl/doc/crypto/ERR_clear_error.pod @@ -0,0 +1,29 @@ +=pod + +=head1 NAME + +ERR_clear_error - clear the error queue + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_clear_error(void); + +=head1 DESCRIPTION + +ERR_clear_error() empties the current thread's error queue. + +=head1 RETURN VALUES + +ERR_clear_error() has no return value. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)> + +=head1 HISTORY + +ERR_clear_error() is available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/ERR_error_string.pod b/crypto/openssl/doc/crypto/ERR_error_string.pod new file mode 100644 index 0000000..e01beb8 --- /dev/null +++ b/crypto/openssl/doc/crypto/ERR_error_string.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +ERR_error_string, ERR_error_string_n, ERR_lib_error_string, +ERR_func_error_string, ERR_reason_error_string - obtain human-readable +error message + +=head1 SYNOPSIS + + #include <openssl/err.h> + + char *ERR_error_string(unsigned long e, char *buf); + char *ERR_error_string_n(unsigned long e, char *buf, size_t len); + + const char *ERR_lib_error_string(unsigned long e); + const char *ERR_func_error_string(unsigned long e); + const char *ERR_reason_error_string(unsigned long e); + +=head1 DESCRIPTION + +ERR_error_string() generates a human-readable string representing the +error code I<e>, and places it at I<buf>. I<buf> must be at least 120 +bytes long. If I<buf> is B<NULL>, the error string is placed in a +static buffer. +ERR_error_string_n() is a variant of ERR_error_string() that writes +at most I<len> characters (including the terminating 0) +and truncates the string if necessary. +For ERR_error_string_n(), I<buf> may not be B<NULL>. + +The string will have the following format: + + error:[error code]:[library name]:[function name]:[reason string] + +I<error code> is an 8 digit hexadecimal number, I<library name>, +I<function name> and I<reason string> are ASCII text. + +ERR_lib_error_string(), ERR_func_error_string() and +ERR_reason_error_string() return the library name, function +name and reason string respectively. + +The OpenSSL error strings should be loaded by calling +L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)> or, for SSL +applications, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> +first. +If there is no text string registered for the given error code, +the error string will contain the numeric code. + +L<ERR_print_errors(3)|ERR_print_errors(3)> can be used to print +all error codes currently in the queue. + +=head1 RETURN VALUES + +ERR_error_string() returns a pointer to a static buffer containing the +string if I<buf> B<== NULL>, I<buf> otherwise. + +ERR_lib_error_string(), ERR_func_error_string() and +ERR_reason_error_string() return the strings, and B<NULL> if +none is registered for the error code. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, +L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, +L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> +L<ERR_print_errors(3)|ERR_print_errors(3)> + +=head1 HISTORY + +ERR_error_string() is available in all versions of SSLeay and OpenSSL. +ERR_error_string_n() was added in OpenSSL 0.9.6. + +=cut diff --git a/crypto/openssl/doc/crypto/ERR_get_error.pod b/crypto/openssl/doc/crypto/ERR_get_error.pod new file mode 100644 index 0000000..3551bac --- /dev/null +++ b/crypto/openssl/doc/crypto/ERR_get_error.pod @@ -0,0 +1,63 @@ +=pod + +=head1 NAME + +ERR_get_error, ERR_peek_error, ERR_get_error_line, ERR_peek_error_line, +ERR_get_error_line_data, ERR_peek_error_line_data - obtain error code and data + +=head1 SYNOPSIS + + #include <openssl/err.h> + + unsigned long ERR_get_error(void); + unsigned long ERR_peek_error(void); + + unsigned long ERR_get_error_line(const char **file, int *line); + unsigned long ERR_peek_error_line(const char **file, int *line); + + unsigned long ERR_get_error_line_data(const char **file, int *line, + const char **data, int *flags); + unsigned long ERR_peek_error_line_data(const char **file, int *line, + const char **data, int *flags); + +=head1 DESCRIPTION + +ERR_get_error() returns the last error code from the thread's error +queue and removes the entry. This function can be called repeatedly +until there are no more error codes to return. + +ERR_peek_error() returns the last error code from the thread's +error queue without modifying it. + +See L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> for obtaining information about +location and reason of the error, and +L<ERR_error_string(3)|ERR_error_string(3)> for human-readable error +messages. + +ERR_get_error_line() and ERR_peek_error_line() are the same as the +above, but they additionally store the file name and line number where +the error occurred in *B<file> and *B<line>, unless these are B<NULL>. + +ERR_get_error_line_data() and ERR_peek_error_line_data() store +additional data and flags associated with the error code in *B<data> +and *B<flags>, unless these are B<NULL>. *B<data> contains a string +if *B<flags>&B<ERR_TXT_STRING>. If it has been allocated by OPENSSL_malloc(), +*B<flags>&B<ERR_TXT_MALLOCED> is true. + +=head1 RETURN VALUES + +The error code, or 0 if there is no error in the queue. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>, +L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> + +=head1 HISTORY + +ERR_get_error(), ERR_peek_error(), ERR_get_error_line() and +ERR_peek_error_line() are available in all versions of SSLeay and +OpenSSL. ERR_get_error_line_data() and ERR_peek_error_line_data() +were added in SSLeay 0.9.0. + +=cut diff --git a/crypto/openssl/doc/crypto/ERR_load_crypto_strings.pod b/crypto/openssl/doc/crypto/ERR_load_crypto_strings.pod new file mode 100644 index 0000000..9bdec75 --- /dev/null +++ b/crypto/openssl/doc/crypto/ERR_load_crypto_strings.pod @@ -0,0 +1,46 @@ +=pod + +=head1 NAME + +ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings - +load and free error strings + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_load_crypto_strings(void); + void ERR_free_strings(void); + + #include <openssl/ssl.h> + + void SSL_load_error_strings(void); + +=head1 DESCRIPTION + +ERR_load_crypto_strings() registers the error strings for all +B<libcrypto> functions. SSL_load_error_strings() does the same, +but also registers the B<libssl> error strings. + +One of these functions should be called before generating +textual error messages. However, this is not required when memory +usage is an issue. + +ERR_free_strings() frees all previously loaded error strings. + +=head1 RETURN VALUES + +ERR_load_crypto_strings(), SSL_load_error_strings() and +ERR_free_strings() return no values. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)> + +=head1 HISTORY + +ERR_load_error_strings(), SSL_load_error_strings() and +ERR_free_strings() are available in all versions of SSLeay and +OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/ERR_load_strings.pod b/crypto/openssl/doc/crypto/ERR_load_strings.pod new file mode 100644 index 0000000..5acdd0e --- /dev/null +++ b/crypto/openssl/doc/crypto/ERR_load_strings.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +ERR_load_strings, ERR_PACK, ERR_get_next_error_library - load +arbitrary error strings + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_load_strings(int lib, ERR_STRING_DATA str[]); + + int ERR_get_next_error_library(void); + + unsigned long ERR_PACK(int lib, int func, int reason); + +=head1 DESCRIPTION + +ERR_load_strings() registers error strings for library number B<lib>. + +B<str> is an array of error string data: + + typedef struct ERR_string_data_st + { + unsigned long error; + char *string; + } ERR_STRING_DATA; + +The error code is generated from the library number and a function and +reason code: B<error> = ERR_PACK(B<lib>, B<func>, B<reason>). +ERR_PACK() is a macro. + +The last entry in the array is {0,0}. + +ERR_get_next_error_library() can be used to assign library numbers +to user libraries at runtime. + +=head1 RETURN VALUE + +ERR_load_strings() returns no value. ERR_PACK() return the error code. +ERR_get_next_error_library() returns a new library number. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)> + +=head1 HISTORY + +ERR_load_error_strings() and ERR_PACK() are available in all versions +of SSLeay and OpenSSL. ERR_get_next_error_library() was added in +SSLeay 0.9.0. + +=cut diff --git a/crypto/openssl/doc/crypto/ERR_print_errors.pod b/crypto/openssl/doc/crypto/ERR_print_errors.pod new file mode 100644 index 0000000..b100a5f --- /dev/null +++ b/crypto/openssl/doc/crypto/ERR_print_errors.pod @@ -0,0 +1,51 @@ +=pod + +=head1 NAME + +ERR_print_errors, ERR_print_errors_fp - print error messages + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_print_errors(BIO *bp); + void ERR_print_errors_fp(FILE *fp); + +=head1 DESCRIPTION + +ERR_print_errors() is a convenience function that prints the error +strings for all errors that OpenSSL has recorded to B<bp>, thus +emptying the error queue. + +ERR_print_errors_fp() is the same, except that the output goes to a +B<FILE>. + + +The error strings will have the following format: + + [pid]:error:[error code]:[library name]:[function name]:[reason string]:[file name]:[line]:[optional text message] + +I<error code> is an 8 digit hexadecimal number. I<library name>, +I<function name> and I<reason string> are ASCII text, as is I<optional +text message> if one was set for the respective error code. + +If there is no text string registered for the given error code, +the error string will contain the numeric code. + +=head1 RETURN VALUES + +ERR_print_errors() and ERR_print_errors_fp() return no values. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>, +L<ERR_get_error(3)|ERR_get_error(3)>, +L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, +L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> + +=head1 HISTORY + +ERR_print_errors() and ERR_print_errors_fp() +are available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/ERR_put_error.pod b/crypto/openssl/doc/crypto/ERR_put_error.pod new file mode 100644 index 0000000..acd241f --- /dev/null +++ b/crypto/openssl/doc/crypto/ERR_put_error.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +ERR_put_error, ERR_add_error_data - record an error + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_put_error(int lib, int func, int reason, const char *file, + int line); + + void ERR_add_error_data(int num, ...); + +=head1 DESCRIPTION + +ERR_put_error() adds an error code to the thread's error queue. It +signals that the error of reason code B<reason> occurred in function +B<func> of library B<lib>, in line number B<line> of B<file>. +This function is usually called by a macro. + +ERR_add_error_data() associates the concatenation of its B<num> string +arguments with the error code added last. + +L<ERR_load_strings(3)|ERR_load_strings(3)> can be used to register +error strings so that the application can a generate human-readable +error messages for the error code. + +=head1 RETURN VALUES + +ERR_put_error() and ERR_add_error_data() return +no values. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)> + +=head1 HISTORY + +ERR_put_error() is available in all versions of SSLeay and OpenSSL. +ERR_add_error_data() was added in SSLeay 0.9.0. + +=cut diff --git a/crypto/openssl/doc/crypto/ERR_remove_state.pod b/crypto/openssl/doc/crypto/ERR_remove_state.pod new file mode 100644 index 0000000..72925fb --- /dev/null +++ b/crypto/openssl/doc/crypto/ERR_remove_state.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +ERR_remove_state - free a thread's error queue + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_remove_state(unsigned long pid); + +=head1 DESCRIPTION + +ERR_remove_state() frees the error queue associated with thread B<pid>. +If B<pid> == 0, the current thread will have its error queue removed. + +Since error queue data structures are allocated automatically for new +threads, they must be freed when threads are terminated in order to +avoid memory leaks. + +=head1 RETURN VALUE + +ERR_remove_state() returns no value. + +=head1 SEE ALSO + +L<err(3)|err(3)> + +=head1 HISTORY + +ERR_remove_state() is available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/EVP_DigestInit.pod b/crypto/openssl/doc/crypto/EVP_DigestInit.pod new file mode 100644 index 0000000..b8a231c --- /dev/null +++ b/crypto/openssl/doc/crypto/EVP_DigestInit.pod @@ -0,0 +1,202 @@ +=pod + +=head1 NAME + +EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal, EVP_MAX_MD_SIZE, +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_sha, EVP_sha1, EVP_dss, EVP_dss1, EVP_mdc2, +EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj - +EVP digest routines + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + void EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); + void EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + void EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, + unsigned int *s); + + #define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */ + + int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); + + #define EVP_MD_type(e) ((e)->type) + #define EVP_MD_pkey_type(e) ((e)->pkey_type) + #define EVP_MD_size(e) ((e)->md_size) + #define EVP_MD_block_size(e) ((e)->block_size) + + #define EVP_MD_CTX_md(e) (e)->digest) + #define EVP_MD_CTX_size(e) EVP_MD_size((e)->digest) + #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest) + #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) + + EVP_MD *EVP_md_null(void); + EVP_MD *EVP_md2(void); + EVP_MD *EVP_md5(void); + EVP_MD *EVP_sha(void); + EVP_MD *EVP_sha1(void); + EVP_MD *EVP_dss(void); + EVP_MD *EVP_dss1(void); + EVP_MD *EVP_mdc2(void); + EVP_MD *EVP_ripemd160(void); + + const EVP_MD *EVP_get_digestbyname(const char *name); + #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) + #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a)) + +=head1 DESCRIPTION + +The EVP digest routines are a high level interface to message digests. + +EVP_DigestInit() initializes a digest context B<ctx> to use a digest +B<type>: this will typically be supplied by a function such as +EVP_sha1(). + +EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the +digest context B<ctx>. This function can be called several times on the +same B<ctx> to hash additional data. + +EVP_DigestFinal() retrieves the digest value from B<ctx> and places +it in B<md>. If the B<s> parameter is not NULL then the number of +bytes of data written (i.e. the length of the digest) will be written +to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written. +After calling EVP_DigestFinal() no additional calls to EVP_DigestUpdate() +can be made, but EVP_DigestInit() can be called to initialize a new +digest operation. + +EVP_MD_CTX_copy() can be used to copy the message digest state from +B<in> to B<out>. This is useful if large amounts of data are to be +hashed which only differ in the last few bytes. + +EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest +when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the +hash. + +EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the +message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure. + +EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER +representing the given message digest when passed an B<EVP_MD> structure. +For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is +normally used when setting ASN1 OIDs. + +EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed +B<EVP_MD_CTX>. + +EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated +with this digest. For example EVP_sha1() is associated with RSA so this will +return B<NID_sha1WithRSAEncryption>. This "link" between digests and signature +algorithms may not be retained in future versions of OpenSSL. + +EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_mdc2() and EVP_ripemd160() +return B<EVP_MD> structures for the MD2, MD5, SHA, SHA1, MDC2 and RIPEMD160 digest +algorithms respectively. The associated signature algorithm is RSA in each case. + +EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest +algorithms but using DSS (DSA) for the signature algorithm. + +EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it +returns is of zero length. + +EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() +return an B<EVP_MD> structure when passed a digest name, a digest NID or +an ASN1_OBJECT structure respectively. The digest table must be initialized +using, for example, OpenSSL_add_all_digests() for these functions to work. + +=head1 RETURN VALUES + +EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() do not return values. + +EVP_MD_CTX_copy() returns 1 if successful or 0 for failure. + +EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the +corresponding OBJECT IDENTIFIER or NID_undef if none exists. + +EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size(e), EVP_MD_size(), +EVP_MD_CTX_block_size() and EVP_MD_block_size() return the digest or block +size in bytes. + +EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), +EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the +corresponding EVP_MD structures. + +EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() +return either an B<EVP_MD> structure or NULL if an error occurs. + +=head1 NOTES + +The B<EVP> interface to message digests should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the digest used and much more flexible. + +SHA1 is the digest of choice for new applications. The other digest algorithms +are still in common use. + +=head1 EXAMPLE + +This example digests the data "Test Message\n" and "Hello World\n", using the +digest name passed on the command line. + + #include <stdio.h> + #include <openssl/evp.h> + + main(int argc, char *argv[]) + { + EVP_MD_CTX mdctx; + const EVP_MD *md; + char mess1[] = "Test Message\n"; + char mess2[] = "Hello World\n"; + unsigned char md_value[EVP_MAX_MD_SIZE]; + int md_len, i; + + OpenSSL_add_all_digests(); + + if(!argv[1]) { + printf("Usage: mdtest digestname\n"); + exit(1); + } + + md = EVP_get_digestbyname(argv[1]); + + if(!md) { + printf("Unknown message digest %s\n", argv[1]); + exit(1); + } + + EVP_DigestInit(&mdctx, md); + EVP_DigestUpdate(&mdctx, mess1, strlen(mess1)); + EVP_DigestUpdate(&mdctx, mess2, strlen(mess2)); + EVP_DigestFinal(&mdctx, md_value, &md_len); + + printf("Digest is: "); + for(i = 0; i < md_len; i++) printf("%02x", md_value[i]); + printf("\n"); + } + +=head1 BUGS + +Several of the functions do not return values: maybe they should. Although the +internal digest operations will never fail some future hardware based operations +might. + +The link between digests and signing algorithms results in a situation where +EVP_sha1() must be used with RSA and EVP_dss1() must be used with DSS +even though they are identical digests. + +The size of an B<EVP_MD_CTX> structure is determined at compile time: this results +in code that must be recompiled if the size of B<EVP_MD_CTX> increases. + +=head1 SEE ALSO + +L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, +L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, +L<sha(3)|sha(3)>, L<digest(1)|digest(1)> + +=head1 HISTORY + +EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are +available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/EVP_EncryptInit.pod b/crypto/openssl/doc/crypto/EVP_EncryptInit.pod new file mode 100644 index 0000000..9afe239 --- /dev/null +++ b/crypto/openssl/doc/crypto/EVP_EncryptInit.pod @@ -0,0 +1,359 @@ +=pod + +=head1 NAME + +EVP_EncryptInit, EVP_EncryptUpdate, EVP_EncryptFinal, EVP_DecryptInit, +EVP_DecryptUpdate, EVP_DecryptFinal, EVP_CipherInit, EVP_CipherUpdate, +EVP_CipherFinal, EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl, +EVP_CIPHER_CTX_cleanup, EVP_get_cipherbyname, EVP_get_cipherbynid, +EVP_get_cipherbyobj, EVP_CIPHER_nid, EVP_CIPHER_block_size, +EVP_CIPHER_key_length, EVP_CIPHER_iv_length, EVP_CIPHER_flags, +EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher, EVP_CIPHER_CTX_nid, +EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, EVP_CIPHER_CTX_iv_length, +EVP_CIPHER_CTX_get_app_data, EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, +EVP_CIPHER_CTX_flags, EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, +EVP_CIPHER_asn1_to_param - EVP cipher routines + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, + unsigned char *key, unsigned char *iv); + int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl, unsigned char *in, int inl); + int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl); + + int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, + unsigned char *key, unsigned char *iv); + int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl, unsigned char *in, int inl); + int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, + int *outl); + + int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, + unsigned char *key, unsigned char *iv, int enc); + int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl, unsigned char *in, int inl); + int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, + int *outl); + + int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen); + int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr); + int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a); + + 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) + int EVP_CIPHER_type(const EVP_CIPHER *ctx); + + #define EVP_CIPHER_CTX_cipher(e) ((e)->cipher) + #define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid) + #define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size) + #define EVP_CIPHER_CTX_key_length(e) ((e)->key_len) + #define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len) + #define EVP_CIPHER_CTX_get_app_data(e) ((e)->app_data) + #define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d)) + #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c)) + #define EVP_CIPHER_CTX_flags(e) ((e)->cipher->flags) + #define EVP_CIPHER_CTX_mode(e) ((e)->cipher->flags & EVP_CIPH_MODE) + + int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); + int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); + +=head1 DESCRIPTION + +The EVP cipher routines are a high level interface to certain +symmetric ciphers. + +EVP_EncryptInit() initializes a cipher context B<ctx> for encryption +with cipher B<type>. B<type> is normally supplied by a function such +as EVP_des_cbc() . B<key> is the symmetric key to use and B<iv> is the +IV to use (if necessary), the actual number of bytes used for the +key and IV depends on the cipher. It is possible to set all parameters +to NULL except B<type> in an initial call and supply the remaining +parameters in subsequent calls, all of which have B<type> set to NULL. +This is done when the default cipher parameters are not appropriate. + +EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and +writes the encrypted version to B<out>. This function can be called +multiple times to encrypt successive blocks of data. The amount +of data written depends on the block alignment of the encrypted data: +as a result the amount of data written may be anything from zero bytes +to (inl + cipher_block_size - 1) so B<outl> should contain sufficient +room. The actual number of bytes written is placed in B<outl>. + +EVP_EncryptFinal() encrypts the "final" data, that is any data that +remains in a partial block. It uses L<standard block padding|/NOTES> (aka PKCS +padding). The encrypted final data is written to B<out> which should +have sufficient space for one cipher block. The number of bytes written +is placed in B<outl>. After this function is called the encryption operation +is finished and no further calls to EVP_EncryptUpdate() should be made. + +EVP_DecryptInit(), EVP_DecryptUpdate() and EVP_DecryptFinal() are the +corresponding decryption operations. EVP_DecryptFinal() will return an +error code if the final block is not correctly formatted. The parameters +and restrictions are identical to the encryption operations except that +the decrypted data buffer B<out> passed to EVP_DecryptUpdate() should +have sufficient room for (B<inl> + cipher_block_size) bytes unless the +cipher block size is 1 in which case B<inl> bytes is sufficient. + +EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal() are functions +that can be used for decryption or encryption. The operation performed +depends on the value of the B<enc> parameter. It should be set to 1 for +encryption, 0 for decryption and -1 to leave the value unchanged (the +actual value of 'enc' being supplied in a previous call). + +EVP_CIPHER_CTX_cleanup() clears all information from a cipher context. +It should be called after all operations using a cipher are complete +so sensitive information does not remain in memory. + +EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() +return an EVP_CIPHER structure when passed a cipher name, a NID or an +ASN1_OBJECT structure. + +EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when +passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> structure. The actual NID +value is an internal value which may not have a corresponding OBJECT +IDENTIFIER. + +EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key +length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> +structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length +for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a +given cipher, the value of EVP_CIPHER_CTX_key_length() may be different +for variable key length ciphers. + +EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx. +If the cipher is a fixed length cipher then attempting to set the key +length to any value other than the fixed value is an error. + +EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV +length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>. +It will return zero if the cipher does not use an IV. The constant +B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers. + +EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block +size of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> +structure. The constant B<EVP_MAX_IV_LENGTH> is also the maximum block +length for all ciphers. + +EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed +cipher or context. This "type" is the actual NID of the cipher OBJECT +IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and +128 bit RC2 have the same NID. If the cipher does not have an object +identifier or does not have ASN1 support this function will return +B<NID_undef>. + +EVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed +an B<EVP_CIPHER_CTX> structure. + +EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode: +EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE or +EVP_CIPH_OFB_MODE. If the cipher is a stream cipher then +EVP_CIPH_STREAM_CIPHER is returned. + +EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based +on the passed cipher. This will typically include any parameters and an +IV. The cipher IV (if any) must be set when this call is made. This call +should be made before the cipher is actually "used" (before any +EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function +may fail if the cipher does not have any ASN1 support. + +EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1 +AlgorithmIdentifier "parameter". The precise effect depends on the cipher +In the case of RC2, for example, it will set the IV and effective key length. +This function should be called after the base cipher type is set but before +the key is set. For example EVP_CipherInit() will be called with the IV and +key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally +EVP_CipherInit() again with all parameters except the key set to NULL. It is +possible for this function to fail if the cipher does not have any ASN1 support +or the parameters cannot be set (for example the RC2 effective key length +is not supported. + +EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined +and set. Currently only the RC2 effective key length and the number of rounds of +RC5 can be set. + +=head1 RETURN VALUES + +EVP_EncryptInit(), EVP_EncryptUpdate() and EVP_EncryptFinal() return 1 for success +and 0 for failure. + +EVP_DecryptInit() and EVP_DecryptUpdate() return 1 for success and 0 for failure. +EVP_DecryptFinal() returns 0 if the decrypt failed or 1 for success. + +EVP_CipherInit() and EVP_CipherUpdate() return 1 for success and 0 for failure. +EVP_CipherFinal() returns 1 for a decryption failure or 1 for success. + +EVP_CIPHER_CTX_cleanup() returns 1 for success and 0 for failure. + +EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() +return an B<EVP_CIPHER> structure or NULL on error. + +EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID. + +EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block +size. + +EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key +length. + +EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV +length or zero if the cipher does not use an IV. + +EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's +OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER. + +EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure. + +EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for +success or zero for failure. + +=head1 CIPHER LISTING + +All algorithms have a fixed key length unless otherwise stated. + +=over 4 + +=item EVP_enc_null() + +Null cipher: does nothing. + +=item EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void) + +DES in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), EVP_des_ede_cfb(void) + +Two key triple DES in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void), EVP_des_ede3_cfb(void) + +Three key triple DES in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_desx_cbc(void) + +DESX algorithm in CBC mode. + +=item EVP_rc4(void) + +RC4 stream cipher. This is a variable key length cipher with default key length 128 bits. + +=item EVP_rc4_40(void) + +RC4 stream cipher with 40 bit key length. This is obsolete and new code should use EVP_rc4() +and the EVP_CIPHER_CTX_set_key_length() function. + +=item EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void), EVP_idea_cbc(void) + +IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void) + +RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key +length cipher with an additional parameter called "effective key bits" or "effective key length". +By default both are set to 128 bits. + +=item EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void) + +RC2 algorithm in CBC mode with a default key length and effective key length of 40 and 64 bits. +These are obsolete and new code should use EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() and +EVP_CIPHER_CTX_ctrl() to set the key length and effective key length. + +=item EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void); + +Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key +length cipher. + +=item EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void) + +CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key +length cipher. + +=item EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void) + +RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length +cipher with an additional "number of rounds" parameter. By default the key length is set to 128 +bits and 12 rounds. + +=back + +=head1 NOTES + +Where possible the B<EVP> interface to symmetric ciphers should be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the cipher used and much more flexible. + +PKCS padding works by adding B<n> padding bytes of value B<n> to make the total +length of the encrypted data a multiple of the block size. Padding is always +added so if the data is already a multiple of the block size B<n> will equal +the block size. For example if the block size is 8 and 11 bytes are to be +encrypted then 5 padding bytes of value 5 will be added. + +When decrypting the final block is checked to see if it has the correct form. + +Although the decryption operation can produce an error, it is not a strong +test that the input data or key is correct. A random block has better than +1 in 256 chance of being of the correct format and problems with the +input data earlier on will not produce a final decrypt error. + +The functions EVP_EncryptInit(), EVP_EncryptUpdate(), EVP_EncryptFinal(), +EVP_DecryptInit(), EVP_DecryptUpdate(), EVP_CipherInit() and EVP_CipherUpdate() +and EVP_CIPHER_CTX_cleanup() did not return errors in OpenSSL version 0.9.5a or +earlier. Software only versions of encryption algorithms will never return +error codes for these functions, unless there is a programming error (for example +and attempt to set the key before the cipher is set in EVP_EncryptInit() ). + +=head1 BUGS + +For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is +a limitation of the current RC5 code rather than the EVP interface. + +It should be possible to disable PKCS padding: currently it isn't. + +EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with +default key lengths. If custom ciphers exceed these values the results are +unpredictable. This is because it has become standard practice to define a +generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes. + +The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested +for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode. + +=head1 EXAMPLES + +Get the number of rounds used in RC5: + + int nrounds; + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &i); + +Get the RC2 effective key length: + + int key_bits; + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &i); + +Set the number of rounds used in RC5: + + int nrounds; + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, i, NULL); + +Set the number of rounds used in RC2: + + int nrounds; + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, i, NULL); + +=head1 SEE ALSO + +L<evp(3)|evp(3)> + +=head1 HISTORY + +=cut diff --git a/crypto/openssl/doc/crypto/EVP_OpenInit.pod b/crypto/openssl/doc/crypto/EVP_OpenInit.pod new file mode 100644 index 0000000..2e710da --- /dev/null +++ b/crypto/openssl/doc/crypto/EVP_OpenInit.pod @@ -0,0 +1,63 @@ +=pod + +=head1 NAME + +EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal - EVP envelope decryption + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek, + int ekl,unsigned char *iv,EVP_PKEY *priv); + int EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl, unsigned char *in, int inl); + int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl); + +=head1 DESCRIPTION + +The EVP envelope routines are a high level interface to envelope +decryption. They decrypt a public key encrypted symmetric key and +then decrypt data using it. + +EVP_OpenInit() initializes a cipher context B<ctx> for decryption +with cipher B<type>. It decrypts the encrypted symmetric key of length +B<ekl> bytes passed in the B<ek> parameter using the private key B<priv>. +The IV is supplied in the B<iv> parameter. + +EVP_OpenUpdate() and EVP_OpenFinal() have exactly the same properties +as the EVP_DecryptUpdate() and EVP_DecryptFinal() routines, as +documented on the L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> manual +page. + +=head1 NOTES + +It is possible to call EVP_OpenInit() twice in the same way as +EVP_DecryptInit(). The first call should have B<priv> set to NULL +and (after setting any cipher parameters) it should be called again +with B<type> set to NULL. + +If the cipher passed in the B<type> parameter is a variable length +cipher then the key length will be set to the value of the recovered +key length. If the cipher is a fixed length cipher then the recovered +key length must match the fixed cipher length. + +=head1 RETURN VALUES + +EVP_OpenInit() returns 0 on error or a non zero integer (actually the +recovered secret key size) if successful. + +EVP_OpenUpdate() returns 1 for success or 0 for failure. + +EVP_OpenFinal() returns 0 if the decrypt failed or 1 for success. + +=head1 SEE ALSO + +L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, +L<EVP_SealInit(3)|EVP_SealInit(3)> + +=head1 HISTORY + +=cut diff --git a/crypto/openssl/doc/crypto/EVP_SealInit.pod b/crypto/openssl/doc/crypto/EVP_SealInit.pod new file mode 100644 index 0000000..0451eb6 --- /dev/null +++ b/crypto/openssl/doc/crypto/EVP_SealInit.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + +EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek, + int *ekl, unsigned char *iv,EVP_PKEY **pubk, int npubk); + int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl, unsigned char *in, int inl); + int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl); + +=head1 DESCRIPTION + +The EVP envelope routines are a high level interface to envelope +encryption. They generate a random key and then "envelope" it by +using public key encryption. Data can then be encrypted using this +key. + +EVP_SealInit() initializes a cipher context B<ctx> for encryption +with cipher B<type> using a random secret key and IV supplied in +the B<iv> parameter. B<type> is normally supplied by a function such +as EVP_des_cbc(). The secret key is encrypted using one or more public +keys, this allows the same encrypted data to be decrypted using any +of the corresponding private keys. B<ek> is an array of buffers where +the public key encrypted secret key will be written, each buffer must +contain enough room for the corresponding encrypted key: that is +B<ek[i]> must have room for B<EVP_PKEY_size(pubk[i])> bytes. The actual +size of each encrypted secret key is written to the array B<ekl>. B<pubk> is +an array of B<npubk> public keys. + +EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties +as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as +documented on the L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> manual +page. + +=head1 RETURN VALUES + +EVP_SealInit() returns 0 on error or B<npubk> if successful. + +EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for +failure. + +=head1 NOTES + +Because a random secret key is generated the random number generator +must be seeded before calling EVP_SealInit(). + +The public key must be RSA because it is the only OpenSSL public key +algorithm that supports key transport. + +Envelope encryption is the usual method of using public key encryption +on large amounts of data, this is because public key encryption is slow +but symmetric encryption is fast. So symmetric encryption is used for +bulk encryption and the small random symmetric key used is transferred +using public key encryption. + +It is possible to call EVP_SealInit() twice in the same way as +EVP_EncryptInit(). The first call should have B<npubk> set to 0 +and (after setting any cipher parameters) it should be called again +with B<type> set to NULL. + +=head1 SEE ALSO + +L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, +L<EVP_OpenInit(3)|EVP_OpenInit(3)> + +=head1 HISTORY + +=cut diff --git a/crypto/openssl/doc/crypto/EVP_SignInit.pod b/crypto/openssl/doc/crypto/EVP_SignInit.pod new file mode 100644 index 0000000..7f9265d --- /dev/null +++ b/crypto/openssl/doc/crypto/EVP_SignInit.pod @@ -0,0 +1,85 @@ +=pod + +=head1 NAME + +EVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); + void EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s, EVP_PKEY *pkey); + + int EVP_PKEY_size(EVP_PKEY *pkey); + +=head1 DESCRIPTION + +The EVP signature routines are a high level interface to digital +signatures. + +EVP_SignInit() initializes a signing context B<ctx> to using digest +B<type>: this will typically be supplied by a function such as +EVP_sha1(). + +EVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the +signature context B<ctx>. This function can be called several times on the +same B<ctx> to include additional data. + +EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> +and places the signature in B<sig>. If the B<s> parameter is not NULL +then the number of bytes of data written (i.e. the length of the signature) +will be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes +will be written. After calling EVP_SignFinal() no additional calls to +EVP_SignUpdate() can be made, but EVP_SignInit() can be called to initialize +a new signature operation. + +EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual +signature returned by EVP_SignFinal() may be smaller. + +=head1 RETURN VALUES + +EVP_SignInit() and EVP_SignUpdate() do not return values. + +EVP_SignFinal() returns 1 for success and 0 for failure. + +EVP_PKEY_size() returns the maximum size of a signature in bytes. + +The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 NOTES + +The B<EVP> interface to digital signatures should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. + +Due to the link between message digests and public key algorithms the correct +digest algorithm must be used with the correct public key type. A list of +algorithms and associated public key algorithms appears in +L<EVP_DigestInit(3)|EVP_DigestInit(3)>. + +When signing with DSA private keys the random number generator must be seeded +or the operation will fail. The random number generator does not need to be +seeded for RSA signatures. + +=head1 BUGS + +Several of the functions do not return values: maybe they should. Although the +internal digest operations will never fail some future hardware based operations +might. + +=head1 SEE ALSO + +L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, +L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, +L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, +L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, +L<sha(3)|sha(3)>, L<digest(1)|digest(1)> + +=head1 HISTORY + +EVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are +available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/EVP_VerifyInit.pod b/crypto/openssl/doc/crypto/EVP_VerifyInit.pod new file mode 100644 index 0000000..736a0f4 --- /dev/null +++ b/crypto/openssl/doc/crypto/EVP_VerifyInit.pod @@ -0,0 +1,72 @@ +=pod + +=head1 NAME + +EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + void EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type); + void EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + int EVP_VerifyFinal(EVP_MD_CTX *ctx,unsigned char *sigbuf, unsigned int siglen,EVP_PKEY *pkey); + +=head1 DESCRIPTION + +The EVP signature verification routines are a high level interface to digital +signatures. + +EVP_VerifyInit() initializes a verification context B<ctx> to using digest +B<type>: this will typically be supplied by a function such as EVP_sha1(). + +EVP_VerifyUpdate() hashes B<cnt> bytes of data at B<d> into the +verification context B<ctx>. This function can be called several times on the +same B<ctx> to include additional data. + +EVP_VerifyFinal() verifies the data in B<ctx> using the public key B<pkey> +and against the B<siglen> bytes at B<sigbuf>. After calling EVP_VerifyFinal() +no additional calls to EVP_VerifyUpdate() can be made, but EVP_VerifyInit() +can be called to initialize a new verification operation. + +=head1 RETURN VALUES + +EVP_VerifyInit() and EVP_VerifyUpdate() do not return values. + +EVP_VerifyFinal() returns 1 for a correct signature, 0 for failure and -1 if some +other error occurred. + +The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 NOTES + +The B<EVP> interface to digital signatures should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. + +Due to the link between message digests and public key algorithms the correct +digest algorithm must be used with the correct public key type. A list of +algorithms and associated public key algorithms appears in +L<EVP_DigestInit(3)|EVP_DigestInit(3)>. + +=head1 BUGS + +Several of the functions do not return values: maybe they should. Although the +internal digest operations will never fail some future hardware based operations +might. + +=head1 SEE ALSO + +L<evp(3)|evp(3)>, +L<EVP_SignInit(3)|EVP_SignInit(3)>, +L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, +L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, +L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, +L<sha(3)|sha(3)>, L<digest(1)|digest(1)> + +=head1 HISTORY + +EVP_VerifyInit(), EVP_VerifyUpdate() and EVP_VerifyFinal() are +available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod b/crypto/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod new file mode 100644 index 0000000..68ea723 --- /dev/null +++ b/crypto/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod @@ -0,0 +1,88 @@ +=pod + +=head1 NAME + +OPENSSL_VERSION_NUMBER, SSLeay SSLeay_version - get OpenSSL version number + +=head1 SYNOPSIS + + #include <openssl/opensslv.h> + #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL + + #include <openssl/crypto.h> + long SSLeay(void); + char *SSLeay_version(int t); + +=head1 DESCRIPTION + +OPENSSL_VERSION_NUMBER is a numeric release version identifier: + + MMNNFFPPS: major minor fix patch status + +The status nibble has one of the values 0 for development, 1 to e for betas +1 to 14, and f for release. + +for example + + 0x000906000 == 0.9.6 dev + 0x000906023 == 0.9.6b beta 3 + 0x00090605f == 0.9.6e release + +Versions prior to 0.9.3 have identifiers E<lt> 0x0930. +Versions between 0.9.3 and 0.9.5 had a version identifier with this +interpretation: + + MMNNFFRBB major minor fix final beta/patch + +for example + + 0x000904100 == 0.9.4 release + 0x000905000 == 0.9.5 dev + +Version 0.9.5a had an interim interpretation that is like the current one, +except the patch level got the highest bit set, to keep continuity. The +number was therefore 0x0090581f. + + +For backward compatibility, SSLEAY_VERSION_NUMBER is also defined. + +SSLeay() returns this number. The return value can be compared to the +macro to make sure that the correct version of the library has been +loaded, especially when using DLLs on Windows systems. + +SSLeay_version() returns different strings depending on B<t>: + +=over 4 + +=item SSLEAY_VERSION +The text variant of the version number and the release date. For example, +"OpenSSL 0.9.5a 1 Apr 2000". + +=item SSLEAY_CFLAGS +The flags given to the C compiler when compiling OpenSSL are returned in a +string. + +=item SSLEAY_PLATFORM +The platform name used when OpenSSL was configured is returned. + +=back + +If the data request isn't available, a text saying that the information is +not available is returned. + +For an unknown B<t>, the text "not available" is returned. + +=head1 RETURN VALUE + +The version number. + +=head1 SEE ALSO + +L<crypto(3)|crypto(3)> + +=head1 HISTORY + +SSLeay() and SSLEAY_VERSION_NUMBER are available in all versions of SSLeay and OpenSSL. +OPENSSL_VERSION_NUMBER is available in all versions of OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/OpenSSL_add_all_algorithms.pod b/crypto/openssl/doc/crypto/OpenSSL_add_all_algorithms.pod new file mode 100644 index 0000000..486c903 --- /dev/null +++ b/crypto/openssl/doc/crypto/OpenSSL_add_all_algorithms.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests - +add algorithms to internal table + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + void OpenSSL_add_all_algorithms(void); + void OpenSSL_add_all_ciphers(void); + void OpenSSL_add_all_digests(void); + + void EVP_cleanup(void); + +=head1 DESCRIPTION + +OpenSSL keeps an internal table of digest algorithms and ciphers. It uses +this table to lookup ciphers via functions such as EVP_get_cipher_byname(). + +OpenSSL_add_all_digests() adds all digest algorithms to the table. + +OpenSSL_add_all_algorithms() adds all algorithms to the table (digests and +ciphers). + +OpenSSL_add_all_ciphers() adds all encryption algorithms to the table including +password based encryption algorithms. + +EVP_cleanup() removes all ciphers and digests from the table. + +=head1 RETURN VALUES + +None of the functions return a value. + +=head1 NOTES + +A typical application will will call OpenSSL_add_all_algorithms() initially and +EVP_cleanup() before exiting. + +An application does not need to add algorithms to use them explicitly, for example +by EVP_sha1(). It just needs to add them if it (or any of the functions it calls) +needs to lookup algorithms. + +The cipher and digest lookup functions are used in many parts of the library. If +the table is not initialized several functions will misbehave and complain they +cannot find algorithms. This includes the PEM, PKCS#12, SSL and S/MIME libraries. +This is a common query in the OpenSSL mailing lists. + +Calling OpenSSL_add_all_algorithms() links in all algorithms: as a result a +statically linked executable can be quite large. If this is important it is possible +to just add the required ciphers and digests. + +=head1 BUGS + +Although the functions do not return error codes it is possible for them to fail. +This will only happen as a result of a memory allocation failure so this is not +too much of a problem in practice. + +=head1 SEE ALSO + +L<evp(3)|evp(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>, +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> + +=cut diff --git a/crypto/openssl/doc/crypto/RAND_add.pod b/crypto/openssl/doc/crypto/RAND_add.pod new file mode 100644 index 0000000..67c66f3 --- /dev/null +++ b/crypto/openssl/doc/crypto/RAND_add.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +RAND_add, RAND_seed, RAND_status, RAND_event, RAND_screen - add +entropy to the PRNG + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + void RAND_seed(const void *buf, int num); + + void RAND_add(const void *buf, int num, double entropy); + + int RAND_status(void); + + int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); + void RAND_screen(void); + +=head1 DESCRIPTION + +RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state. Thus, +if the data at B<buf> are unpredictable to an adversary, this +increases the uncertainty about the state and makes the PRNG output +less predictable. Suitable input comes from user interaction (random +key presses, mouse movements) and certain hardware events. The +B<entropy> argument is (the lower bound of) an estimate of how much +randomness is contained in B<buf>, measured in bytes. Details about +sources of randomness and how to estimate their entropy can be found +in the literature, e.g. RFC 1750. + +RAND_add() may be called with sensitive data such as user entered +passwords. The seed values cannot be recovered from the PRNG output. + +OpenSSL makes sure that the PRNG state is unique for each thread. On +systems that provide C</dev/urandom>, the randomness device is used +to seed the PRNG transparently. However, on all other systems, the +application is responsible for seeding the PRNG by calling RAND_add(), +L<RAND_egd(3)|RAND_egd(3)> +or L<RAND_load_file(3)|RAND_load_file(3)>. + +RAND_seed() is equivalent to RAND_add() when B<num == entropy>. + +RAND_event() collects the entropy from Windows events such as mouse +movements and other user interaction. It should be called with the +B<iMsg>, B<wParam> and B<lParam> arguments of I<all> messages sent to +the window procedure. It will estimate the entropy contained in the +event message (if any), and add it to the PRNG. The program can then +process the messages as usual. + +The RAND_screen() function is available for the convenience of Windows +programmers. It adds the current contents of the screen to the PRNG. +For applications that can catch Windows events, seeding the PRNG by +calling RAND_event() is a significantly better source of +randomness. It should be noted that both methods cannot be used on +servers that run without user interaction. + +=head1 RETURN VALUES + +RAND_status() and RAND_event() return 1 if the PRNG has been seeded +with enough data, 0 otherwise. + +The other functions do not return values. + +=head1 SEE ALSO + +L<rand(3)|rand(3)>, L<RAND_egd(3)|RAND_egd(3)>, +L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> + +=head1 HISTORY + +RAND_seed() and RAND_screen() are available in all versions of SSLeay +and OpenSSL. RAND_add() and RAND_status() have been added in OpenSSL +0.9.5, RAND_event() in OpenSSL 0.9.5a. + +=cut diff --git a/crypto/openssl/doc/crypto/RAND_bytes.pod b/crypto/openssl/doc/crypto/RAND_bytes.pod new file mode 100644 index 0000000..b6ebd50 --- /dev/null +++ b/crypto/openssl/doc/crypto/RAND_bytes.pod @@ -0,0 +1,46 @@ +=pod + +=head1 NAME + +RAND_bytes, RAND_pseudo_bytes - generate random data + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + int RAND_bytes(unsigned char *buf, int num); + + int RAND_pseudo_bytes(unsigned char *buf, int num); + +=head1 DESCRIPTION + +RAND_bytes() puts B<num> cryptographically strong pseudo-random bytes +into B<buf>. An error occurs if the PRNG has not been seeded with +enough randomness to ensure an unpredictable byte sequence. + +RAND_pseudo_bytes() puts B<num> pseudo-random bytes into B<buf>. +Pseudo-random byte sequences generated by RAND_pseudo_bytes() will be +unique if they are of sufficient length, but are not necessarily +unpredictable. They can be used for non-cryptographic purposes and for +certain purposes in cryptographic protocols, but usually not for key +generation etc. + +=head1 RETURN VALUES + +RAND_bytes() returns 1 on success, 0 otherwise. The error code can be +obtained by L<ERR_get_error(3)|ERR_get_error(3)>. RAND_pseudo_bytes() returns 1 if the +bytes generated are cryptographically strong, 0 otherwise. Both +functions return -1 if they are not supported by the current RAND +method. + +=head1 SEE ALSO + +L<rand(3)|rand(3)>, L<err(3)|err(3)>, L<RAND_add(3)|RAND_add(3)> + +=head1 HISTORY + +RAND_bytes() is available in all versions of SSLeay and OpenSSL. It +has a return value since OpenSSL 0.9.5. RAND_pseudo_bytes() was added +in OpenSSL 0.9.5. + +=cut diff --git a/crypto/openssl/doc/crypto/RAND_cleanup.pod b/crypto/openssl/doc/crypto/RAND_cleanup.pod new file mode 100644 index 0000000..3a8f074 --- /dev/null +++ b/crypto/openssl/doc/crypto/RAND_cleanup.pod @@ -0,0 +1,29 @@ +=pod + +=head1 NAME + +RAND_cleanup - erase the PRNG state + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + void RAND_cleanup(void); + +=head1 DESCRIPTION + +RAND_cleanup() erases the memory used by the PRNG. + +=head1 RETURN VALUE + +RAND_cleanup() returns no value. + +=head1 SEE ALSO + +L<rand(3)|rand(3)> + +=head1 HISTORY + +RAND_cleanup() is available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/RAND_egd.pod b/crypto/openssl/doc/crypto/RAND_egd.pod new file mode 100644 index 0000000..40241e2 --- /dev/null +++ b/crypto/openssl/doc/crypto/RAND_egd.pod @@ -0,0 +1,42 @@ +=pod + +=head1 NAME + +RAND_egd - query entropy gathering daemon + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + int RAND_egd(const char *path); + +=head1 DESCRIPTION + +RAND_egd() queries the entropy gathering daemon EGD on socket B<path>. + +EGD is available from http://www.lothar.com/tech/crypto/ (C<perl +Makefile.PL; make; make install> to install). It is run as B<egd> +I<path>, where I<path> is an absolute path designating a socket. When +RAND_egd() is called with that path as an argument, it tries to read +random bytes that EGD has collected. The read is performed in +non-blocking mode. + +Alternatively, the EGD-compatible daemon PRNGD can be used. It is +available from +http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html . + +=head1 RETURN VALUE + +RAND_egd() returns the number of bytes read from the daemon on +success, and -1 if the connection failed or the daemon did not return +enough data to fully seed the PRNG. + +=head1 SEE ALSO + +L<rand(3)|rand(3)>, L<RAND_add(3)|RAND_add(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> + +=head1 HISTORY + +RAND_egd() is available since OpenSSL 0.9.5. + +=cut diff --git a/crypto/openssl/doc/crypto/RAND_load_file.pod b/crypto/openssl/doc/crypto/RAND_load_file.pod new file mode 100644 index 0000000..8dd700c --- /dev/null +++ b/crypto/openssl/doc/crypto/RAND_load_file.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + const char *RAND_file_name(char *buf, int num); + + int RAND_load_file(const char *filename, long max_bytes); + + int RAND_write_file(const char *filename); + +=head1 DESCRIPTION + +RAND_file_name() generates a default path for the random seed +file. B<buf> points to a buffer of size B<num> in which to store the +filename. The seed file is $RANDFILE if that environment variable is +set, $HOME/.rnd otherwise. If $HOME is not set either, or B<num> is +too small for the path name, an error occurs. + +RAND_load_file() reads a number of bytes from file B<filename> and +adds them to the PRNG. If B<max_bytes> is non-negative, +up to to B<max_bytes> are read; starting with OpenSSL 0.9.5, +if B<max_bytes> is -1, the complete file is read. + +RAND_write_file() writes a number of random bytes (currently 1024) to +file B<filename> which can be used to initialize the PRNG by calling +RAND_load_file() in a later session. + +=head1 RETURN VALUES + +RAND_load_file() returns the number of bytes read. + +RAND_write_file() returns the number of bytes written, and -1 if the +bytes written were generated without appropriate seed. + +RAND_file_name() returns a pointer to B<buf> on success, and NULL on +error. + +=head1 SEE ALSO + +L<rand(3)|rand(3)>, L<RAND_add(3)|RAND_add(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> + +=head1 HISTORY + +RAND_load_file(), RAND_write_file() and RAND_file_name() are available in +all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/RAND_set_rand_method.pod b/crypto/openssl/doc/crypto/RAND_set_rand_method.pod new file mode 100644 index 0000000..464eba4 --- /dev/null +++ b/crypto/openssl/doc/crypto/RAND_set_rand_method.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +RAND_set_rand_method, RAND_get_rand_method, RAND_SSLeay - select RAND method + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + void RAND_set_rand_method(RAND_METHOD *meth); + + RAND_METHOD *RAND_get_rand_method(void); + + RAND_METHOD *RAND_SSLeay(void); + +=head1 DESCRIPTION + +A B<RAND_METHOD> specifies the functions that OpenSSL uses for random +number generation. By modifying the method, alternative +implementations such as hardware RNGs may be used. Initially, the +default is to use the OpenSSL internal implementation. RAND_SSLeay() +returns a pointer to that method. + +RAND_set_rand_method() sets the RAND method to B<meth>. +RAND_get_rand_method() returns a pointer to the current method. + +=head1 THE RAND_METHOD STRUCTURE + + typedef struct rand_meth_st + { + void (*seed)(const void *buf, int num); + int (*bytes)(unsigned char *buf, int num); + void (*cleanup)(void); + void (*add)(const void *buf, int num, int entropy); + int (*pseudorand)(unsigned char *buf, int num); + int (*status)(void); + } RAND_METHOD; + +The components point to the implementation of RAND_seed(), +RAND_bytes(), RAND_cleanup(), RAND_add(), RAND_pseudo_rand() +and RAND_status(). +Each component may be NULL if the function is not implemented. + +=head1 RETURN VALUES + +RAND_set_rand_method() returns no value. RAND_get_rand_method() and +RAND_SSLeay() return pointers to the respective methods. + +=head1 SEE ALSO + +L<rand(3)|rand(3)> + +=head1 HISTORY + +RAND_set_rand_method(), RAND_get_rand_method() and RAND_SSLeay() are +available in all versions of OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/RSA_blinding_on.pod b/crypto/openssl/doc/crypto/RSA_blinding_on.pod new file mode 100644 index 0000000..fd2c69a --- /dev/null +++ b/crypto/openssl/doc/crypto/RSA_blinding_on.pod @@ -0,0 +1,43 @@ +=pod + +=head1 NAME + +RSA_blinding_on, RSA_blinding_off - protect the RSA operation from timing attacks + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); + + void RSA_blinding_off(RSA *rsa); + +=head1 DESCRIPTION + +RSA is vulnerable to timing attacks. In a setup where attackers can +measure the time of RSA decryption or signature operations, blinding +must be used to protect the RSA operation from that attack. + +RSA_blinding_on() turns blinding on for key B<rsa> and generates a +random blinding factor. B<ctx> is B<NULL> or a pre-allocated and +initialized B<BN_CTX>. The random number generator must be seeded +prior to calling RSA_blinding_on(). + +RSA_blinding_off() turns blinding off and frees the memory used for +the blinding factor. + +=head1 RETURN VALUES + +RSA_blinding_on() returns 1 on success, and 0 if an error occurred. + +RSA_blinding_off() returns no value. + +=head1 SEE ALSO + +L<rsa(3)|rsa(3)>, L<rand(3)|rand(3)> + +=head1 HISTORY + +RSA_blinding_on() and RSA_blinding_off() appeared in SSLeay 0.9.0. + +=cut diff --git a/crypto/openssl/doc/crypto/RSA_check_key.pod b/crypto/openssl/doc/crypto/RSA_check_key.pod new file mode 100644 index 0000000..79fed75 --- /dev/null +++ b/crypto/openssl/doc/crypto/RSA_check_key.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +RSA_check_key - validate private RSA keys + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_check_key(RSA *rsa); + +=head1 DESCRIPTION + +This function validates RSA keys. It checks that B<p> and B<q> are +in fact prime, and that B<n = p*q>. + +It also checks that B<d*e = 1 mod (p-1*q-1)>, +and that B<dmp1>, B<dmq1> and B<iqmp> are set correctly or are B<NULL>. + +The key's public components may not be B<NULL>. + +=head1 RETURN VALUE + +RSA_check_key() returns 1 if B<rsa> is a valid RSA key, and 0 otherwise. +-1 is returned if an error occurs while checking the key. + +If the key is invalid or an error occurred, the reason code can be +obtained using L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<rsa(3)|rsa(3)>, L<err(3)|err(3)> + +=head1 HISTORY + +RSA_check() appeared in OpenSSL 0.9.4. + +=cut diff --git a/crypto/openssl/doc/crypto/RSA_generate_key.pod b/crypto/openssl/doc/crypto/RSA_generate_key.pod new file mode 100644 index 0000000..fdaddbc --- /dev/null +++ b/crypto/openssl/doc/crypto/RSA_generate_key.pod @@ -0,0 +1,68 @@ +=pod + +=head1 NAME + +RSA_generate_key - generate RSA key pair + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + RSA *RSA_generate_key(int num, unsigned long e, + void (*callback)(int,int,void *), void *cb_arg); + +=head1 DESCRIPTION + +RSA_generate_key() generates a key pair and returns it in a newly +allocated B<RSA> structure. The pseudo-random number generator must +be seeded prior to calling RSA_generate_key(). + +The modulus size will be B<num> bits, and the public exponent will be +B<e>. Key sizes with B<num> E<lt> 1024 should be considered insecure. +The exponent is an odd number, typically 3 or 65535. + +A callback function may be used to provide feedback about the +progress of the key generation. If B<callback> is not B<NULL>, it +will be called as follows: + +=over 4 + +=item * + +While a random prime number is generated, it is called as +described in L<BN_generate_prime(3)|BN_generate_prime(3)>. + +=item * + +When the n-th randomly generated prime is rejected as not +suitable for the key, B<callback(2, n, cb_arg)> is called. + +=item * + +When a random p has been found with p-1 relatively prime to B<e>, +it is called as B<callback(3, 0, cb_arg)>. + +=back + +The process is then repeated for prime q with B<callback(3, 1, cb_arg)>. + +=head1 RETURN VALUE + +If key generation fails, RSA_generate_key() returns B<NULL>; the +error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 BUGS + +B<callback(2, x, cb_arg)> is used with two different meanings. + +RSA_generate_key() goes into an infinite loop for illegal input values. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<RSA_free(3)|RSA_free(3)> + +=head1 HISTORY + +The B<cb_arg> argument was added in SSLeay 0.9.0. + +=cut diff --git a/crypto/openssl/doc/crypto/RSA_get_ex_new_index.pod b/crypto/openssl/doc/crypto/RSA_get_ex_new_index.pod new file mode 100644 index 0000000..46cc8f5 --- /dev/null +++ b/crypto/openssl/doc/crypto/RSA_get_ex_new_index.pod @@ -0,0 +1,120 @@ +=pod + +=head1 NAME + +RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application specific data to RSA structures + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + int RSA_set_ex_data(RSA *r, int idx, void *arg); + + void *RSA_get_ex_data(RSA *r, int idx); + + typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, + int idx, long argl, void *argp); + +=head1 DESCRIPTION + +Several OpenSSL structures can have application specific data attached to them. +This has several potential uses, it can be used to cache data associated with +a structure (for example the hash of some part of the structure) or some +additional data (for example a handle to the data in an external library). + +Since the application data can be anything at all it is passed and retrieved +as a B<void *> type. + +The B<RSA_get_ex_new_index()> function is initially called to "register" some +new application specific data. It takes three optional function pointers which +are called when the parent structure (in this case an RSA structure) is +initially created, when it is copied and when it is freed up. If any or all of +these function pointer arguments are not used they should be set to NULL. The +precise manner in which these function pointers are called is described in more +detail below. B<RSA_get_ex_new_index()> also takes additional long and pointer +parameters which will be passed to the supplied functions but which otherwise +have no special meaning. It returns an B<index> which should be stored +(typically in a static variable) and passed used in the B<idx> parameter in +the remaining functions. Each successful call to B<RSA_get_ex_new_index()> +will return an index greater than any previously returned, this is important +because the optional functions are called in order of increasing index value. + +B<RSA_set_ex_data()> is used to set application specific data, the data is +supplied in the B<arg> parameter and its precise meaning is up to the +application. + +B<RSA_get_ex_data()> is used to retrieve application specific data. The data +is returned to the application, this will be the same value as supplied to +a previous B<RSA_set_ex_data()> call. + +B<new_func()> is called when a structure is initially allocated (for example +with B<RSA_new()>. The parent structure members will not have any meaningful +values at this point. This function will typically be used to allocate any +application specific structure. + +B<free_func()> is called when a structure is being freed up. The dynamic parent +structure members should not be accessed because they will be freed up when +this function is called. + +B<new_func()> and B<free_func()> take the same parameters. B<parent> is a +pointer to the parent RSA structure. B<ptr> is a the application specific data +(this wont be of much use in B<new_func()>. B<ad> is a pointer to the +B<CRYPTO_EX_DATA> structure from the parent RSA structure: the functions +B<CRYPTO_get_ex_data()> and B<CRYPTO_set_ex_data()> can be called to manipulate +it. The B<idx> parameter is the index: this will be the same value returned by +B<RSA_get_ex_new_index()> when the functions were initially registered. Finally +the B<argl> and B<argp> parameters are the values originally passed to the same +corresponding parameters when B<RSA_get_ex_new_index()> was called. + +B<dup_func()> is called when a structure is being copied. Pointers to the +destination and source B<CRYPTO_EX_DATA> structures are passed in the B<to> and +B<from> parameters respectively. The B<from_d> parameter is passed a pointer to +the source application data when the function is called, when the function returns +the value is copied to the destination: the application can thus modify the data +pointed to by B<from_d> and have different values in the source and destination. +The B<idx>, B<argl> and B<argp> parameters are the same as those in B<new_func()> +and B<free_func()>. + +=head1 RETURN VALUES + +B<RSA_get_ex_new_index()> returns a new index or -1 on failure (note 0 is a valid +index value). + +B<RSA_set_ex_data()> returns 1 on success or 0 on failure. + +B<RSA_get_ex_data()> returns the application data or 0 on failure. 0 may also +be valid application data but currently it can only fail if given an invalid B<idx> +parameter. + +B<new_func()> and B<dup_func()> should return 0 for failure and 1 for success. + +On failure an error code can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 BUGS + +B<dup_func()> is currently never called. + +The return value of B<new_func()> is ignored. + +The B<new_func()> function isn't very useful because no meaningful values are +present in the parent RSA structure when it is called. + +=head1 SEE ALSO + +L<rsa(3)|rsa(3)>, L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> + +=head1 HISTORY + +RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() are +available since SSLeay 0.9.0. + +=cut diff --git a/crypto/openssl/doc/crypto/RSA_new.pod b/crypto/openssl/doc/crypto/RSA_new.pod new file mode 100644 index 0000000..f16490e --- /dev/null +++ b/crypto/openssl/doc/crypto/RSA_new.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + +RSA_new, RSA_free - allocate and free RSA objects + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + RSA * RSA_new(void); + + void RSA_free(RSA *rsa); + +=head1 DESCRIPTION + +RSA_new() allocates and initializes an B<RSA> structure. + +RSA_free() frees the B<RSA> structure and its components. The key is +erased before the memory is returned to the system. + +=head1 RETURN VALUES + +If the allocation fails, RSA_new() returns B<NULL> and sets an error +code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns +a pointer to the newly allocated structure. + +RSA_free() returns no value. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<rsa(3)|rsa(3)>, L<RSA_generate_key(3)|RSA_generate_key(3)> + +=head1 HISTORY + +RSA_new() and RSA_free() are available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/RSA_padding_add_PKCS1_type_1.pod b/crypto/openssl/doc/crypto/RSA_padding_add_PKCS1_type_1.pod new file mode 100644 index 0000000..b8f678f --- /dev/null +++ b/crypto/openssl/doc/crypto/RSA_padding_add_PKCS1_type_1.pod @@ -0,0 +1,124 @@ +=pod + +=head1 NAME + +RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1, +RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2, +RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP, +RSA_padding_add_SSLv23, RSA_padding_check_SSLv23, +RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption +padding + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen, + unsigned char *f, int fl); + + int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen, + unsigned char *f, int fl, int rsa_len); + + int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen, + unsigned char *f, int fl); + + int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen, + unsigned char *f, int fl, int rsa_len); + + int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen, + unsigned char *f, int fl, unsigned char *p, int pl); + + int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen, + unsigned char *f, int fl, int rsa_len, unsigned char *p, int pl); + + int RSA_padding_add_SSLv23(unsigned char *to, int tlen, + unsigned char *f, int fl); + + int RSA_padding_check_SSLv23(unsigned char *to, int tlen, + unsigned char *f, int fl, int rsa_len); + + int RSA_padding_add_none(unsigned char *to, int tlen, + unsigned char *f, int fl); + + int RSA_padding_check_none(unsigned char *to, int tlen, + unsigned char *f, int fl, int rsa_len); + +=head1 DESCRIPTION + +The RSA_padding_xxx_xxx() functions are called from the RSA encrypt, +decrypt, sign and verify functions. Normally they should not be called +from application programs. + +However, they can also be called directly to implement padding for other +asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and +RSA_padding_check_PKCS1_OAEP() may be used in an application combined +with B<RSA_NO_PADDING> in order to implement OAEP with an encoding +parameter. + +RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into +B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl> +does not meet the size requirements of the encoding method. + +The following encoding methods are implemented: + +=over 4 + +=item PKCS1_type_1 + +PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures + +=item PKCS1_type_2 + +PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2) + +=item PKCS1_OAEP + +PKCS #1 v2.0 EME-OAEP + +=item SSLv23 + +PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification + +=item none + +simply copy the data + +=back + +The random number generator must be seeded prior to calling +RSA_padding_add_xxx(). + +RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain +a valid encoding for a B<rsa_len> byte RSA key in the respective +encoding method and stores the recovered data of at most B<tlen> bytes +(for B<RSA_NO_PADDING>: of size B<tlen>) +at B<to>. + +For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter +of length B<pl>. B<p> may be B<NULL> if B<pl> is 0. + +=head1 RETURN VALUES + +The RSA_padding_add_xxx() functions return 1 on success, 0 on error. +The RSA_padding_check_xxx() functions return the length of the +recovered data, -1 on error. Error codes can be obtained by calling +L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>, +L<RSA_private_decrypt(3)|RSA_private_decrypt(3)>, +L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)> + +=head1 HISTORY + +RSA_padding_add_PKCS1_type_1(), RSA_padding_check_PKCS1_type_1(), +RSA_padding_add_PKCS1_type_2(), RSA_padding_check_PKCS1_type_2(), +RSA_padding_add_SSLv23(), RSA_padding_check_SSLv23(), +RSA_padding_add_none() and RSA_padding_check_none() appeared in +SSLeay 0.9.0. + +RSA_padding_add_PKCS1_OAEP() and RSA_padding_check_PKCS1_OAEP() were +added in OpenSSL 0.9.2b. + +=cut diff --git a/crypto/openssl/doc/crypto/RSA_print.pod b/crypto/openssl/doc/crypto/RSA_print.pod new file mode 100644 index 0000000..67876fa --- /dev/null +++ b/crypto/openssl/doc/crypto/RSA_print.pod @@ -0,0 +1,49 @@ +=pod + +=head1 NAME + +RSA_print, RSA_print_fp, DHparams_print, DHparams_print_fp, DSA_print, +DSA_print_fp, DHparams_print, DHparams_print_fp - print cryptographic +parameters + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_print(BIO *bp, RSA *x, int offset); + int RSA_print_fp(FILE *fp, RSA *x, int offset); + + #include <openssl/dsa.h> + + int DSAparams_print(BIO *bp, DSA *x); + int DSAparams_print_fp(FILE *fp, DSA *x); + int DSA_print(BIO *bp, DSA *x, int offset); + int DSA_print_fp(FILE *fp, DSA *x, int offset); + + #include <openssl/dh.h> + + int DHparams_print(BIO *bp, DH *x); + int DHparams_print_fp(FILE *fp, DH *x); + +=head1 DESCRIPTION + +A human-readable hexadecimal output of the components of the RSA +key, DSA parameters or key or DH parameters is printed to B<bp> or B<fp>. + +The output lines are indented by B<offset> spaces. + +=head1 RETURN VALUES + +These functions return 1 on success, 0 on error. + +=head1 SEE ALSO + +L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)> + +=head1 HISTORY + +RSA_print(), RSA_print_fp(), DSA_print(), DSA_print_fp(), DH_print(), +DH_print_fp() are available in all versions of SSLeay and OpenSSL. +DSAparams_print() and DSAparams_print_pf() were added in SSLeay 0.8. + +=cut diff --git a/crypto/openssl/doc/crypto/RSA_private_encrypt.pod b/crypto/openssl/doc/crypto/RSA_private_encrypt.pod new file mode 100644 index 0000000..6861a98 --- /dev/null +++ b/crypto/openssl/doc/crypto/RSA_private_encrypt.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + +RSA_private_encrypt, RSA_public_decrypt - low level signature operations + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_private_encrypt(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + int RSA_public_decrypt(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + +=head1 DESCRIPTION + +These functions handle RSA signatures at a low level. + +RSA_private_encrypt() signs the B<flen> bytes at B<from> (usually a +message digest with an algorithm identifier) using the private key +B<rsa> and stores the signature in B<to>. B<to> must point to +B<RSA_size(rsa)> bytes of memory. + +B<padding> denotes one of the following modes: + +=over 4 + +=item RSA_PKCS1_PADDING + +PKCS #1 v1.5 padding. This function does not handle the +B<algorithmIdentifier> specified in PKCS #1. When generating or +verifying PKCS #1 signatures, L<RSA_sign(3)|RSA_sign(3)> and L<RSA_verify(3)|RSA_verify(3)> should be +used. + +=item RSA_NO_PADDING + +Raw RSA signature. This mode should I<only> be used to implement +cryptographically sound padding modes in the application code. +Signing user data directly with RSA is insecure. + +=back + +RSA_public_decrypt() recovers the message digest from the B<flen> +bytes long signature at B<from> using the signer's public key +B<rsa>. B<to> must point to a memory section large enough to hold the +message digest (which is smaller than B<RSA_size(rsa) - +11>). B<padding> is the padding mode that was used to sign the data. + +=head1 RETURN VALUES + +RSA_private_encrypt() returns the size of the signature (i.e., +RSA_size(rsa)). RSA_public_decrypt() returns the size of the +recovered message digest. + +On error, -1 is returned; the error codes can be +obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<rsa(3)|rsa(3)>, L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)> + +=head1 HISTORY + +The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is +available since SSLeay 0.9.0. + +=cut diff --git a/crypto/openssl/doc/crypto/RSA_public_encrypt.pod b/crypto/openssl/doc/crypto/RSA_public_encrypt.pod new file mode 100644 index 0000000..02edb7a --- /dev/null +++ b/crypto/openssl/doc/crypto/RSA_public_encrypt.pod @@ -0,0 +1,86 @@ +=pod + +=head1 NAME + +RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_public_encrypt(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + int RSA_private_decrypt(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + +=head1 DESCRIPTION + +RSA_public_encrypt() encrypts the B<flen> bytes at B<from> (usually a +session key) using the public key B<rsa> and stores the ciphertext in +B<to>. B<to> must point to RSA_size(B<rsa>) bytes of memory. + +B<padding> denotes one of the following modes: + +=over 4 + +=item RSA_PKCS1_PADDING + +PKCS #1 v1.5 padding. This currently is the most widely used mode. + +=item RSA_PKCS1_OAEP_PADDING + +EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty +encoding parameter. This mode is recommended for all new applications. + +=item RSA_SSLV23_PADDING + +PKCS #1 v1.5 padding with an SSL-specific modification that denotes +that the server is SSL3 capable. + +=item RSA_NO_PADDING + +Raw RSA encryption. This mode should I<only> be used to implement +cryptographically sound padding modes in the application code. +Encrypting user data directly with RSA is insecure. + +=back + +B<flen> must be less than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5 +based padding modes, and less than RSA_size(B<rsa>) - 41 for +RSA_PKCS1_OAEP_PADDING. The random number generator must be seeded +prior to calling RSA_public_encrypt(). + +RSA_private_decrypt() decrypts the B<flen> bytes at B<from> using the +private key B<rsa> and stores the plaintext in B<to>. B<to> must point +to a memory section large enough to hold the decrypted data (which is +smaller than RSA_size(B<rsa>)). B<padding> is the padding mode that +was used to encrypt the data. + +=head1 RETURN VALUES + +RSA_public_encrypt() returns the size of the encrypted data (i.e., +RSA_size(B<rsa>)). RSA_private_decrypt() returns the size of the +recovered plaintext. + +On error, -1 is returned; the error codes can be +obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 CONFORMING TO + +SSL, PKCS #1 v2.0 + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<RSA_size(3)|RSA_size(3)> + +=head1 NOTES + +The L<RSA_PKCS1_RSAref(3)|RSA_PKCS1_RSAref(3)> method supports only the RSA_PKCS1_PADDING mode. + +=head1 HISTORY + +The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is +available since SSLeay 0.9.0, OAEP was added in OpenSSL 0.9.2b. + +=cut diff --git a/crypto/openssl/doc/crypto/RSA_set_method.pod b/crypto/openssl/doc/crypto/RSA_set_method.pod new file mode 100644 index 0000000..c1a5b39 --- /dev/null +++ b/crypto/openssl/doc/crypto/RSA_set_method.pod @@ -0,0 +1,154 @@ +=pod + +=head1 NAME + +RSA_set_default_method, RSA_get_default_method, RSA_set_method, +RSA_get_method, RSA_PKCS1_SSLeay, RSA_PKCS1_RSAref, +RSA_null_method, RSA_flags, RSA_new_method - select RSA method + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + void RSA_set_default_method(RSA_METHOD *meth); + + RSA_METHOD *RSA_get_default_method(void); + + RSA_METHOD *RSA_set_method(RSA *rsa, RSA_METHOD *meth); + + RSA_METHOD *RSA_get_method(RSA *rsa); + + RSA_METHOD *RSA_PKCS1_SSLeay(void); + + RSA_METHOD *RSA_PKCS1_RSAref(void); + + RSA_METHOD *RSA_null_method(void); + + int RSA_flags(RSA *rsa); + + RSA *RSA_new_method(RSA_METHOD *method); + +=head1 DESCRIPTION + +An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA +operations. By modifying the method, alternative implementations +such as hardware accelerators may be used. + +Initially, the default is to use the OpenSSL internal implementation, +unless OpenSSL was configured with the C<rsaref> or C<-DRSA_NULL> +options. RSA_PKCS1_SSLeay() returns a pointer to that method. + +RSA_PKCS1_RSAref() returns a pointer to a method that uses the RSAref +library. This is the default method in the C<rsaref> configuration; +the function is not available in other configurations. +RSA_null_method() returns a pointer to a method that does not support +the RSA transformation. It is the default if OpenSSL is compiled with +C<-DRSA_NULL>. These methods may be useful in the USA because of a +patent on the RSA cryptosystem. + +RSA_set_default_method() makes B<meth> the default method for all B<RSA> +structures created later. + +RSA_get_default_method() returns a pointer to the current default +method. + +RSA_set_method() selects B<meth> for all operations using the key +B<rsa>. + +RSA_get_method() returns a pointer to the method currently selected +for B<rsa>. + +RSA_flags() returns the B<flags> that are set for B<rsa>'s current method. + +RSA_new_method() allocates and initializes an B<RSA> structure so that +B<method> will be used for the RSA operations. If B<method> is B<NULL>, +the default method is used. + +=head1 THE RSA_METHOD STRUCTURE + + typedef struct rsa_meth_st + { + /* name of the implementation */ + const char *name; + + /* encrypt */ + int (*rsa_pub_enc)(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + /* verify arbitrary data */ + int (*rsa_pub_dec)(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + /* sign arbitrary data */ + int (*rsa_priv_enc)(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + /* decrypt */ + int (*rsa_priv_dec)(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some + implementations) */ + int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa); + + /* compute r = a ^ p mod m (May be NULL for some implementations) */ + int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); + + /* called at RSA_new */ + int (*init)(RSA *rsa); + + /* called at RSA_free */ + int (*finish)(RSA *rsa); + + /* RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key + * operations, even if p,q,dmp1,dmq1,iqmp + * are NULL + * RSA_FLAG_SIGN_VER - enable rsa_sign and rsa_verify + * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match + */ + int flags; + + char *app_data; /* ?? */ + + /* sign. For backward compatibility, this is used only + * if (flags & RSA_FLAG_SIGN_VER) + */ + int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len, + unsigned char *sigret, unsigned int *siglen, RSA *rsa); + + /* verify. For backward compatibility, this is used only + * if (flags & RSA_FLAG_SIGN_VER) + */ + int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len, + unsigned char *sigbuf, unsigned int siglen, RSA *rsa); + + } RSA_METHOD; + +=head1 RETURN VALUES + +RSA_PKCS1_SSLeay(), RSA_PKCS1_RSAref(), RSA_PKCS1_null_method(), +RSA_get_default_method() and RSA_get_method() return pointers to the +respective B<RSA_METHOD>s. + +RSA_set_default_method() returns no value. + +RSA_set_method() returns a pointer to the B<RSA_METHOD> previously +associated with B<rsa>. + +RSA_new_method() returns B<NULL> and sets an error code that can be +obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise it +returns a pointer to the newly allocated structure. + +=head1 SEE ALSO + +L<rsa(3)|rsa(3)>, L<RSA_new(3)|RSA_new(3)> + +=head1 HISTORY + +RSA_new_method() and RSA_set_default_method() appeared in SSLeay 0.8. +RSA_get_default_method(), RSA_set_method() and RSA_get_method() as +well as the rsa_sign and rsa_verify components of RSA_METHOD were +added in OpenSSL 0.9.4. + +=cut diff --git a/crypto/openssl/doc/crypto/RSA_sign.pod b/crypto/openssl/doc/crypto/RSA_sign.pod new file mode 100644 index 0000000..f0bf6ee --- /dev/null +++ b/crypto/openssl/doc/crypto/RSA_sign.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +RSA_sign, RSA_verify - RSA signatures + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_sign(int type, unsigned char *m, unsigned int m_len, + unsigned char *sigret, unsigned int *siglen, RSA *rsa); + + int RSA_verify(int type, unsigned char *m, unsigned int m_len, + unsigned char *sigbuf, unsigned int siglen, RSA *rsa); + +=head1 DESCRIPTION + +RSA_sign() signs the message digest B<m> of size B<m_len> using the +private key B<rsa> as specified in PKCS #1 v2.0. It stores the +signature in B<sigret> and the signature size in B<siglen>. B<sigret> +must point to RSA_size(B<rsa>) bytes of memory. + +B<type> denotes the message digest algorithm that was used to generate +B<m>. It usually is one of B<NID_sha1>, B<NID_ripemd160> and B<NID_md5>; +see L<objects(3)|objects(3)> for details. If B<type> is B<NID_md5_sha1>, +an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding +and no algorithm identifier) is created. + +RSA_verify() verifies that the signature B<sigbuf> of size B<siglen> +matches a given message digest B<m> of size B<m_len>. B<type> denotes +the message digest algorithm that was used to generate the signature. +B<rsa> is the signer's public key. + +=head1 RETURN VALUES + +RSA_sign() returns 1 on success, 0 otherwise. RSA_verify() returns 1 +on successful verification, 0 otherwise. + +The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 BUGS + +Certain signatures with an improper algorithm identifier are accepted +for compatibility with SSLeay 0.4.5 :-) + +=head1 CONFORMING TO + +SSL, PKCS #1 v2.0 + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<objects(3)|objects(3)>, L<rsa(3)|rsa(3)>, +L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>, +L<RSA_public_decrypt(3)|RSA_public_decrypt(3)> + +=head1 HISTORY + +RSA_sign() and RSA_verify() are available in all versions of SSLeay +and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod b/crypto/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod new file mode 100644 index 0000000..df9ceb3 --- /dev/null +++ b/crypto/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING - RSA signatures + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, + unsigned int m_len, unsigned char *sigret, unsigned int *siglen, + RSA *rsa); + + int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m, + unsigned int m_len, unsigned char *sigbuf, unsigned int siglen, + RSA *rsa); + +=head1 DESCRIPTION + +RSA_sign_ASN1_OCTET_STRING() signs the octet string B<m> of size +B<m_len> using the private key B<rsa> represented in DER using PKCS #1 +padding. It stores the signature in B<sigret> and the signature size +in B<siglen>. B<sigret> must point to B<RSA_size(rsa)> bytes of +memory. + +B<dummy> is ignored. + +The random number generator must be seeded prior to calling RSA_sign_ASN1_OCTET_STRING(). + +RSA_verify_ASN1_OCTET_STRING() verifies that the signature B<sigbuf> +of size B<siglen> is the DER representation of a given octet string +B<m> of size B<m_len>. B<dummy> is ignored. B<rsa> is the signer's +public key. + +=head1 RETURN VALUES + +RSA_sign_ASN1_OCTET_STRING() returns 1 on success, 0 otherwise. +RSA_verify_ASN1_OCTET_STRING() returns 1 on successful verification, 0 +otherwise. + +The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 BUGS + +These functions serve no recognizable purpose. + +=head1 SEE ALSO + +L<err(3)|err(3)>, L<objects(3)|objects(3)>, L<rand(3)|rand(3)>, +L<rsa(3)|rsa(3)>, L<RSA_sign(3)|RSA_sign(3)>, +L<RSA_verify(3)|RSA_verify(3)> + +=head1 HISTORY + +RSA_sign_ASN1_OCTET_STRING() and RSA_verify_ASN1_OCTET_STRING() were +added in SSLeay 0.8. + +=cut diff --git a/crypto/openssl/doc/crypto/RSA_size.pod b/crypto/openssl/doc/crypto/RSA_size.pod new file mode 100644 index 0000000..b36b4d5 --- /dev/null +++ b/crypto/openssl/doc/crypto/RSA_size.pod @@ -0,0 +1,33 @@ +=pod + +=head1 NAME + +RSA_size - get RSA modulus size + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_size(RSA *rsa); + +=head1 DESCRIPTION + +This function returns the RSA modulus size in bytes. It can be used to +determine how much memory must be allocated for an RSA encrypted +value. + +B<rsa-E<gt>n> must not be B<NULL>. + +=head1 RETURN VALUE + +The size in bytes. + +=head1 SEE ALSO + +L<rsa(3)|rsa(3)> + +=head1 HISTORY + +RSA_size() is available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/bio.pod b/crypto/openssl/doc/crypto/bio.pod new file mode 100644 index 0000000..24f61df --- /dev/null +++ b/crypto/openssl/doc/crypto/bio.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +bio - I/O abstraction + +=head1 SYNOPSIS + + #include <openssl/bio.h> + +TBA + + +=head1 DESCRIPTION + +A BIO is an I/O abstraction, it hides many of the underlying I/O +details from an application. If an application uses a BIO for its +I/O it can transparently handle SSL connections, unencrypted network +connections and file I/O. + +There are two type of BIO, a source/sink BIO and a filter BIO. + +As its name implies a source/sink BIO is a source and/or sink of data, +examples include a socket BIO and a file BIO. + +A filter BIO takes data from one BIO and passes it through to +another, or the application. The data may be left unmodified (for +example a message digest BIO) or translated (for example an +encryption BIO). The effect of a filter BIO may change according +to the I/O operation it is performing: for example an encryption +BIO will encrypt data if it is being written to and decrypt data +if it is being read from. + +BIOs can be joined together to form a chain (a single BIO is a chain +with one component). A chain normally consist of one source/sink +BIO and one or more filter BIOs. Data read from or written to the +first BIO then traverses the chain to the end (normally a source/sink +BIO). + +=head1 SEE ALSO + +L<BIO_ctrl(3)|BIO_ctrl(3)>, +L<BIO_f_base64(3)|BIO_f_base64(3)>, +L<BIO_f_cipher(3)|BIO_f_cipher(3)>, L<BIO_f_md(3)|BIO_f_md(3)>, +L<BIO_f_null(3)|BIO_f_null(3)>, L<BIO_f_ssl(3)|BIO_f_ssl(3)>, +L<BIO_find_type(3)|BIO_find_type(3)>, L<BIO_new(3)|BIO_new(3)>, +L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)>, +L<BIO_push(3)|BIO_push(3)>, L<BIO_read(3)|BIO_read(3)>, +L<BIO_s_accept(3)|BIO_s_accept(3)>, L<BIO_s_bio(3)|BIO_s_bio(3)>, +L<BIO_s_connect(3)|BIO_s_connect(3)>, L<BIO_s_fd(3)|BIO_s_fd(3)>, +L<BIO_s_file(3)|BIO_s_file(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>, +L<BIO_s_null(3)|BIO_s_null(3)>, L<BIO_s_socket(3)|BIO_s_socket(3)>, +L<BIO_set_callback(3)|BIO_set_callback(3)>, +L<BIO_should_retry(3)|BIO_should_retry(3)> diff --git a/crypto/openssl/doc/crypto/blowfish.pod b/crypto/openssl/doc/crypto/blowfish.pod new file mode 100644 index 0000000..65b8be3 --- /dev/null +++ b/crypto/openssl/doc/crypto/blowfish.pod @@ -0,0 +1,112 @@ +=pod + +=head1 NAME + +blowfish, BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, +BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption + +=head1 SYNOPSIS + + #include <openssl/blowfish.h> + + void BF_set_key(BF_KEY *key, int len, const unsigned char *data); + + void BF_ecb_encrypt(const unsigned char *in, unsigned char *out, + BF_KEY *key, int enc); + void BF_cbc_encrypt(const unsigned char *in, unsigned char *out, + long length, BF_KEY *schedule, unsigned char *ivec, int enc); + void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out, + long length, BF_KEY *schedule, unsigned char *ivec, int *num, + int enc); + void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out, + long length, BF_KEY *schedule, unsigned char *ivec, int *num); + const char *BF_options(void); + + void BF_encrypt(BF_LONG *data,const BF_KEY *key); + void BF_decrypt(BF_LONG *data,const BF_KEY *key); + +=head1 DESCRIPTION + +This library implements the Blowfish cipher, which is invented and described +by Counterpane (see http://www.counterpane.com/blowfish.html ). + +Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data. +It uses a variable size key, but typically, 128 bit (16 byte) keys are +a considered good for strong encryption. Blowfish can be used in the same +modes as DES (see L<des_modes(7)|des_modes(7)>). Blowfish is currently one +of the faster block ciphers. It is quite a bit faster than DES, and much +faster than IDEA or RC2. + +Blowfish consists of a key setup phase and the actual encryption or decryption +phase. + +BF_set_key() sets up the B<BF_KEY> B<key> using the B<len> bytes long key +at B<data>. + +BF_ecb_encrypt() is the basic Blowfish encryption and decryption function. +It encrypts or decrypts the first 64 bits of B<in> using the key B<key>, +putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>) +or decryption (B<BF_DECRYPT>) shall be performed. The vector pointed at by +B<in> and B<out> must be 64 bits in length, no less. If they are larger, +everything after the first 64 bits is ignored. + +The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt() +all operate on variable length data. They all take an initialization vector +B<ivec> which needs to be passed along into the next call of the same function +for the same message. B<ivec> may be initialized with anything, but the +recipient needs to know what it was initialized with, or it won't be able +to decrypt. Some programs and protocols simplify this, like SSH, where +B<ivec> is simply initialized to zero. +BF_cbc_encrypt() operates of data that is a multiple of 8 bytes long, while +BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt an variable +number of bytes (the amount does not have to be an exact multiple of 8). The +purpose of the latter two is to simulate stream ciphers, and therefore, they +need the parameter B<num>, which is a pointer to an integer where the current +offset in B<ivec> is stored between calls. This integer must be initialized +to zero when B<ivec> is initialized. + +BF_cbc_encrypt() is the Cipher Block Chaining function for Blowfish. It +encrypts or decrypts the 64 bits chunks of B<in> using the key B<schedule>, +putting the result in B<out>. B<enc> decides if encryption (BF_ENCRYPT) or +decryption (BF_DECRYPT) shall be performed. B<ivec> must point at an 8 byte +long initialization vector. + +BF_cfb64_encrypt() is the CFB mode for Blowfish with 64 bit feedback. +It encrypts or decrypts the bytes in B<in> using the key B<schedule>, +putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>) +or decryption (B<BF_DECRYPT>) shall be performed. B<ivec> must point at an +8 byte long initialization vector. B<num> must point at an integer which must +be initially zero. + +BF_ofb64_encrypt() is the OFB mode for Blowfish with 64 bit feedback. +It uses the same parameters as BF_cfb64_encrypt(), which must be initialized +the same way. + +BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish +encryption. They encrypt/decrypt the first 64 bits of the vector pointed by +B<data>, using the key B<key>. These functions should not be used unless you +implement 'modes' of Blowfish. The alternative is to use BF_ecb_encrypt(). +If you still want to use these functions, you should be aware that they take +each 32-bit chunk in host-byte order, which is little-endian on little-endian +platforms and big-endian on big-endian ones. + +=head1 RETURN VALUES + +None of the functions presented here return any value. + +=head1 NOTE + +Applications should use the higher level functions +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling the +blowfish functions directly. + +=head1 SEE ALSO + +L<des_modes(7)|des_modes(7)> + +=head1 HISTORY + +The Blowfish functions are available in all versions of SSLeay and OpenSSL. + +=cut + diff --git a/crypto/openssl/doc/crypto/bn.pod b/crypto/openssl/doc/crypto/bn.pod new file mode 100644 index 0000000..1504a1c --- /dev/null +++ b/crypto/openssl/doc/crypto/bn.pod @@ -0,0 +1,148 @@ +=pod + +=head1 NAME + +bn - multiprecision integer arithmetics + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BIGNUM *BN_new(void); + void BN_free(BIGNUM *a); + void BN_init(BIGNUM *); + void BN_clear(BIGNUM *a); + void BN_clear_free(BIGNUM *a); + + BN_CTX *BN_CTX_new(void); + void BN_CTX_init(BN_CTX *c); + void BN_CTX_free(BN_CTX *c); + + BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b); + BIGNUM *BN_dup(const BIGNUM *a); + + int BN_num_bytes(const BIGNUM *a); + int BN_num_bits(const BIGNUM *a); + int BN_num_bits_word(BN_ULONG w); + + int BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b); + int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); + int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); + int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d, + BN_CTX *ctx); + int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); + int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); + int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, + BN_CTX *ctx); + int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx); + int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx); + int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); + + int BN_add_word(BIGNUM *a, BN_ULONG w); + int BN_sub_word(BIGNUM *a, BN_ULONG w); + int BN_mul_word(BIGNUM *a, BN_ULONG w); + BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w); + BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w); + + int BN_cmp(BIGNUM *a, BIGNUM *b); + int BN_ucmp(BIGNUM *a, BIGNUM *b); + int BN_is_zero(BIGNUM *a); + int BN_is_one(BIGNUM *a); + int BN_is_word(BIGNUM *a, BN_ULONG w); + int BN_is_odd(BIGNUM *a); + + int BN_zero(BIGNUM *a); + int BN_one(BIGNUM *a); + BIGNUM *BN_value_one(void); + int BN_set_word(BIGNUM *a, unsigned long w); + unsigned long BN_get_word(BIGNUM *a); + + int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); + int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); + + BIGNUM *BN_generate_prime(BIGNUM *ret, int bits,int safe, BIGNUM *add, + BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); + int BN_is_prime(const BIGNUM *p, int nchecks, + void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); + + int BN_set_bit(BIGNUM *a, int n); + int BN_clear_bit(BIGNUM *a, int n); + int BN_is_bit_set(const BIGNUM *a, int n); + int BN_mask_bits(BIGNUM *a, int n); + int BN_lshift(BIGNUM *r, const BIGNUM *a, int n); + int BN_lshift1(BIGNUM *r, BIGNUM *a); + int BN_rshift(BIGNUM *r, BIGNUM *a, int n); + int BN_rshift1(BIGNUM *r, BIGNUM *a); + + int BN_bn2bin(const BIGNUM *a, unsigned char *to); + BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret); + char *BN_bn2hex(const BIGNUM *a); + char *BN_bn2dec(const BIGNUM *a); + int BN_hex2bn(BIGNUM **a, const char *str); + int BN_dec2bn(BIGNUM **a, const char *str); + int BN_print(BIO *fp, const BIGNUM *a); + int BN_print_fp(FILE *fp, const BIGNUM *a); + int BN_bn2mpi(const BIGNUM *a, unsigned char *to); + BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret); + + BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n, + BN_CTX *ctx); + + BN_RECP_CTX *BN_RECP_CTX_new(void); + void BN_RECP_CTX_init(BN_RECP_CTX *recp); + void BN_RECP_CTX_free(BN_RECP_CTX *recp); + int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx); + int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b, + BN_RECP_CTX *recp, BN_CTX *ctx); + + BN_MONT_CTX *BN_MONT_CTX_new(void); + void BN_MONT_CTX_init(BN_MONT_CTX *ctx); + void BN_MONT_CTX_free(BN_MONT_CTX *mont); + int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); + BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from); + int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b, + BN_MONT_CTX *mont, BN_CTX *ctx); + int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, + BN_CTX *ctx); + int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, + BN_CTX *ctx); + + +=head1 DESCRIPTION + +This library performs arithmetic operations on integers of arbitrary +size. It was written for use in public key cryptography, such as RSA +and Diffie-Hellman. + +It uses dynamic memory allocation for storing its data structures. +That means that there is no limit on the size of the numbers +manipulated by these functions, but return values must always be +checked in case a memory allocation error has occurred. + +The basic object in this library is a B<BIGNUM>. It is used to hold a +single large integer. This type should be considered opaque and fields +should not be modified or accessed directly. + +The creation of B<BIGNUM> objects is described in L<BN_new(3)|BN_new(3)>; +L<BN_add(3)|BN_add(3)> describes most of the arithmetic operations. +Comparison is described in L<BN_cmp(3)|BN_cmp(3)>; L<BN_zero(3)|BN_zero(3)> +describes certain assignments, L<BN_rand(3)|BN_rand(3)> the generation of +random numbers, L<BN_generate_prime(3)|BN_generate_prime(3)> deals with prime +numbers and L<BN_set_bit(3)|BN_set_bit(3)> with bit operations. The conversion +of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)|BN_bn2bin(3)>. + +=head1 SEE ALSO + +L<bn_internal(3)|bn_internal(3)>, +L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, +L<BN_new(3)|BN_new(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>, +L<BN_copy(3)|BN_copy(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, +L<BN_add(3)|BN_add(3)>, L<BN_add_word(3)|BN_add_word(3)>, +L<BN_cmp(3)|BN_cmp(3)>, L<BN_zero(3)|BN_zero(3)>, L<BN_rand(3)|BN_rand(3)>, +L<BN_generate_prime(3)|BN_generate_prime(3)>, L<BN_set_bit(3)|BN_set_bit(3)>, +L<BN_bn2bin(3)|BN_bn2bin(3)>, L<BN_mod_inverse(3)|BN_mod_inverse(3)>, +L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>, +L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)> + +=cut diff --git a/crypto/openssl/doc/crypto/bn_internal.pod b/crypto/openssl/doc/crypto/bn_internal.pod new file mode 100644 index 0000000..8da244a --- /dev/null +++ b/crypto/openssl/doc/crypto/bn_internal.pod @@ -0,0 +1,225 @@ +=pod + +=head1 NAME + +bn_mul_words, bn_mul_add_words, bn_sqr_words, bn_div_words, +bn_add_words, bn_sub_words, bn_mul_comba4, bn_mul_comba8, +bn_sqr_comba4, bn_sqr_comba8, bn_cmp_words, bn_mul_normal, +bn_mul_low_normal, bn_mul_recursive, bn_mul_part_recursive, +bn_mul_low_recursive, bn_mul_high, bn_sqr_normal, bn_sqr_recursive, +bn_expand, bn_wexpand, bn_expand2, bn_fix_top, bn_check_top, +bn_print, bn_dump, bn_set_max, bn_set_high, bn_set_low - BIGNUM +library internal functions + +=head1 SYNOPSIS + + BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w); + BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num, + BN_ULONG w); + void bn_sqr_words(BN_ULONG *rp, BN_ULONG *ap, int num); + BN_ULONG bn_div_words(BN_ULONG h, BN_ULONG l, BN_ULONG d); + BN_ULONG bn_add_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, + int num); + BN_ULONG bn_sub_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, + int num); + + void bn_mul_comba4(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); + void bn_mul_comba8(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); + void bn_sqr_comba4(BN_ULONG *r, BN_ULONG *a); + void bn_sqr_comba8(BN_ULONG *r, BN_ULONG *a); + + int bn_cmp_words(BN_ULONG *a, BN_ULONG *b, int n); + + void bn_mul_normal(BN_ULONG *r, BN_ULONG *a, int na, BN_ULONG *b, + int nb); + void bn_mul_low_normal(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n); + void bn_mul_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n2, + BN_ULONG *tmp); + void bn_mul_part_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, + int tn, int n, BN_ULONG *tmp); + void bn_mul_low_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, + int n2, BN_ULONG *tmp); + void bn_mul_high(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, BN_ULONG *l, + int n2, BN_ULONG *tmp); + + void bn_sqr_normal(BN_ULONG *r, BN_ULONG *a, int n, BN_ULONG *tmp); + void bn_sqr_recursive(BN_ULONG *r, BN_ULONG *a, int n2, BN_ULONG *tmp); + + void mul(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); + void mul_add(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); + void sqr(BN_ULONG r0, BN_ULONG r1, BN_ULONG a); + + BIGNUM *bn_expand(BIGNUM *a, int bits); + BIGNUM *bn_wexpand(BIGNUM *a, int n); + BIGNUM *bn_expand2(BIGNUM *a, int n); + void bn_fix_top(BIGNUM *a); + + void bn_check_top(BIGNUM *a); + void bn_print(BIGNUM *a); + void bn_dump(BN_ULONG *d, int n); + void bn_set_max(BIGNUM *a); + void bn_set_high(BIGNUM *r, BIGNUM *a, int n); + void bn_set_low(BIGNUM *r, BIGNUM *a, int n); + +=head1 DESCRIPTION + +This page documents the internal functions used by the OpenSSL +B<BIGNUM> implementation. They are described here to facilitate +debugging and extending the library. They are I<not> to be used by +applications. + +=head2 The BIGNUM structure + + typedef struct bignum_st + { + int top; /* index of last used d (most significant word) */ + BN_ULONG *d; /* pointer to an array of 'BITS2' bit chunks */ + int max; /* size of the d array */ + int neg; /* sign */ + } BIGNUM; + +The big number is stored in B<d>, a malloc()ed array of B<BN_ULONG>s, +least significant first. A B<BN_ULONG> can be either 16, 32 or 64 bits +in size (B<BITS2>), depending on the 'number of bits' specified in +C<openssl/bn.h>. + +B<max> is the size of the B<d> array that has been allocated. B<top> +is the 'last' entry being used, so for a value of 4, bn.d[0]=4 and +bn.top=1. B<neg> is 1 if the number is negative. When a B<BIGNUM> is +B<0>, the B<d> field can be B<NULL> and B<top> == B<0>. + +Various routines in this library require the use of temporary +B<BIGNUM> variables during their execution. Since dynamic memory +allocation to create B<BIGNUM>s is rather expensive when used in +conjunction with repeated subroutine calls, the B<BN_CTX> structure is +used. This structure contains B<BN_CTX_NUM> B<BIGNUM>s, see +L<BN_CTX_start(3)|BN_CTX_start(3)>. + +=head2 Low-level arithmetic operations + +These functions are implemented in C and for several platforms in +assembly language: + +bn_mul_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num> word +arrays B<rp> and B<ap>. It computes B<ap> * B<w>, places the result +in B<rp>, and returns the high word (carry). + +bn_mul_add_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num> +word arrays B<rp> and B<ap>. It computes B<ap> * B<w> + B<rp>, places +the result in B<rp>, and returns the high word (carry). + +bn_sqr_words(B<rp>, B<ap>, B<n>) operates on the B<num> word array +B<ap> and the 2*B<num> word array B<ap>. It computes B<ap> * B<ap> +word-wise, and places the low and high bytes of the result in B<rp>. + +bn_div_words(B<h>, B<l>, B<d>) divides the two word number (B<h>,B<l>) +by B<d> and returns the result. + +bn_add_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word +arrays B<ap>, B<bp> and B<rp>. It computes B<ap> + B<bp>, places the +result in B<rp>, and returns the high word (carry). + +bn_sub_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word +arrays B<ap>, B<bp> and B<rp>. It computes B<ap> - B<bp>, places the +result in B<rp>, and returns the carry (1 if B<bp> E<gt> B<ap>, 0 +otherwise). + +bn_mul_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and +B<b> and the 8 word array B<r>. It computes B<a>*B<b> and places the +result in B<r>. + +bn_mul_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and +B<b> and the 16 word array B<r>. It computes B<a>*B<b> and places the +result in B<r>. + +bn_sqr_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and +B<b> and the 8 word array B<r>. + +bn_sqr_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and +B<b> and the 16 word array B<r>. + +The following functions are implemented in C: + +bn_cmp_words(B<a>, B<b>, B<n>) operates on the B<n> word arrays B<a> +and B<b>. It returns 1, 0 and -1 if B<a> is greater than, equal and +less than B<b>. + +bn_mul_normal(B<r>, B<a>, B<na>, B<b>, B<nb>) operates on the B<na> +word array B<a>, the B<nb> word array B<b> and the B<na>+B<nb> word +array B<r>. It computes B<a>*B<b> and places the result in B<r>. + +bn_mul_low_normal(B<r>, B<a>, B<b>, B<n>) operates on the B<n> word +arrays B<r>, B<a> and B<b>. It computes the B<n> low words of +B<a>*B<b> and places the result in B<r>. + +bn_mul_recursive(B<r>, B<a>, B<b>, B<n2>, B<t>) operates on the B<n2> +word arrays B<a> and B<b> and the 2*B<n2> word arrays B<r> and B<t>. +B<n2> must be a power of 2. It computes B<a>*B<b> and places the +result in B<r>. + +bn_mul_part_recursive(B<r>, B<a>, B<b>, B<tn>, B<n>, B<tmp>) operates +on the B<n>+B<tn> word arrays B<a> and B<b> and the 4*B<n> word arrays +B<r> and B<tmp>. + +bn_mul_low_recursive(B<r>, B<a>, B<b>, B<n2>, B<tmp>) operates on the +B<n2> word arrays B<r> and B<tmp> and the B<n2>/2 word arrays B<a> +and B<b>. + +bn_mul_high(B<r>, B<a>, B<b>, B<l>, B<n2>, B<tmp>) operates on the +B<n2> word arrays B<r>, B<a>, B<b> and B<l> (?) and the 3*B<n2> word +array B<tmp>. + +BN_mul() calls bn_mul_normal(), or an optimized implementation if the +factors have the same size: bn_mul_comba8() is used if they are 8 +words long, bn_mul_recursive() if they are larger than +B<BN_MULL_SIZE_NORMAL> and the size is an exact multiple of the word +size, and bn_mul_part_recursive() for others that are larger than +B<BN_MULL_SIZE_NORMAL>. + +bn_sqr_normal(B<r>, B<a>, B<n>, B<tmp>) operates on the B<n> word array +B<a> and the 2*B<n> word arrays B<tmp> and B<r>. + +The implementations use the following macros which, depending on the +architecture, may use "long long" C operations or inline assembler. +They are defined in C<bn_lcl.h>. + +mul(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<c> and places the +low word of the result in B<r> and the high word in B<c>. + +mul_add(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<r>+B<c> and +places the low word of the result in B<r> and the high word in B<c>. + +sqr(B<r0>, B<r1>, B<a>) computes B<a>*B<a> and places the low word +of the result in B<r0> and the high word in B<r1>. + +=head2 Size changes + +bn_expand() ensures that B<b> has enough space for a B<bits> bit +number. bn_wexpand() ensures that B<b> has enough space for an +B<n> word number. If the number has to be expanded, both macros +call bn_expand2(), which allocates a new B<d> array and copies the +data. They return B<NULL> on error, B<b> otherwise. + +The bn_fix_top() macro reduces B<a-E<gt>top> to point to the most +significant non-zero word when B<a> has shrunk. + +=head2 Debugging + +bn_check_top() verifies that C<((a)-E<gt>top E<gt>= 0 && (a)-E<gt>top +E<lt>= (a)-E<gt>max)>. A violation will cause the program to abort. + +bn_print() prints B<a> to stderr. bn_dump() prints B<n> words at B<d> +(in reverse order, i.e. most significant word first) to stderr. + +bn_set_max() makes B<a> a static number with a B<max> of its current size. +This is used by bn_set_low() and bn_set_high() to make B<r> a read-only +B<BIGNUM> that contains the B<n> low or high words of B<a>. + +If B<BN_DEBUG> is not defined, bn_check_top(), bn_print(), bn_dump() +and bn_set_max() are defined as empty macros. + +=head1 SEE ALSO + +L<bn(3)|bn(3)> + +=cut diff --git a/crypto/openssl/doc/crypto/buffer.pod b/crypto/openssl/doc/crypto/buffer.pod new file mode 100644 index 0000000..781f5b1 --- /dev/null +++ b/crypto/openssl/doc/crypto/buffer.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +BUF_MEM_new, BUF_MEM_free, BUF_MEM_grow, BUF_strdup - simple +character arrays structure + +=head1 SYNOPSIS + + #include <openssl/buffer.h> + + BUF_MEM *BUF_MEM_new(void); + + void BUF_MEM_free(BUF_MEM *a); + + int BUF_MEM_grow(BUF_MEM *str, int len); + + char * BUF_strdup(const char *str); + +=head1 DESCRIPTION + +The buffer library handles simple character arrays. Buffers are used for +various purposes in the library, most notably memory BIOs. + +The library uses the BUF_MEM structure defined in buffer.h: + + typedef struct buf_mem_st + { + int length; /* current number of bytes */ + char *data; + int max; /* size of buffer */ + } BUF_MEM; + +B<length> is the current size of the buffer in bytes, B<max> is the amount of +memory allocated to the buffer. There are three functions which handle these +and one "miscellaneous" function. + +BUF_MEM_new() allocates a new buffer of zero size. + +BUF_MEM_free() frees up an already existing buffer. The data is zeroed +before freeing up in case the buffer contains sensitive data. + +BUF_MEM_grow() changes the size of an already existing buffer to +B<len>. Any data already in the buffer is preserved if it increases in +size. + +BUF_strdup() copies a null terminated string into a block of allocated +memory and returns a pointer to the allocated block. +Unlike the standard C library strdup() this function uses OPENSSL_malloc() and so +should be used in preference to the standard library strdup() because it can +be used for memory leak checking or replacing the malloc() function. + +The memory allocated from BUF_strdup() should be freed up using the OPENSSL_free() +function. + +=head1 RETURN VALUES + +BUF_MEM_new() returns the buffer or NULL on error. + +BUF_MEM_free() has no return value. + +BUF_MEM_grow() returns zero on error or the new size (i.e. B<len>). + +=head1 SEE ALSO + +L<bio(3)|bio(3)> + +=head1 HISTORY + +BUF_MEM_new(), BUF_MEM_free() and BUF_MEM_grow() are available in all +versions of SSLeay and OpenSSL. BUF_strdup() was added in SSLeay 0.8. + +=cut diff --git a/crypto/openssl/doc/crypto/crypto.pod b/crypto/openssl/doc/crypto/crypto.pod new file mode 100644 index 0000000..07ba7e5 --- /dev/null +++ b/crypto/openssl/doc/crypto/crypto.pod @@ -0,0 +1,68 @@ +=pod + +=head1 NAME + +crypto - OpenSSL cryptographic library + +=head1 SYNOPSIS + +=head1 DESCRIPTION + +The OpenSSL B<crypto> library implements a wide range of cryptographic +algorithms used in various Internet standards. The services provided +by this library are used by the OpenSSL implementations of SSL, TLS +and S/MIME, and they have also been used to implement SSH, OpenPGP, and +other cryptographic standards. + +=head1 OVERVIEW + +B<libcrypto> consists of a number of sub-libraries that implement the +individual algorithms. + +The functionality includes symmetric encryption, public key +cryptography and key agreement, certificate handling, cryptographic +hash functions and a cryptographic pseudo-random number generator. + +=over 4 + +=item SYMMETRIC CIPHERS + +L<blowfish(3)|blowfish(3)>, L<cast(3)|cast(3)>, L<des(3)|des(3)>, +L<idea(3)|idea(3)>, L<rc2(3)|rc2(3)>, L<rc4(3)|rc4(3)>, L<rc5(3)|rc5(3)> + +=item PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT + +L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rsa(3)|rsa(3)> + +=item CERTIFICATES + +L<x509(3)|x509(3)>, L<x509v3(3)|x509v3(3)> + +=item AUTHENTICATION CODES, HASH FUNCTIONS + +L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, L<md4(3)|md4(3)>, +L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, +L<sha(3)|sha(3)> + +=item AUXILIARY FUNCTIONS + +L<err(3)|err(3)>, L<threads(3)|threads(3)>, L<rand(3)|rand(3)> + +=item INPUT/OUTPUT, DATA ENCODING + +L<asn1(3)|asn1(3)>, L<bio(3)|bio(3)>, L<evp(3)|evp(3)>, L<pem(3)|pem(3)>, +L<pkcs7(3)|pkcs7(3)>, L<pkcs12(3)|pkcs12(3)> + +=item INTERNAL FUNCTIONS + +L<bn(3)|bn(3)>, L<buffer(3)|buffer(3)>, L<lhash(3)|lhash(3)>, +L<objects(3)|objects(3)>, L<stack(3)|stack(3)>, +L<txt_db(3)|txt_db(3)> + +=back + +=head1 SEE ALSO + +L<openssl(1)|openssl(1)>, L<ssl(3)|ssl(3)> + +=cut diff --git a/crypto/openssl/doc/crypto/d2i_DHparams.pod b/crypto/openssl/doc/crypto/d2i_DHparams.pod new file mode 100644 index 0000000..a6d1743 --- /dev/null +++ b/crypto/openssl/doc/crypto/d2i_DHparams.pod @@ -0,0 +1,30 @@ +=pod + +=head1 NAME + +d2i_DHparams, i2d_DHparams - ... + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + DH *d2i_DHparams(DH **a, unsigned char **pp, long length); + int i2d_DHparams(DH *a, unsigned char **pp); + +=head1 DESCRIPTION + +... + +=head1 RETURN VALUES + +... + +=head1 SEE ALSO + +... + +=head1 HISTORY + +... + +=cut diff --git a/crypto/openssl/doc/crypto/d2i_RSAPublicKey.pod b/crypto/openssl/doc/crypto/d2i_RSAPublicKey.pod new file mode 100644 index 0000000..ff4d0d5 --- /dev/null +++ b/crypto/openssl/doc/crypto/d2i_RSAPublicKey.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey, i2d_Netscape_RSA, d2i_Netscape_RSA - ... + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + RSA * d2i_RSAPublicKey(RSA **a, unsigned char **pp, long length); + + int i2d_RSAPublicKey(RSA *a, unsigned char **pp); + + RSA * d2i_RSAPrivateKey(RSA **a, unsigned char **pp, long length); + + int i2d_RSAPrivateKey(RSA *a, unsigned char **pp); + + int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)()); + + RSA * d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)()); + +=head1 DESCRIPTION + +... + +=head1 RETURN VALUES + +... + +=head1 SEE ALSO + +... + +=head1 HISTORY + +... + +=cut diff --git a/crypto/openssl/doc/crypto/des.pod b/crypto/openssl/doc/crypto/des.pod new file mode 100644 index 0000000..ab3e26e --- /dev/null +++ b/crypto/openssl/doc/crypto/des.pod @@ -0,0 +1,376 @@ +=pod + +=head1 NAME + +des_random_key, des_set_key, des_key_sched, des_set_key_checked, +des_set_key_unchecked, des_set_odd_parity, des_is_weak_key, +des_ecb_encrypt, des_ecb2_encrypt, des_ecb3_encrypt, des_ncbc_encrypt, +des_cfb_encrypt, des_ofb_encrypt, des_pcbc_encrypt, des_cfb64_encrypt, +des_ofb64_encrypt, des_xcbc_encrypt, des_ede2_cbc_encrypt, +des_ede2_cfb64_encrypt, des_ede2_ofb64_encrypt, des_ede3_cbc_encrypt, +des_ede3_cbcm_encrypt, des_ede3_cfb64_encrypt, des_ede3_ofb64_encrypt, +des_read_password, des_read_2passwords, des_read_pw_string, +des_cbc_cksum, des_quad_cksum, des_string_to_key, des_string_to_2keys, +des_fcrypt, des_crypt, des_enc_read, des_enc_write - DES encryption + +=head1 SYNOPSIS + + #include <openssl/des.h> + + void des_random_key(des_cblock *ret); + + int des_set_key(const_des_cblock *key, des_key_schedule schedule); + int des_key_sched(const_des_cblock *key, des_key_schedule schedule); + int des_set_key_checked(const_des_cblock *key, + des_key_schedule schedule); + void des_set_key_unchecked(const_des_cblock *key, + des_key_schedule schedule); + + void des_set_odd_parity(des_cblock *key); + int des_is_weak_key(const_des_cblock *key); + + void des_ecb_encrypt(const_des_cblock *input, des_cblock *output, + des_key_schedule ks, int enc); + void des_ecb2_encrypt(const_des_cblock *input, des_cblock *output, + des_key_schedule ks1, des_key_schedule ks2, int enc); + void des_ecb3_encrypt(const_des_cblock *input, des_cblock *output, + des_key_schedule ks1, des_key_schedule ks2, + des_key_schedule ks3, int enc); + + void des_ncbc_encrypt(const unsigned char *input, unsigned char *output, + long length, des_key_schedule schedule, des_cblock *ivec, + int enc); + void des_cfb_encrypt(const unsigned char *in, unsigned char *out, + int numbits, long length, des_key_schedule schedule, + des_cblock *ivec, int enc); + void des_ofb_encrypt(const unsigned char *in, unsigned char *out, + int numbits, long length, des_key_schedule schedule, + des_cblock *ivec); + void des_pcbc_encrypt(const unsigned char *input, unsigned char *output, + long length, des_key_schedule schedule, des_cblock *ivec, + int enc); + void des_cfb64_encrypt(const unsigned char *in, unsigned char *out, + long length, des_key_schedule schedule, des_cblock *ivec, + int *num, int enc); + void des_ofb64_encrypt(const unsigned char *in, unsigned char *out, + long length, des_key_schedule schedule, des_cblock *ivec, + int *num); + + void des_xcbc_encrypt(const unsigned char *input, unsigned char *output, + long length, des_key_schedule schedule, des_cblock *ivec, + const_des_cblock *inw, const_des_cblock *outw, int enc); + + void des_ede2_cbc_encrypt(const unsigned char *input, + unsigned char *output, long length, des_key_schedule ks1, + des_key_schedule ks2, des_cblock *ivec, int enc); + void des_ede2_cfb64_encrypt(const unsigned char *in, + unsigned char *out, long length, des_key_schedule ks1, + des_key_schedule ks2, des_cblock *ivec, int *num, int enc); + void des_ede2_ofb64_encrypt(const unsigned char *in, + unsigned char *out, long length, des_key_schedule ks1, + des_key_schedule ks2, des_cblock *ivec, int *num); + + void des_ede3_cbc_encrypt(const unsigned char *input, + unsigned char *output, long length, des_key_schedule ks1, + des_key_schedule ks2, des_key_schedule ks3, des_cblock *ivec, + int enc); + void des_ede3_cbcm_encrypt(const unsigned char *in, unsigned char *out, + long length, des_key_schedule ks1, des_key_schedule ks2, + des_key_schedule ks3, des_cblock *ivec1, des_cblock *ivec2, + int enc); + void des_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out, + long length, des_key_schedule ks1, des_key_schedule ks2, + des_key_schedule ks3, des_cblock *ivec, int *num, int enc); + void des_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out, + long length, des_key_schedule ks1, + des_key_schedule ks2, des_key_schedule ks3, + des_cblock *ivec, int *num); + + int des_read_password(des_cblock *key, const char *prompt, int verify); + int des_read_2passwords(des_cblock *key1, des_cblock *key2, + const char *prompt, int verify); + int des_read_pw_string(char *buf, int length, const char *prompt, + int verify); + + DES_LONG des_cbc_cksum(const unsigned char *input, des_cblock *output, + long length, des_key_schedule schedule, + const_des_cblock *ivec); + DES_LONG des_quad_cksum(const unsigned char *input, des_cblock output[], + long length, int out_count, des_cblock *seed); + void des_string_to_key(const char *str, des_cblock *key); + void des_string_to_2keys(const char *str, des_cblock *key1, + des_cblock *key2); + + char *des_fcrypt(const char *buf, const char *salt, char *ret); + char *des_crypt(const char *buf, const char *salt); + char *crypt(const char *buf, const char *salt); + + int des_enc_read(int fd, void *buf, int len, des_key_schedule sched, + des_cblock *iv); + int des_enc_write(int fd, const void *buf, int len, + des_key_schedule sched, des_cblock *iv); + +=head1 DESCRIPTION + +This library contains a fast implementation of the DES encryption +algorithm. + +There are two phases to the use of DES encryption. The first is the +generation of a I<des_key_schedule> from a key, the second is the +actual encryption. A DES key is of type I<des_cblock>. This type is +consists of 8 bytes with odd parity. The least significant bit in +each byte is the parity bit. The key schedule is an expanded form of +the key; it is used to speed the encryption process. + +des_random_key() generates a random key. The PRNG must be seeded +prior to using this function (see L<rand(3)|rand(3)>; for backward +compatibility the function des_random_seed() is available as well). +If the PRNG could not generate a secure key, 0 is returned. In +earlier versions of the library, des_random_key() did not generate +secure keys. + +Before a DES key can be used, it must be converted into the +architecture dependent I<des_key_schedule> via the +des_set_key_checked() or des_set_key_unchecked() function. + +des_set_key_checked() will check that the key passed is of odd parity +and is not a week or semi-weak key. If the parity is wrong, then -1 +is returned. If the key is a weak key, then -2 is returned. If an +error is returned, the key schedule is not generated. + +des_set_key() (called des_key_sched() in the MIT library) works like +des_set_key_checked() if the I<des_check_key> flag is non-zero, +otherwise like des_set_key_unchecked(). These functions are available +for compatibility; it is recommended to use a function that does not +depend on a global variable. + +des_set_odd_parity() (called des_fixup_key_parity() in the MIT +library) sets the parity of the passed I<key> to odd. + +des_is_weak_key() returns 1 is the passed key is a weak key, 0 if it +is ok. The probability that a randomly generated key is weak is +1/2^52, so it is not really worth checking for them. + +The following routines mostly operate on an input and output stream of +I<des_cblock>s. + +des_ecb_encrypt() is the basic DES encryption routine that encrypts or +decrypts a single 8-byte I<des_cblock> in I<electronic code book> +(ECB) mode. It always transforms the input data, pointed to by +I<input>, into the output data, pointed to by the I<output> argument. +If the I<encrypt> argument is non-zero (DES_ENCRYPT), the I<input> +(cleartext) is encrypted in to the I<output> (ciphertext) using the +key_schedule specified by the I<schedule> argument, previously set via +I<des_set_key>. If I<encrypt> is zero (DES_DECRYPT), the I<input> (now +ciphertext) is decrypted into the I<output> (now cleartext). Input +and output may overlap. des_ecb_encrypt() does not return a value. + +des_ecb3_encrypt() encrypts/decrypts the I<input> block by using +three-key Triple-DES encryption in ECB mode. This involves encrypting +the input with I<ks1>, decrypting with the key schedule I<ks2>, and +then encrypting with I<ks3>. This routine greatly reduces the chances +of brute force breaking of DES and has the advantage of if I<ks1>, +I<ks2> and I<ks3> are the same, it is equivalent to just encryption +using ECB mode and I<ks1> as the key. + +The macro des_ecb2_encrypt() is provided to perform two-key Triple-DES +encryption by using I<ks1> for the final encryption. + +des_ncbc_encrypt() encrypts/decrypts using the I<cipher-block-chaining> +(CBC) mode of DES. If the I<encrypt> argument is non-zero, the +routine cipher-block-chain encrypts the cleartext data pointed to by +the I<input> argument into the ciphertext pointed to by the I<output> +argument, using the key schedule provided by the I<schedule> argument, +and initialization vector provided by the I<ivec> argument. If the +I<length> argument is not an integral multiple of eight bytes, the +last block is copied to a temporary area and zero filled. The output +is always an integral multiple of eight bytes. + +des_xcbc_encrypt() is RSA's DESX mode of DES. It uses I<inw> and +I<outw> to 'whiten' the encryption. I<inw> and I<outw> are secret +(unlike the iv) and are as such, part of the key. So the key is sort +of 24 bytes. This is much better than CBC DES. + +des_ede3_cbc_encrypt() implements outer triple CBC DES encryption with +three keys. This means that each DES operation inside the CBC mode is +really an C<C=E(ks3,D(ks2,E(ks1,M)))>. This mode is used by SSL. + +The des_ede2_cbc_encrypt() macro implements two-key Triple-DES by +reusing I<ks1> for the final encryption. C<C=E(ks1,D(ks2,E(ks1,M)))>. +This form of Triple-DES is used by the RSAREF library. + +des_pcbc_encrypt() encrypt/decrypts using the propagating cipher block +chaining mode used by Kerberos v4. Its parameters are the same as +des_ncbc_encrypt(). + +des_cfb_encrypt() encrypt/decrypts using cipher feedback mode. This +method takes an array of characters as input and outputs and array of +characters. It does not require any padding to 8 character groups. +Note: the I<ivec> variable is changed and the new changed value needs to +be passed to the next call to this function. Since this function runs +a complete DES ECB encryption per I<numbits>, this function is only +suggested for use when sending small numbers of characters. + +des_cfb64_encrypt() +implements CFB mode of DES with 64bit feedback. Why is this +useful you ask? Because this routine will allow you to encrypt an +arbitrary number of bytes, no 8 byte padding. Each call to this +routine will encrypt the input bytes to output and then update ivec +and num. num contains 'how far' we are though ivec. If this does +not make much sense, read more about cfb mode of DES :-). + +des_ede3_cfb64_encrypt() and des_ede2_cfb64_encrypt() is the same as +des_cfb64_encrypt() except that Triple-DES is used. + +des_ofb_encrypt() encrypts using output feedback mode. This method +takes an array of characters as input and outputs and array of +characters. It does not require any padding to 8 character groups. +Note: the I<ivec> variable is changed and the new changed value needs to +be passed to the next call to this function. Since this function runs +a complete DES ECB encryption per numbits, this function is only +suggested for use when sending small numbers of characters. + +des_ofb64_encrypt() is the same as des_cfb64_encrypt() using Output +Feed Back mode. + +des_ede3_ofb64_encrypt() and des_ede2_ofb64_encrypt() is the same as +des_ofb64_encrypt(), using Triple-DES. + +The following functions are included in the DES library for +compatibility with the MIT Kerberos library. des_read_pw_string() +is also available under the name EVP_read_pw_string(). + +des_read_pw_string() writes the string specified by I<prompt> to +standard output, turns echo off and reads in input string from the +terminal. The string is returned in I<buf>, which must have space for +at least I<length> bytes. If I<verify> is set, the user is asked for +the password twice and unless the two copies match, an error is +returned. A return code of -1 indicates a system error, 1 failure due +to use interaction, and 0 is success. + +des_read_password() does the same and converts the password to a DES +key by calling des_string_to_key(); des_read_2password() operates in +the same way as des_read_password() except that it generates two keys +by using the des_string_to_2key() function. des_string_to_key() is +available for backward compatibility with the MIT library. New +applications should use a cryptographic hash function. The same +applies for des_string_to_2key(). + +des_cbc_cksum() produces an 8 byte checksum based on the input stream +(via CBC encryption). The last 4 bytes of the checksum are returned +and the complete 8 bytes are placed in I<output>. This function is +used by Kerberos v4. Other applications should use +L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead. + +des_quad_cksum() is a Kerberos v4 function. It returns a 4 byte +checksum from the input bytes. The algorithm can be iterated over the +input, depending on I<out_count>, 1, 2, 3 or 4 times. If I<output> is +non-NULL, the 8 bytes generated by each pass are written into +I<output>. + +The following are DES-based transformations: + +des_fcrypt() is a fast version of the Unix crypt(3) function. This +version takes only a small amount of space relative to other fast +crypt() implementations. This is different to the normal crypt in +that the third parameter is the buffer that the return value is +written into. It needs to be at least 14 bytes long. This function +is thread safe, unlike the normal crypt. + +des_crypt() is a faster replacement for the normal system crypt(). +This function calls des_fcrypt() with a static array passed as the +third parameter. This emulates the normal non-thread safe semantics +of crypt(3). + +des_enc_write() writes I<len> bytes to file descriptor I<fd> from +buffer I<buf>. The data is encrypted via I<pcbc_encrypt> (default) +using I<sched> for the key and I<iv> as a starting vector. The actual +data send down I<fd> consists of 4 bytes (in network byte order) +containing the length of the following encrypted data. The encrypted +data then follows, padded with random data out to a multiple of 8 +bytes. + +des_enc_read() is used to read I<len> bytes from file descriptor +I<fd> into buffer I<buf>. The data being read from I<fd> is assumed to +have come from des_enc_write() and is decrypted using I<sched> for +the key schedule and I<iv> for the initial vector. + +B<Warning:> The data format used by des_enc_write() and des_enc_read() +has a cryptographic weakness: When asked to write more than MAXWRITE +bytes, des_enc_write() will split the data into several chunks that +are all encrypted using the same IV. So don't use these functions +unless you are sure you know what you do (in which case you might not +want to use them anyway). They cannot handle non-blocking sockets. +des_enc_read() uses an internal state and thus cannot be used on +multiple files. + +I<des_rw_mode> is used to specify the encryption mode to use with +des_enc_read() and des_end_write(). If set to I<DES_PCBC_MODE> (the +default), des_pcbc_encrypt is used. If set to I<DES_CBC_MODE> +des_cbc_encrypt is used. + +=head1 NOTES + +Single-key DES is insecure due to its short key size. ECB mode is +not suitable for most applications; see L<des_modes(7)|des_modes(7)>. + +The L<evp(3)|evp(3)> library provides higher-level encryption functions. + +=head1 BUGS + +des_3cbc_encrypt() is flawed and must not be used in applications. + +des_cbc_encrypt() does not modify B<ivec>; use des_ncbc_encrypt() +instead. + +des_cfb_encrypt() and des_ofb_encrypt() operates on input of 8 bits. +What this means is that if you set numbits to 12, and length to 2, the +first 12 bits will come from the 1st input byte and the low half of +the second input byte. The second 12 bits will have the low 8 bits +taken from the 3rd input byte and the top 4 bits taken from the 4th +input byte. The same holds for output. This function has been +implemented this way because most people will be using a multiple of 8 +and because once you get into pulling bytes input bytes apart things +get ugly! + +des_read_pw_string() is the most machine/OS dependent function and +normally generates the most problems when porting this code. + +=head1 CONFORMING TO + +ANSI X3.106 + +The B<des> library was written to be source code compatible with +the MIT Kerberos library. + +=head1 SEE ALSO + +crypt(3), L<des_modes(3)|des_modes(3)>, L<evp(3)|evp(3)>, L<rand(3)|rand(3)> + +=head1 HISTORY + +des_cbc_cksum(), des_cbc_encrypt(), des_ecb_encrypt(), +des_is_weak_key(), des_key_sched(), des_pcbc_encrypt(), +des_quad_cksum(), des_random_key(), des_read_password() and +des_string_to_key() are available in the MIT Kerberos library; +des_check_key_parity(), des_fixup_key_parity() and des_is_weak_key() +are available in newer versions of that library. + +des_set_key_checked() and des_set_key_unchecked() were added in +OpenSSL 0.9.5. + +des_generate_random_block(), des_init_random_number_generator(), +des_new_random_key(), des_set_random_generator_seed() and +des_set_sequence_number() and des_rand_data() are used in newer +versions of Kerberos but are not implemented here. + +des_random_key() generated cryptographically weak random data in +SSLeay and in OpenSSL prior version 0.9.5, as well as in the original +MIT library. + +=head1 AUTHOR + +Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project +(http://www.openssl.org). + +=cut diff --git a/crypto/openssl/doc/crypto/des_modes.pod b/crypto/openssl/doc/crypto/des_modes.pod new file mode 100644 index 0000000..36b77c4 --- /dev/null +++ b/crypto/openssl/doc/crypto/des_modes.pod @@ -0,0 +1,253 @@ +=pod + +=head1 NAME + +Modes of DES - the variants of DES and other crypto algorithms of OpenSSL + +=head1 DESCRIPTION + +Several crypto algorithms for OpenSSL can be used in a number of modes. Those +are used for using block ciphers in a way similar to stream ciphers, among +other things. + +=head1 OVERVIEW + +=head2 Electronic Codebook Mode (ECB) + +Normally, this is found as the function I<algorithm>_ecb_encrypt(). + +=over 2 + +=item * + +64 bits are enciphered at a time. + +=item * + +The order of the blocks can be rearranged without detection. + +=item * + +The same plaintext block always produces the same ciphertext block +(for the same key) making it vulnerable to a 'dictionary attack'. + +=item * + +An error will only affect one ciphertext block. + +=back + +=head2 Cipher Block Chaining Mode (CBC) + +Normally, this is found as the function I<algorithm>_cbc_encrypt(). +Be aware that des_cbc_encrypt() is not really DES CBC (it does +not update the IV); use des_ncbc_encrypt() instead. + +=over 2 + +=item * + +a multiple of 64 bits are enciphered at a time. + +=item * + +The CBC mode produces the same ciphertext whenever the same +plaintext is encrypted using the same key and starting variable. + +=item * + +The chaining operation makes the ciphertext blocks dependent on the +current and all preceding plaintext blocks and therefore blocks can not +be rearranged. + +=item * + +The use of different starting variables prevents the same plaintext +enciphering to the same ciphertext. + +=item * + +An error will affect the current and the following ciphertext blocks. + +=back + +=head2 Cipher Feedback Mode (CFB) + +Normally, this is found as the function I<algorithm>_cfb_encrypt(). + +=over 2 + +=item * + +a number of bits (j) <= 64 are enciphered at a time. + +=item * + +The CFB mode produces the same ciphertext whenever the same +plaintext is encrypted using the same key and starting variable. + +=item * + +The chaining operation makes the ciphertext variables dependent on the +current and all preceding variables and therefore j-bit variables are +chained together and can not be rearranged. + +=item * + +The use of different starting variables prevents the same plaintext +enciphering to the same ciphertext. + +=item * + +The strength of the CFB mode depends on the size of k (maximal if +j == k). In my implementation this is always the case. + +=item * + +Selection of a small value for j will require more cycles through +the encipherment algorithm per unit of plaintext and thus cause +greater processing overheads. + +=item * + +Only multiples of j bits can be enciphered. + +=item * + +An error will affect the current and the following ciphertext variables. + +=back + +=head2 Output Feedback Mode (OFB) + +Normally, this is found as the function I<algorithm>_ofb_encrypt(). + +=over 2 + + +=item * + +a number of bits (j) <= 64 are enciphered at a time. + +=item * + +The OFB mode produces the same ciphertext whenever the same +plaintext enciphered using the same key and starting variable. More +over, in the OFB mode the same key stream is produced when the same +key and start variable are used. Consequently, for security reasons +a specific start variable should be used only once for a given key. + +=item * + +The absence of chaining makes the OFB more vulnerable to specific attacks. + +=item * + +The use of different start variables values prevents the same +plaintext enciphering to the same ciphertext, by producing different +key streams. + +=item * + +Selection of a small value for j will require more cycles through +the encipherment algorithm per unit of plaintext and thus cause +greater processing overheads. + +=item * + +Only multiples of j bits can be enciphered. + +=item * + +OFB mode of operation does not extend ciphertext errors in the +resultant plaintext output. Every bit error in the ciphertext causes +only one bit to be in error in the deciphered plaintext. + +=item * + +OFB mode is not self-synchronizing. If the two operation of +encipherment and decipherment get out of synchronism, the system needs +to be re-initialized. + +=item * + +Each re-initialization should use a value of the start variable +different from the start variable values used before with the same +key. The reason for this is that an identical bit stream would be +produced each time from the same parameters. This would be +susceptible to a 'known plaintext' attack. + +=back + +=head2 Triple ECB Mode + +Normally, this is found as the function I<algorithm>_ecb3_encrypt(). + +=over 2 + +=item * + +Encrypt with key1, decrypt with key2 and encrypt with key3 again. + +=item * + +As for ECB encryption but increases the key length to 168 bits. +There are theoretic attacks that can be used that make the effective +key length 112 bits, but this attack also requires 2^56 blocks of +memory, not very likely, even for the NSA. + +=item * + +If both keys are the same it is equivalent to encrypting once with +just one key. + +=item * + +If the first and last key are the same, the key length is 112 bits. +There are attacks that could reduce the key space to 55 bit's but it +requires 2^56 blocks of memory. + +=item * + +If all 3 keys are the same, this is effectively the same as normal +ecb mode. + +=back + +=head2 Triple CBC Mode + +Normally, this is found as the function I<algorithm>_ede3_cbc_encrypt(). + +=over 2 + + +=item * + +Encrypt with key1, decrypt with key2 and then encrypt with key3. + +=item * + +As for CBC encryption but increases the key length to 168 bits with +the same restrictions as for triple ecb mode. + +=back + +=head1 NOTES + +This text was been written in large parts by Eric Young in his original +documentation for SSLeay, the predecessor of OpenSSL. In turn, he attributed +it to: + + AS 2805.5.2 + Australian Standard + Electronic funds transfer - Requirements for interfaces, + Part 5.2: Modes of operation for an n-bit block cipher algorithm + Appendix A + +=head1 SEE ALSO + +L<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<idea(3)|idea(3)>, +L<rc2(3)|rc2(3)> + +=cut + diff --git a/crypto/openssl/doc/crypto/dh.pod b/crypto/openssl/doc/crypto/dh.pod new file mode 100644 index 0000000..0a9b7c0 --- /dev/null +++ b/crypto/openssl/doc/crypto/dh.pod @@ -0,0 +1,68 @@ +=pod + +=head1 NAME + +dh - Diffie-Hellman key agreement + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + DH * DH_new(void); + void DH_free(DH *dh); + + int DH_size(DH *dh); + + DH * DH_generate_parameters(int prime_len, int generator, + void (*callback)(int, int, void *), void *cb_arg); + int DH_check(DH *dh, int *codes); + + int DH_generate_key(DH *dh); + int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); + + void DH_set_default_method(DH_METHOD *meth); + DH_METHOD *DH_get_default_method(void); + DH_METHOD *DH_set_method(DH *dh, DH_METHOD *meth); + DH *DH_new_method(DH_METHOD *meth); + DH_METHOD *DH_OpenSSL(void); + + int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(), + int (*dup_func)(), void (*free_func)()); + int DH_set_ex_data(DH *d, int idx, char *arg); + char *DH_get_ex_data(DH *d, int idx); + + DH * d2i_DHparams(DH **a, unsigned char **pp, long length); + int i2d_DHparams(DH *a, unsigned char **pp); + + int DHparams_print_fp(FILE *fp, DH *x); + int DHparams_print(BIO *bp, DH *x); + +=head1 DESCRIPTION + +These functions implement the Diffie-Hellman key agreement protocol. +The generation of shared DH parameters is described in +L<DH_generate_parameters(3)|DH_generate_parameters(3)>; L<DH_generate_key(3)|DH_generate_key(3)> describes how +to perform a key agreement. + +The B<DH> structure consists of several BIGNUM components. + + struct + { + BIGNUM *p; // prime number (shared) + BIGNUM *g; // generator of Z_p (shared) + BIGNUM *priv_key; // private DH value x + BIGNUM *pub_key; // public DH value g^x + // ... + }; + DH + +=head1 SEE ALSO + +L<dhparam(1)|dhparam(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, +L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<DH_set_method(3)|DH_set_method(3)>, +L<DH_new(3)|DH_new(3)>, L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>, +L<DH_generate_parameters(3)|DH_generate_parameters(3)>, +L<DH_compute_key(3)|DH_compute_key(3)>, L<d2i_DHparams(3)|d2i_DHparams(3)>, +L<RSA_print(3)|RSA_print(3)> + +=cut diff --git a/crypto/openssl/doc/crypto/dsa.pod b/crypto/openssl/doc/crypto/dsa.pod new file mode 100644 index 0000000..2c09244 --- /dev/null +++ b/crypto/openssl/doc/crypto/dsa.pod @@ -0,0 +1,104 @@ +=pod + +=head1 NAME + +dsa - Digital Signature Algorithm + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + DSA * DSA_new(void); + void DSA_free(DSA *dsa); + + int DSA_size(DSA *dsa); + + DSA * DSA_generate_parameters(int bits, unsigned char *seed, + int seed_len, int *counter_ret, unsigned long *h_ret, + void (*callback)(int, int, void *), void *cb_arg); + + DH * DSA_dup_DH(DSA *r); + + int DSA_generate_key(DSA *dsa); + + int DSA_sign(int dummy, const unsigned char *dgst, int len, + unsigned char *sigret, unsigned int *siglen, DSA *dsa); + int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, + BIGNUM **rp); + int DSA_verify(int dummy, const unsigned char *dgst, int len, + unsigned char *sigbuf, int siglen, DSA *dsa); + + void DSA_set_default_method(DSA_METHOD *meth); + DSA_METHOD *DSA_get_default_method(void); + DSA_METHOD *DSA_set_method(DSA *dsa, DSA_METHOD *meth); + DSA *DSA_new_method(DSA_METHOD *meth); + DSA_METHOD *DSA_OpenSSL(void); + + int DSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), + int (*dup_func)(), void (*free_func)()); + int DSA_set_ex_data(DSA *d, int idx, char *arg); + char *DSA_get_ex_data(DSA *d, int idx); + + DSA_SIG *DSA_SIG_new(void); + void DSA_SIG_free(DSA_SIG *a); + int i2d_DSA_SIG(DSA_SIG *a, unsigned char **pp); + DSA_SIG *d2i_DSA_SIG(DSA_SIG **v, unsigned char **pp, long length); + + DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); + int DSA_do_verify(const unsigned char *dgst, int dgst_len, + DSA_SIG *sig, DSA *dsa); + + DSA * d2i_DSAPublicKey(DSA **a, unsigned char **pp, long length); + DSA * d2i_DSAPrivateKey(DSA **a, unsigned char **pp, long length); + DSA * d2i_DSAparams(DSA **a, unsigned char **pp, long length); + int i2d_DSAPublicKey(DSA *a, unsigned char **pp); + int i2d_DSAPrivateKey(DSA *a, unsigned char **pp); + int i2d_DSAparams(DSA *a,unsigned char **pp); + + int DSAparams_print(BIO *bp, DSA *x); + int DSAparams_print_fp(FILE *fp, DSA *x); + int DSA_print(BIO *bp, DSA *x, int off); + int DSA_print_fp(FILE *bp, DSA *x, int off); + +=head1 DESCRIPTION + +These functions implement the Digital Signature Algorithm (DSA). The +generation of shared DSA parameters is described in +L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>; +L<DSA_generate_key(3)|DSA_generate_key(3)> describes how to +generate a signature key. Signature generation and verification are +described in L<DSA_sign(3)|DSA_sign(3)>. + +The B<DSA> structure consists of several BIGNUM components. + + struct + { + BIGNUM *p; // prime number (public) + BIGNUM *q; // 160-bit subprime, q | p-1 (public) + BIGNUM *g; // generator of subgroup (public) + BIGNUM *priv_key; // private key x + BIGNUM *pub_key; // public key y = g^x + // ... + } + DSA; + +In public keys, B<priv_key> is NULL. + +=head1 CONFORMING TO + +US Federal Information Processing Standard FIPS 186 (Digital Signature +Standard, DSS), ANSI X9.30 + +=head1 SEE ALSO + +L<bn(3)|bn(3)>, L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, +L<rsa(3)|rsa(3)>, L<sha(3)|sha(3)>, L<DSA_new(3)|DSA_new(3)>, +L<DSA_size(3)|DSA_size(3)>, +L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>, +L<DSA_dup_DH(3)|DSA_dup_DH(3)>, +L<DSA_generate_key(3)|DSA_generate_key(3)>, +L<DSA_sign(3)|DSA_sign(3)>, L<DSA_set_method(3)|DSA_set_method(3)>, +L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>, +L<RSA_print(3)|RSA_print(3)> + +=cut diff --git a/crypto/openssl/doc/crypto/err.pod b/crypto/openssl/doc/crypto/err.pod new file mode 100644 index 0000000..264e301 --- /dev/null +++ b/crypto/openssl/doc/crypto/err.pod @@ -0,0 +1,187 @@ +=pod + +=head1 NAME + +err - error codes + +=head1 SYNOPSIS + + #include <openssl/err.h> + + unsigned long ERR_get_error(void); + unsigned long ERR_peek_error(void); + unsigned long ERR_get_error_line(const char **file, int *line); + unsigned long ERR_peek_error_line(const char **file, int *line); + unsigned long ERR_get_error_line_data(const char **file, int *line, + const char **data, int *flags); + unsigned long ERR_peek_error_line_data(const char **file, int *line, + const char **data, int *flags); + + int ERR_GET_LIB(unsigned long e); + int ERR_GET_FUNC(unsigned long e); + int ERR_GET_REASON(unsigned long e); + + void ERR_clear_error(void); + + char *ERR_error_string(unsigned long e, char *buf); + const char *ERR_lib_error_string(unsigned long e); + const char *ERR_func_error_string(unsigned long e); + const char *ERR_reason_error_string(unsigned long e); + + void ERR_print_errors(BIO *bp); + void ERR_print_errors_fp(FILE *fp); + + void ERR_load_crypto_strings(void); + void ERR_free_strings(void); + + void ERR_remove_state(unsigned long pid); + + void ERR_put_error(int lib, int func, int reason, const char *file, + int line); + void ERR_add_error_data(int num, ...); + + void ERR_load_strings(int lib,ERR_STRING_DATA str[]); + unsigned long ERR_PACK(int lib, int func, int reason); + int ERR_get_next_error_library(void); + +=head1 DESCRIPTION + +When a call to the OpenSSL library fails, this is usually signalled +by the return value, and an error code is stored in an error queue +associated with the current thread. The B<err> library provides +functions to obtain these error codes and textual error messages. + +The L<ERR_get_error(3)|ERR_get_error(3)> manpage describes how to +access error codes. + +Error codes contain information about where the error occurred, and +what went wrong. L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> describes how to +extract this information. A method to obtain human-readable error +messages is described in L<ERR_error_string(3)|ERR_error_string(3)>. + +L<ERR_clear_error(3)|ERR_clear_error(3)> can be used to clear the +error queue. + +Note that L<ERR_remove_state(3)|ERR_remove_state(3)> should be used to +avoid memory leaks when threads are terminated. + +=head1 ADDING NEW ERROR CODES TO OPENSSL + +See L<ERR_put_error(3)> if you want to record error codes in the +OpenSSL error system from within your application. + +The remainder of this section is of interest only if you want to add +new error codes to OpenSSL or add error codes from external libraries. + +=head2 Reporting errors + +Each sub-library has a specific macro XXXerr() that is used to report +errors. Its first argument is a function code B<XXX_F_...>, the second +argument is a reason code B<XXX_R_...>. Function codes are derived +from the function names; reason codes consist of textual error +descriptions. For example, the function ssl23_read() reports a +"handshake failure" as follows: + + SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE); + +Function and reason codes should consist of upper case characters, +numbers and underscores only. The error file generation script translates +function codes into function names by looking in the header files +for an appropriate function name, if none is found it just uses +the capitalized form such as "SSL23_READ" 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<make errors>. +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 +the ASN1err() macro. + +=head2 Adding new libraries + +When adding a new sub-library to OpenSSL, assign it a library number +B<ERR_LIB_XXX>, define a macro XXXerr() (both in B<err.h>), add its +name to B<ERR_str_libraries[]> (in B<crypto/err/err.c>), and add +C<ERR_load_XXX_strings()> to the ERR_load_crypto_strings() function +(in B<crypto/err/err_all.c>). Finally, add an entry + + L XXX xxx.h xxx_err.c + +to B<crypto/err/openssl.ec>, and add B<xxx_err.c> to the Makefile. +Running B<make errors> will then generate a file B<xxx_err.c>, and +add all error codes used in the library to B<xxx.h>. + +Additionally the library include file must have a certain form. +Typically it will initially look like this: + + #ifndef HEADER_XXX_H + #define HEADER_XXX_H + + #ifdef __cplusplus + extern "C" { + #endif + + /* Include files */ + + #include <openssl/bio.h> + #include <openssl/x509.h> + + /* Macros, structures and function prototypes */ + + + /* BEGIN ERROR CODES */ + +The B<BEGIN ERROR CODES> sequence is used by the error code +generation script as the point to place new error codes, any text +after this point will be overwritten when B<make errors> is run. +The closing #endif etc will be automatically added by the script. + +The generated C error code file B<xxx_err.c> will load the header +files B<stdio.h>, B<openssl/err.h> and B<openssl/xxx.h> so the +header file must load any additional header files containing any +definitions it uses. + +=head1 USING ERROR CODES IN EXTERNAL LIBRARIES + +It is also possible to use OpenSSL's error code scheme in external +libraries. The library needs to load its own codes and call the OpenSSL +error code insertion script B<mkerr.pl> explicitly to add codes to +the header file and generate the C error code file. This will normally +be done if the external library needs to generate new ASN1 structures +but it can also be used to add more general purpose error code handling. + +TBA more details + +=head1 INTERNALS + +The error queues are stored in a hash table with one B<ERR_STATE> +entry for each pid. ERR_get_state() returns the current thread's +B<ERR_STATE>. An B<ERR_STATE> can hold up to B<ERR_NUM_ERRORS> error +codes. When more error codes are added, the old ones are overwritten, +on the assumption that the most recent errors are most important. + +Error strings are also stored in hash table. The hash tables can +be obtained by calling ERR_get_err_state_table(void) and +ERR_get_string_table(void) respectively. + +=head1 SEE ALSO + +L<CRYPTO_set_id_callback(3)|CRYPTO_set_id_callback(3)>, +L<CRYPTO_set_locking_callback(3)|<CRYPTO_set_locking_callback(3)>, +L<ERR_get_error(3)|ERR_get_error(3)>, +L<ERR_GET_LIB(3)|ERR_GET_LIB(3)>, +L<ERR_clear_error(3)|ERR_clear_error(3)>, +L<ERR_error_string(3)|ERR_error_string(3)>, +L<ERR_print_errors(3)|ERR_print_errors(3)>, +L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, +L<ERR_remove_state(3)|ERR_remove_state(3)>, +L<ERR_put_error(3)|ERR_put_error(3)>, +L<ERR_load_strings(3)|ERR_load_strings(3)>, +L<SSL_get_error(3)|SSL_get_error(3)> + +=cut diff --git a/crypto/openssl/doc/crypto/evp.pod b/crypto/openssl/doc/crypto/evp.pod new file mode 100644 index 0000000..f089dd4 --- /dev/null +++ b/crypto/openssl/doc/crypto/evp.pod @@ -0,0 +1,37 @@ +=pod + +=head1 NAME + +evp - high-level cryptographic functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + +=head1 DESCRIPTION + +The EVP library provided a high-level interface to cryptographic +functions. + +B<EVP_Seal>I<...> and B<EVP_Open>I<...> provide public key encryption +and decryption to implement digital "envelopes". + +The B<EVP_Sign>I<...> and B<EVP_Verify>I<...> functions implement +digital signatures. + +Symmetric encryption is available with the B<EVP_Encrypt>I<...> +functions. The B<EVP_Digest>I<...> functions provide message digests. + +Algorithms are loaded with OpenSSL_add_all_algorithms(3). + +=head1 SEE ALSO + +L<EVP_DigestInit(3)|EVP_DigestInit(3)>, +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, +L<EVP_OpenInit(3)|EVP_OpenInit(3)>, +L<EVP_SealInit(3)|EVP_SealInit(3)>, +L<EVP_SignInit(3)|EVP_SignInit(3)>, +L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, +L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)> + +=cut diff --git a/crypto/openssl/doc/crypto/hmac.pod b/crypto/openssl/doc/crypto/hmac.pod new file mode 100644 index 0000000..f86e7d7 --- /dev/null +++ b/crypto/openssl/doc/crypto/hmac.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + +HMAC, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_cleanup - HMAC message +authentication code + +=head1 SYNOPSIS + + #include <openssl/hmac.h> + + unsigned char *HMAC(const EVP_MD *evp_md, const void *key, + int key_len, const unsigned char *d, int n, + unsigned char *md, unsigned int *md_len); + + void HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, + const EVP_MD *md); + void HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len); + void HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); + + void HMAC_cleanup(HMAC_CTX *ctx); + +=head1 DESCRIPTION + +HMAC is a MAC (message authentication code), i.e. a keyed hash +function used for message authentication, which is based on a hash +function. + +HMAC() computes the message authentication code of the B<n> bytes at +B<d> using the hash function B<evp_md> and the key B<key> which is +B<key_len> bytes long. + +It places the result in B<md> (which must have space for the output of +the hash function, which is no more than B<EVP_MAX_MD_SIZE> bytes). +If B<md> is NULL, the digest is placed in a static array. The size of +the output is placed in B<md_len>, unless it is B<NULL>. + +B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc. +B<key> and B<evp_md> may be B<NULL> if a key and hash function have +been set in a previous call to HMAC_Init() for that B<HMAC_CTX>. + +HMAC_cleanup() erases the key and other data from the B<HMAC_CTX>. + +The following functions may be used if the message is not completely +stored in memory: + +HMAC_Init() initializes a B<HMAC_CTX> structure to use the hash +function B<evp_md> and the key B<key> which is B<key_len> bytes long. + +HMAC_Update() can be called repeatedly with chunks of the message to +be authenticated (B<len> bytes at B<data>). + +HMAC_Final() places the message authentication code in B<md>, which +must have space for the hash function output. + +=head1 RETURN VALUES + +HMAC() returns a pointer to the message authentication code. + +HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup() do not +return values. + +=head1 CONFORMING TO + +RFC 2104 + +=head1 SEE ALSO + +L<sha(3)|sha(3)>, L<evp(3)|evp(3)> + +=head1 HISTORY + +HMAC(), HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup() +are available since SSLeay 0.9.0. + +=cut diff --git a/crypto/openssl/doc/crypto/lh_stats.pod b/crypto/openssl/doc/crypto/lh_stats.pod new file mode 100644 index 0000000..3eeaa72 --- /dev/null +++ b/crypto/openssl/doc/crypto/lh_stats.pod @@ -0,0 +1,60 @@ +=pod + +=head1 NAME + +lh_stats, lh_node_stats, lh_node_usage_stats, lh_stats_bio, +lh_node_stats_bio, lh_node_usage_stats_bio - LHASH statistics + +=head1 SYNOPSIS + + #include <openssl/lhash.h> + + void lh_stats(LHASH *table, FILE *out); + void lh_node_stats(LHASH *table, FILE *out); + void lh_node_usage_stats(LHASH *table, FILE *out); + + void lh_stats_bio(LHASH *table, BIO *out); + void lh_node_stats_bio(LHASH *table, BIO *out); + void lh_node_usage_stats_bio(LHASH *table, BIO *out); + +=head1 DESCRIPTION + +The B<LHASH> structure records statistics about most aspects of +accessing the hash table. This is mostly a legacy of Eric Young +writing this library for the reasons of implementing what looked like +a nice algorithm rather than for a particular software product. + +lh_stats() prints out statistics on the size of the hash table, how +many entries are in it, and the number and result of calls to the +routines in this library. + +lh_node_stats() prints the number of entries for each 'bucket' in the +hash table. + +lh_node_usage_stats() prints out a short summary of the state of the +hash table. It prints the 'load' and the 'actual load'. The load is +the average number of data items per 'bucket' in the hash table. The +'actual load' is the average number of items per 'bucket', but only +for buckets which contain entries. So the 'actual load' is the +average number of searches that will need to find an item in the hash +table, while the 'load' is the average number that will be done to +record a miss. + +lh_stats_bio(), lh_node_stats_bio() and lh_node_usage_stats_bio() +are the same as the above, except that the output goes to a B<BIO>. + +=head1 RETURN VALUES + +These functions do not return values. + +=head1 SEE ALSO + +L<bio(3)|bio(3)>, L<lhash(3)|lhash(3)> + +=head1 HISTORY + +These functions are available in all versions of SSLeay and OpenSSL. + +This manpage is derived from the SSLeay documentation. + +=cut diff --git a/crypto/openssl/doc/crypto/lhash.pod b/crypto/openssl/doc/crypto/lhash.pod new file mode 100644 index 0000000..4e87aee --- /dev/null +++ b/crypto/openssl/doc/crypto/lhash.pod @@ -0,0 +1,155 @@ +=pod + +=head1 NAME + +lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, +lh_doall_arg, lh_error - dynamic hash table + +=head1 SYNOPSIS + + #include <openssl/lhash.h> + + LHASH *lh_new(unsigned long (*hash)(/*void *a*/), + int (*compare)(/*void *a,void *b*/)); + void lh_free(LHASH *table); + + void *lh_insert(LHASH *table, void *data); + void *lh_delete(LHASH *table, void *data); + void *lh_retrieve(LHASH *table, void *data); + + void lh_doall(LHASH *table, void (*func)(/*void *b*/)); + void lh_doall_arg(LHASH *table, void (*func)(/*void *a,void *b*/), + void *arg); + + int lh_error(LHASH *table); + +=head1 DESCRIPTION + +This library implements dynamic hash tables. The hash table entries +can be arbitrary structures. Usually they consist of key and value +fields. + +lh_new() creates a new B<LHASH> structure. B<hash> takes a pointer to +the structure and returns an unsigned long hash value of 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. B<compare> takes two arguments, and returns 0 if their keys are +equal, non-zero otherwise. + +lh_free() frees the B<LHASH> structure B<table>. Allocated hash table +entries will not be freed; consider using lh_doall() to deallocate any +remaining entries in the hash table. + +lh_insert() inserts the structure pointed to by B<data> into B<table>. +If there already is an entry with the same key, the old value is +replaced. Note that lh_insert() stores pointers, the data are not +copied. + +lh_delete() deletes an entry from B<table>. + +lh_retrieve() looks up an entry in B<table>. Normally, B<data> is +a structure with the key field(s) set; the function will return a +pointer to a fully populated structure. + +lh_doall() will, for every entry in the hash table, call B<func> with +the data item as parameters. +This function can be quite useful when used as follows: + void cleanup(STUFF *a) + { STUFF_free(a); } + lh_doall(hash,cleanup); + lh_free(hash); +This can be used to free all the entries. lh_free() then cleans up the +'buckets' that point to nothing. When doing this, be careful if you +delete entries from the hash table in B<func>: the table may decrease +in size, moving item that you are currently on down lower in the hash +table. This could cause some entries to be skipped. The best +solution to this problem is to set hash-E<gt>down_load=0 before you +start. This will stop the hash table ever being decreased in size. + +lh_doall_arg() is the same as lh_doall() except that B<func> will +be called with B<arg> as the second argument. + +lh_error() can be used to determine if an error occurred in the last +operation. lh_error() is a macro. + +=head1 RETURN VALUES + +lh_new() returns B<NULL> on error, otherwise a pointer to the new +B<LHASH> structure. + +When a hash table entry is replaced, lh_insert() returns the value +being replaced. B<NULL> is returned on normal operation and on error. + +lh_delete() returns the entry being deleted. B<NULL> is returned if +there is no such value in the hash table. + +lh_retrieve() returns the hash table entry if it has been found, +B<NULL> otherwise. + +lh_error() returns 1 if an error occurred in the last operation, 0 +otherwise. + +lh_free(), lh_doall() and lh_doall_arg() return no values. + +=head1 BUGS + +lh_insert() returns B<NULL> both for success and error. + +=head1 INTERNALS + +The following description is based on the SSLeay documentation: + +The B<lhash> library implements a hash table described in the +I<Communications of the ACM> in 1991. What makes this hash table +different is that as the table fills, the hash table is increased (or +decreased) in size via OPENSSL_realloc(). When a 'resize' is done, instead of +all hashes being redistributed over twice as many 'buckets', one +bucket is split. So when an 'expand' is done, there is only a minimal +cost to redistribute some values. Subsequent inserts will cause more +single 'bucket' redistributions but there will never be a sudden large +cost due to redistributing all the 'buckets'. + +The state for a particular hash table is kept in the B<LHASH> structure. +The decision to increase or decrease the hash table size is made +depending on the 'load' of the hash table. The load is the number of +items in the hash table divided by the size of the hash table. The +default values are as follows. If (hash->up_load E<lt> load) =E<gt> +expand. if (hash-E<gt>down_load E<gt> load) =E<gt> contract. The +B<up_load> has a default value of 1 and B<down_load> has a default value +of 2. These numbers can be modified by the application by just +playing with the B<up_load> and B<down_load> variables. The 'load' is +kept in a form which is multiplied by 256. So +hash-E<gt>up_load=8*256; will cause a load of 8 to be set. + +If you are interested in performance the field to watch is +num_comp_calls. The hash library keeps track of the 'hash' value for +each item so when a lookup is done, the 'hashes' are compared, if +there is a match, then a full compare is done, and +hash-E<gt>num_comp_calls is incremented. If num_comp_calls is not equal +to num_delete plus num_retrieve it means that your hash function is +generating hashes that are the same for different values. It is +probably worth changing your hash function if this is the case because +even if your hash table has 10 items in a 'bucket', it can be searched +with 10 B<unsigned long> compares and 10 linked list traverses. This +will be much less expensive that 10 calls to you compare function. + +lh_strhash() is a demo string hashing function: + + unsigned long lh_strhash(const char *c); + +Since the B<LHASH> routines would normally be passed structures, this +routine would not normally be passed to lh_new(), rather it would be +used in the function passed to lh_new(). + +=head1 SEE ALSO + +L<lh_stats(3)|lh_stats(3)> + +=head1 HISTORY + +The B<lhash> library is available in all versions of SSLeay and OpenSSL. +lh_error() was added in SSLeay 0.9.1b. + +This manpage is derived from the SSLeay documentation. + +=cut diff --git a/crypto/openssl/doc/crypto/md5.pod b/crypto/openssl/doc/crypto/md5.pod new file mode 100644 index 0000000..6e6322d --- /dev/null +++ b/crypto/openssl/doc/crypto/md5.pod @@ -0,0 +1,101 @@ +=pod + +=head1 NAME + +MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update, +MD4_Final, MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions + +=head1 SYNOPSIS + + #include <openssl/md2.h> + + unsigned char *MD2(const unsigned char *d, unsigned long n, + unsigned char *md); + + void MD2_Init(MD2_CTX *c); + void MD2_Update(MD2_CTX *c, const unsigned char *data, + unsigned long len); + void MD2_Final(unsigned char *md, MD2_CTX *c); + + + #include <openssl/md4.h> + + unsigned char *MD4(const unsigned char *d, unsigned long n, + unsigned char *md); + + void MD4_Init(MD4_CTX *c); + void MD4_Update(MD4_CTX *c, const void *data, + unsigned long len); + void MD4_Final(unsigned char *md, MD4_CTX *c); + + + #include <openssl/md5.h> + + unsigned char *MD5(const unsigned char *d, unsigned long n, + unsigned char *md); + + void MD5_Init(MD5_CTX *c); + void MD5_Update(MD5_CTX *c, const void *data, + unsigned long len); + void MD5_Final(unsigned char *md, MD5_CTX *c); + +=head1 DESCRIPTION + +MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output. + +MD2(), MD4(), and MD5() compute the MD2, MD4, and MD5 message digest +of the B<n> bytes at B<d> and place it in B<md> (which must have space +for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16 +bytes of output). If B<md> is NULL, the digest is placed in a static +array. + +The following functions may be used if the message is not completely +stored in memory: + +MD2_Init() initializes a B<MD2_CTX> structure. + +MD2_Update() can be called repeatedly with chunks of the message to +be hashed (B<len> bytes at B<data>). + +MD2_Final() places the message digest in B<md>, which must have space +for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MD2_CTX>. + +MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and +MD5_Final() are analogous using an B<MD4_CTX> and B<MD5_CTX> structure. + +Applications should use the higher level functions +L<EVP_DigestInit(3)|EVP_DigestInit(3)> +etc. instead of calling the hash functions directly. + +=head1 NOTE + +MD2, MD4, and MD5 are recommended only for compatibility with existing +applications. In new applications, SHA-1 or RIPEMD-160 should be +preferred. + +=head1 RETURN VALUES + +MD2(), MD4(), and MD5() return pointers to the hash value. + +MD2_Init(), MD2_Update(), MD2_Final(), MD4_Init(), MD4_Update(), +MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() do not return +values. + +=head1 CONFORMING TO + +RFC 1319, RFC 1320, RFC 1321 + +=head1 SEE ALSO + +L<sha(3)|sha(3)>, L<ripemd(3)|ripemd(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> + +=head1 HISTORY + +MD2(), MD2_Init(), MD2_Update() MD2_Final(), MD5(), MD5_Init(), +MD5_Update() and MD5_Final() are available in all versions of SSLeay +and OpenSSL. + +MD4(), MD4_Init(), and MD4_Update() are available in OpenSSL 0.9.6 and +above. + +=cut diff --git a/crypto/openssl/doc/crypto/mdc2.pod b/crypto/openssl/doc/crypto/mdc2.pod new file mode 100644 index 0000000..11dc303 --- /dev/null +++ b/crypto/openssl/doc/crypto/mdc2.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +MDC2, MDC2_Init, MDC2_Update, MDC2_Final - MDC2 hash function + +=head1 SYNOPSIS + + #include <openssl/mdc2.h> + + unsigned char *MDC2(const unsigned char *d, unsigned long n, + unsigned char *md); + + void MDC2_Init(MDC2_CTX *c); + void MDC2_Update(MDC2_CTX *c, const unsigned char *data, + unsigned long len); + void MDC2_Final(unsigned char *md, MDC2_CTX *c); + +=head1 DESCRIPTION + +MDC2 is a method to construct hash functions with 128 bit output from +block ciphers. These functions are an implementation of MDC2 with +DES. + +MDC2() computes the MDC2 message digest of the B<n> +bytes at B<d> and places it in B<md> (which must have space for +MDC2_DIGEST_LENGTH == 16 bytes of output). If B<md> is NULL, the digest +is placed in a static array. + +The following functions may be used if the message is not completely +stored in memory: + +MDC2_Init() initializes a B<MDC2_CTX> structure. + +MDC2_Update() can be called repeatedly with chunks of the message to +be hashed (B<len> bytes at B<data>). + +MDC2_Final() places the message digest in B<md>, which must have space +for MDC2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MDC2_CTX>. + +Applications should use the higher level functions +L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the +hash functions directly. + +=head1 RETURN VALUES + +MDC2() returns a pointer to the hash value. + +MDC2_Init(), MDC2_Update() and MDC2_Final() do not return values. + +=head1 CONFORMING TO + +ISO/IEC 10118-2, with DES + +=head1 SEE ALSO + +L<sha(3)|sha(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> + +=head1 HISTORY + +MDC2(), MDC2_Init(), MDC2_Update() and MDC2_Final() are available since +SSLeay 0.8. + +=cut diff --git a/crypto/openssl/doc/crypto/rand.pod b/crypto/openssl/doc/crypto/rand.pod new file mode 100644 index 0000000..295b681 --- /dev/null +++ b/crypto/openssl/doc/crypto/rand.pod @@ -0,0 +1,158 @@ +=pod + +=head1 NAME + +rand - pseudo-random number generator + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + int RAND_bytes(unsigned char *buf,int num); + int RAND_pseudo_bytes(unsigned char *buf,int num); + + void RAND_seed(const void *buf,int num); + void RAND_add(const void *buf,int num,int entropy); + int RAND_status(void); + void RAND_screen(void); + + int RAND_load_file(const char *file,long max_bytes); + int RAND_write_file(const char *file); + const char *RAND_file_name(char *file,int num); + + int RAND_egd(const char *path); + + void RAND_set_rand_method(RAND_METHOD *meth); + RAND_METHOD *RAND_get_rand_method(void); + RAND_METHOD *RAND_SSLeay(void); + + void RAND_cleanup(void); + +=head1 DESCRIPTION + +These functions implement a cryptographically secure pseudo-random +number generator (PRNG). It is used by other library functions for +example to generate random keys, and applications can use it when they +need randomness. + +A cryptographic PRNG must be seeded with unpredictable data such as +mouse movements or keys pressed at random by the user. This is +described in L<RAND_add(3)|RAND_add(3)>. Its state can be saved in a seed file +(see L<RAND_load_file(3)|RAND_load_file(3)>) to avoid having to go through the +seeding process whenever the application is started. + +L<RAND_bytes(3)|RAND_bytes(3)> describes how to obtain random data from the +PRNG. + +=head1 INTERNALS + +The RAND_SSLeay() method implements a PRNG based on a cryptographic +hash function. + +The following description of its design is based on the SSLeay +documentation: + +First up I will state the things I believe I need for a good RNG. + +=over 4 + +=item 1 + +A good hashing algorithm to mix things up and to convert the RNG 'state' +to random numbers. + +=item 2 + +An initial source of random 'state'. + +=item 3 + +The state should be very large. If the RNG is being used to generate +4096 bit RSA keys, 2 2048 bit random strings are required (at a minimum). +If your RNG state only has 128 bits, you are obviously limiting the +search space to 128 bits, not 2048. I'm probably getting a little +carried away on this last point but it does indicate that it may not be +a bad idea to keep quite a lot of RNG state. It should be easier to +break a cipher than guess the RNG seed data. + +=item 4 + +Any RNG seed data should influence all subsequent random numbers +generated. This implies that any random seed data entered will have +an influence on all subsequent random numbers generated. + +=item 5 + +When using data to seed the RNG state, the data used should not be +extractable from the RNG state. I believe this should be a +requirement because one possible source of 'secret' semi random +data would be a private key or a password. This data must +not be disclosed by either subsequent random numbers or a +'core' dump left by a program crash. + +=item 6 + +Given the same initial 'state', 2 systems should deviate in their RNG state +(and hence the random numbers generated) over time if at all possible. + +=item 7 + +Given the random number output stream, it should not be possible to determine +the RNG state or the next random number. + +=back + +The algorithm is as follows. + +There is global state made up of a 1023 byte buffer (the 'state'), a +working hash value ('md'), and a counter ('count'). + +Whenever seed data is added, it is inserted into the 'state' as +follows. + +The input is chopped up into units of 20 bytes (or less for +the last block). Each of these blocks is run through the hash +function as follows: The data passed to the hash function +is the current 'md', the same number of bytes from the 'state' +(the location determined by in incremented looping index) as +the current 'block', the new key data 'block', and 'count' +(which is incremented after each use). +The result of this is kept in 'md' and also xored into the +'state' at the same locations that were used as input into the +hash function. I +believe this system addresses points 1 (hash function; currently +SHA-1), 3 (the 'state'), 4 (via the 'md'), 5 (by the use of a hash +function and xor). + +When bytes are extracted from the RNG, the following process is used. +For each group of 10 bytes (or less), we do the following: + +Input into the hash function the top 10 bytes from the local 'md' +(which is initialized from the global 'md' before any bytes are +generated), the bytes that are to be overwritten by the random bytes, +and bytes from the 'state' (incrementing looping index). From this +digest output (which is kept in 'md'), the top (up to) 10 bytes are +returned to the caller and the bottom (up to) 10 bytes are xored into +the 'state'. + +Finally, after we have finished 'num' random bytes for the caller, +'count' (which is incremented) and the local and global 'md' are fed +into the hash function and the results are kept in the global 'md'. + +I believe the above addressed points 1 (use of SHA-1), 6 (by hashing +into the 'state' the 'old' data from the caller that is about to be +overwritten) and 7 (by not using the 10 bytes given to the caller to +update the 'state', but they are used to update 'md'). + +So of the points raised, only 2 is not addressed (but see +L<RAND_add(3)|RAND_add(3)>). + +=head1 SEE ALSO + +L<BN_rand(3)|BN_rand(3)>, L<RAND_add(3)|RAND_add(3)>, +L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_egd(3)|RAND_egd(3)>, +L<RAND_bytes(3)|RAND_bytes(3)>, +L<RAND_set_rand_method(3)|RAND_set_rand_method(3)>, +L<RAND_cleanup(3)|RAND_cleanup(3)> + +=cut diff --git a/crypto/openssl/doc/crypto/rc4.pod b/crypto/openssl/doc/crypto/rc4.pod new file mode 100644 index 0000000..b6d3a43 --- /dev/null +++ b/crypto/openssl/doc/crypto/rc4.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +RC4_set_key, RC4 - RC4 encryption + +=head1 SYNOPSIS + + #include <openssl/rc4.h> + + void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data); + + void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata, + unsigned char *outdata); + +=head1 DESCRIPTION + +This library implements the Alleged RC4 cipher, which is described for +example in I<Applied Cryptography>. It is believed to be compatible +with RC4[TM], a proprietary cipher of RSA Security Inc. + +RC4 is a stream cipher with variable key length. Typically, 128 bit +(16 byte) keys are used for strong encryption, but shorter insecure +key sizes have been widely used due to export restrictions. + +RC4 consists of a key setup phase and the actual encryption or +decryption phase. + +RC4_set_key() sets up the B<RC4_KEY> B<key> using the B<len> bytes long +key at B<data>. + +RC4() encrypts or decrypts the B<len> bytes of data at B<indata> using +B<key> and places the result at B<outdata>. Repeated RC4() calls with +the same B<key> yield a continuous key stream. + +Since RC4 is a stream cipher (the input is XORed with a pseudo-random +key stream to produce the output), decryption uses the same function +calls as encryption. + +Applications should use the higher level functions +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> +etc. instead of calling the RC4 functions directly. + +=head1 RETURN VALUES + +RC4_set_key() and RC4() do not return values. + +=head1 NOTE + +Certain conditions have to be observed to securely use stream ciphers. +It is not permissible to perform multiple encryptions using the same +key stream. + +=head1 SEE ALSO + +L<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<rc2(3)|rc2(3)> + +=head1 HISTORY + +RC4_set_key() and RC4() are available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/ripemd.pod b/crypto/openssl/doc/crypto/ripemd.pod new file mode 100644 index 0000000..31054b6 --- /dev/null +++ b/crypto/openssl/doc/crypto/ripemd.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final - +RIPEMD-160 hash function + +=head1 SYNOPSIS + + #include <openssl/ripemd.h> + + unsigned char *RIPEMD160(const unsigned char *d, unsigned long n, + unsigned char *md); + + void RIPEMD160_Init(RIPEMD160_CTX *c); + void RIPEMD160_Update(RIPEMD_CTX *c, const void *data, + unsigned long len); + void RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c); + +=head1 DESCRIPTION + +RIPEMD-160 is a cryptographic hash function with a +160 bit output. + +RIPEMD160() computes the RIPEMD-160 message digest of the B<n> +bytes at B<d> and places it in B<md> (which must have space for +RIPEMD160_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest +is placed in a static array. + +The following functions may be used if the message is not completely +stored in memory: + +RIPEMD160_Init() initializes a B<RIPEMD160_CTX> structure. + +RIPEMD160_Update() can be called repeatedly with chunks of the message to +be hashed (B<len> bytes at B<data>). + +RIPEMD160_Final() places the message digest in B<md>, which must have +space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases +the B<RIPEMD160_CTX>. + +Applications should use the higher level functions +L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the +hash functions directly. + +=head1 RETURN VALUES + +RIPEMD160() returns a pointer to the hash value. + +RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() do not +return values. + +=head1 CONFORMING TO + +ISO/IEC 10118-3 (draft) (??) + +=head1 SEE ALSO + +L<sha(3)|sha(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> + +=head1 HISTORY + +RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and +RIPEMD160_Final() are available since SSLeay 0.9.0. + +=cut diff --git a/crypto/openssl/doc/crypto/rsa.pod b/crypto/openssl/doc/crypto/rsa.pod new file mode 100644 index 0000000..1633840 --- /dev/null +++ b/crypto/openssl/doc/crypto/rsa.pod @@ -0,0 +1,116 @@ +=pod + +=head1 NAME + +rsa - RSA public key cryptosystem + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + RSA * RSA_new(void); + void RSA_free(RSA *rsa); + + int RSA_public_encrypt(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + int RSA_private_decrypt(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + int RSA_sign(int type, unsigned char *m, unsigned int m_len, + unsigned char *sigret, unsigned int *siglen, RSA *rsa); + int RSA_verify(int type, unsigned char *m, unsigned int m_len, + unsigned char *sigbuf, unsigned int siglen, RSA *rsa); + + int RSA_size(RSA *rsa); + + RSA *RSA_generate_key(int num, unsigned long e, + void (*callback)(int,int,void *), void *cb_arg); + + int RSA_check_key(RSA *rsa); + + int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); + void RSA_blinding_off(RSA *rsa); + + void RSA_set_default_method(RSA_METHOD *meth); + RSA_METHOD *RSA_get_default_method(void); + RSA_METHOD *RSA_set_method(RSA *rsa, RSA_METHOD *meth); + RSA_METHOD *RSA_get_method(RSA *rsa); + RSA_METHOD *RSA_PKCS1_SSLeay(void); + RSA_METHOD *RSA_PKCS1_RSAref(void); + RSA_METHOD *RSA_null_method(void); + int RSA_flags(RSA *rsa); + RSA *RSA_new_method(RSA_METHOD *method); + + int RSA_print(BIO *bp, RSA *x, int offset); + int RSA_print_fp(FILE *fp, RSA *x, int offset); + + int RSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), + int (*dup_func)(), void (*free_func)()); + int RSA_set_ex_data(RSA *r,int idx,char *arg); + char *RSA_get_ex_data(RSA *r, int idx); + + int RSA_private_encrypt(int flen, unsigned char *from, + unsigned char *to, RSA *rsa,int padding); + int RSA_public_decrypt(int flen, unsigned char *from, + unsigned char *to, RSA *rsa,int padding); + + int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, + unsigned int m_len, unsigned char *sigret, unsigned int *siglen, + RSA *rsa); + int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m, + unsigned int m_len, unsigned char *sigbuf, unsigned int siglen, + RSA *rsa); + +=head1 DESCRIPTION + +These functions implement RSA public key encryption and signatures +as defined in PKCS #1 v2.0 [RFC 2437]. + +The B<RSA> structure consists of several BIGNUM components. It can +contain public as well as private RSA keys: + + struct + { + BIGNUM *n; // public modulus + BIGNUM *e; // public exponent + BIGNUM *d; // private exponent + BIGNUM *p; // secret prime factor + BIGNUM *q; // secret prime factor + BIGNUM *dmp1; // d mod (p-1) + BIGNUM *dmq1; // d mod (q-1) + BIGNUM *iqmp; // q^-1 mod p + // ... + }; + RSA + +In public keys, the private exponent and the related secret values are +B<NULL>. + +B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp> may be B<NULL> in private +keys, but the RSA operations are much faster when these values are +available. + +=head1 CONFORMING TO + +SSL, PKCS #1 v2.0 + +=head1 PATENTS + +RSA was covered by a US patent which expired in September 2000. + +=head1 SEE ALSO + +L<rsa(1)|rsa(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, +L<rand(3)|rand(3)>, L<RSA_new(3)|RSA_new(3)>, +L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>, +L<RSA_sign(3)|RSA_sign(3)>, L<RSA_size(3)|RSA_size(3)>, +L<RSA_generate_key(3)|RSA_generate_key(3)>, +L<RSA_check_key(3)|RSA_check_key(3)>, +L<RSA_blinding_on(3)|RSA_blinding_on(3)>, +L<RSA_set_method(3)|RSA_set_method(3)>, L<RSA_print(3)|RSA_print(3)>, +L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, +L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>, +L<RSA_sign_ASN_OCTET_STRING(3)|RSA_sign_ASN_OCTET_STRING(3)>, +L<RSA_padding_add_PKCS1_type_1(3)|RSA_padding_add_PKCS1_type_1(3)> + +=cut diff --git a/crypto/openssl/doc/crypto/sha.pod b/crypto/openssl/doc/crypto/sha.pod new file mode 100644 index 0000000..0ba315d --- /dev/null +++ b/crypto/openssl/doc/crypto/sha.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +SHA1, SHA1_Init, SHA1_Update, SHA1_Final - Secure Hash Algorithm + +=head1 SYNOPSIS + + #include <openssl/sha.h> + + unsigned char *SHA1(const unsigned char *d, unsigned long n, + unsigned char *md); + + void SHA1_Init(SHA_CTX *c); + void SHA1_Update(SHA_CTX *c, const void *data, + unsigned long len); + void SHA1_Final(unsigned char *md, SHA_CTX *c); + +=head1 DESCRIPTION + +SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a +160 bit output. + +SHA1() computes the SHA-1 message digest of the B<n> +bytes at B<d> and places it in B<md> (which must have space for +SHA_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest +is placed in a static array. + +The following functions may be used if the message is not completely +stored in memory: + +SHA1_Init() initializes a B<SHA_CTX> structure. + +SHA1_Update() can be called repeatedly with chunks of the message to +be hashed (B<len> bytes at B<data>). + +SHA1_Final() places the message digest in B<md>, which must have space +for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B<SHA_CTX>. + +Applications should use the higher level functions +L<EVP_DigestInit(3)|EVP_DigestInit(3)> +etc. instead of calling the hash functions directly. + +The predecessor of SHA-1, SHA, is also implemented, but it should be +used only when backward compatibility is required. + +=head1 RETURN VALUES + +SHA1() returns a pointer to the hash value. + +SHA1_Init(), SHA1_Update() and SHA1_Final() do not return values. + +=head1 CONFORMING TO + +SHA: US Federal Information Processing Standard FIPS PUB 180 (Secure Hash +Standard), +SHA-1: US Federal Information Processing Standard FIPS PUB 180-1 (Secure Hash +Standard), +ANSI X9.30 + +=head1 SEE ALSO + +L<ripemd(3)|ripemd(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> + +=head1 HISTORY + +SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all +versions of SSLeay and OpenSSL. + +=cut diff --git a/crypto/openssl/doc/crypto/threads.pod b/crypto/openssl/doc/crypto/threads.pod new file mode 100644 index 0000000..bc7ff9b --- /dev/null +++ b/crypto/openssl/doc/crypto/threads.pod @@ -0,0 +1,156 @@ +=pod + +=head1 NAME + +CRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks, +CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, +CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, +CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support + +=head1 SYNOPSIS + + #include <openssl/crypto.h> + + void CRYPTO_set_locking_callback(void (*locking_function)(int mode, + int n, const char *file, int line)); + + void CRYPTO_set_id_callback(unsigned long (*id_function)(void)); + + int CRYPTO_num_locks(void); + + + /* struct CRYPTO_dynlock_value needs to be defined by the user */ + struct CRYPTO_dynlock_value; + + void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value * + (*dyn_create_function)(char *file, int line)); + void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function) + (int mode, struct CRYPTO_dynlock_value *l, + const char *file, int line)); + void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function) + (struct CRYPTO_dynlock_value *l, const char *file, int line)); + + int CRYPTO_get_new_dynlockid(void); + + void CRYPTO_destroy_dynlockid(int i); + + void CRYPTO_lock(int mode, int n, const char *file, int line); + + #define CRYPTO_w_lock(type) \ + CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) + #define CRYPTO_w_unlock(type) \ + CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) + #define CRYPTO_r_lock(type) \ + CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__) + #define CRYPTO_r_unlock(type) \ + CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__) + #define CRYPTO_add(addr,amount,type) \ + CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__) + +=head1 DESCRIPTION + +OpenSSL can safely be used in multi-threaded applications provided +that at least two callback functions are set. + +locking_function(int mode, int n, const char *file, int line) is +needed to perform locking on shared data structures. Multi-threaded +applications will crash at random if it is not set. + +locking_function() must be able to handle up to CRYPTO_num_locks() +different mutex locks. It sets the B<n>-th lock if B<mode> & +B<CRYPTO_LOCK>, and releases it otherwise. + +B<file> and B<line> are the file number of the function setting the +lock. They can be useful for debugging. + +id_function(void) is a function that returns a thread ID. It is not +needed on Windows nor on platforms where getpid() returns a different +ID for each thread (most notably Linux). + +Additionally, OpenSSL supports dynamic locks, and sometimes, some parts +of OpenSSL need it for better performance. To enable this, the following +is required: + +=over 4 + +=item * +Three additional callback function, dyn_create_function, dyn_lock_function +and dyn_destroy_function. + +=item * +A structure defined with the data that each lock needs to handle. + +=back + +struct CRYPTO_dynlock_value has to be defined to contain whatever structure +is needed to handle locks. + +dyn_create_function(const char *file, int line) is needed to create a +lock. Multi-threaded applications might crash at random if it is not set. + +dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line) +is needed to perform locking off dynamic lock numbered n. Multi-threaded +applications might crash at random if it is not set. + +dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is +needed to destroy the lock l. Multi-threaded applications might crash at +random if it is not set. + +CRYPTO_get_new_dynlockid() is used to create locks. It will call +dyn_create_function for the actual creation. + +CRYPTO_destroy_dynlockid() is used to destroy locks. It will call +dyn_destroy_function for the actual destruction. + +CRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield +describing what should be done with the lock. n is the number of the +lock as returned from CRYPTO_get_new_dynlockid(). mode can be combined +from the following values. These values are pairwise exclusive, with +undefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE +should not be used together): + + CRYPTO_LOCK 0x01 + CRYPTO_UNLOCK 0x02 + CRYPTO_READ 0x04 + CRYPTO_WRITE 0x08 + +=head1 RETURN VALUES + +CRYPTO_num_locks() returns the required number of locks. + +CRYPTO_get_new_dynlockid() returns the index to the newly created lock. + +The other functions return no values. + +=head1 NOTE + +You can find out if OpenSSL was configured with thread support: + + #define OPENSSL_THREAD_DEFINES + #include <openssl/opensslconf.h> + #if defined(THREADS) + // thread support enabled + #else + // no thread support + #endif + +Also, dynamic locks are currently not used internally by OpenSSL, but +may do so in the future. + +=head1 EXAMPLES + +B<crypto/threads/mttest.c> shows examples of the callback functions on +Solaris, Irix and Win32. + +=head1 HISTORY + +CRYPTO_set_locking_callback() and CRYPTO_set_id_callback() are +available in all versions of SSLeay and OpenSSL. +CRYPTO_num_locks() was added in OpenSSL 0.9.4. +All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev. + +=head1 SEE ALSO + +L<crypto(3)|crypto(3)> + +=cut |
