diff options
Diffstat (limited to 'lib/libcrypto')
| -rw-r--r-- | lib/libcrypto/man/BF_set_key.3 | 215 | ||||
| -rw-r--r-- | lib/libcrypto/man/BIO.3 | 56 | ||||
| -rw-r--r-- | lib/libcrypto/man/BIO_ctrl.3 | 264 | ||||
| -rw-r--r-- | lib/libcrypto/man/BIO_f_base64.3 | 80 | ||||
| -rw-r--r-- | lib/libcrypto/man/BIO_f_buffer.3 | 110 | ||||
| -rw-r--r-- | lib/libcrypto/man/BIO_f_cipher.3 | 114 | ||||
| -rw-r--r-- | lib/libcrypto/man/BIO_f_md.3 | 209 | ||||
| -rw-r--r-- | lib/libcrypto/man/BIO_f_null.3 | 25 | ||||
| -rw-r--r-- | lib/libcrypto/man/BIO_find_type.3 | 117 | ||||
| -rw-r--r-- | lib/libcrypto/man/BIO_new.3 | 104 | ||||
| -rw-r--r-- | lib/libcrypto/man/BIO_new_CMS.3 | 83 | ||||
| -rw-r--r-- | lib/libcrypto/man/Makefile | 8 |
12 files changed, 1381 insertions, 4 deletions
diff --git a/lib/libcrypto/man/BF_set_key.3 b/lib/libcrypto/man/BF_set_key.3 new file mode 100644 index 00000000000..53ff53896c4 --- /dev/null +++ b/lib/libcrypto/man/BF_set_key.3 @@ -0,0 +1,215 @@ +.Dd July 17, 2014 +.Dt BF_SET_KEY 3 +.Os +.Sh NAME +.Nm BF_set_key , +.Nm BF_encrypt , +.Nm BF_decrypt , +.Nm BF_ecb_encrypt , +.Nm BF_cbc_encrypt , +.Nm BF_cfb64_encrypt , +.Nm BF_ofb64_encrypt , +.Nm BF_options +.Nd Blowfish encryption +.Sh SYNOPSIS +.In openssl/blowfish.h +.Ft void +.Fo BF_set_key +.Fa "BF_KEY *key" +.Fa "int len" +.Fa "const unsigned char *data" +.Fc +.Ft void +.Fo BF_ecb_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "BF_KEY *key" +.Fa "int enc" +.Fc +.Ft void +.Fo BF_cbc_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "BF_KEY *schedule" +.Fa "unsigned char *ivec" +.Fa "int enc" +.Fc +.Ft void +.Fo BF_cfb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "BF_KEY *schedule" +.Fa "unsigned char *ivec" +.Fa "int *num" +.Fa "int enc" +.Fc +.Ft void +.Fo BF_ofb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "BF_KEY *schedule" +.Fa "unsigned char *ivec" +.Fa "int *num" +.Fc +.Ft const char * +.Fo BF_options +.Fa void +.Fc +.Ft void +.Fo BF_encrypt +.Fa "BF_LONG *data" +.Fa "const BF_KEY *key" +.Fc +.Ft void +.Fo BF_decrypt +.Fa "BF_LONG *data" +.Fa "const BF_KEY *key" +.Fc +.Sh DESCRIPTION +This library implements the Blowfish cipher, +which was invented and described by +.An Counterpane . +.Pp +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 considered good for strong encryption. +Blowfish can be used in the same modes as DES (see +.Xr des_modes 3 ) . +Blowfish is currently one of the faster block ciphers. +It is quite a bit faster than DES, and much faster than IDEA or RC2. +.Pp +Blowfish consists of a key setup phase +and the actual encryption or decryption phase. +.Pp +.Fn BF_set_key +sets up the +.Vt BF_KEY +.Fa key +using the +.Fa len +bytes long key at +.Fa data . +.Pp +.Fn BF_ecb_encrypt +is the basic Blowfish encryption and decryption function. +It encrypts or decrypts the first 64 bits of +.Fa in +using the key +.Fa key , +putting the result in +.Fa out . +.Fa enc +decides if encryption +.Pq Dv BF_ENCRYPT +or decryption +.Pq Dv BF_DECRYPT +shall be performed. +The vector pointed at by +.Fa in +and +.Fa out +must be 64 bits in length, no less. +If they are larger, everything after the first 64 bits is ignored. +.Pp +The mode functions +.Fn BF_cbc_encrypt , +.Fn BF_cfb64_encrypt , +and +.Fn BF_ofb64_encrypt +all operate on variable length data. +They all take an initialization vector +.Fa ivec +which needs to be passed along into the next call of the same function +for the same message. +.Fa 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 +.Fa ivec +is simply initialized to zero. +.Fn BF_cbc_encrypt +operates on data that is a multiple of 8 bytes long, while +.Fn BF_cfb64_encrypt +and +.Fn 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 +.Fa num , +which is a pointer to an integer where the current offset in +.Fa ivec +is stored between calls. +This integer must be initialized to zero when +.Fa ivec +is initialized. +.Pp +.Fn BF_cbc_encrypt +is the Cipher Block Chaining function for Blowfish. +It encrypts or decrypts the 64 bits chunks of +.Fa in +using the key +.Fa schedule , +putting the result in +.Fa out . +.Fa enc +decides if encryption +.Pq Dv BF_ENCRYPT +or decryption +.Pq Dv BF_DECRYPT +shall be performed. +.Fa ivec +must point at an 8 byte long initialization vector. +.Pp +.Fn BF_cfb64_encrypt +is the CFB mode for Blowfish with 64 bit feedback. +It encrypts or decrypts the bytes in +.Fa in +using the key +.Fa schedule , +putting the result in +.Fa out . +.Fa enc +decides if encryption +.Pq Dv BF_ENCRYPT +or decryption +.Pq Dv BF_DECRYPT +shall be performed. +.Fa ivec +must point at an +8 byte long initialization vector. +.Fa num +must point at an integer which must be initially zero. +.Pp +.Fn BF_ofb64_encrypt +is the OFB mode for Blowfish with 64 bit feedback. +It uses the same parameters as +.Fn BF_cfb64_encrypt , +which must be initialized the same way. +.Pp +.Fn BF_encrypt +and +.Fn BF_decrypt +are the lowest level functions for Blowfish encryption. +They encrypt/decrypt the first 64 bits of the vector pointed by +.Fa data , +using the key +.Fa key . +These functions should not be used unless you implement 'modes' of Blowfish. +The alternative is to use +.Fn 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. +.Sh RETURN VALUES +None of the functions presented here return any value. +.Sh NOTE +Applications should use the higher level functions +.Xr EVP_EncryptInit 3 +etc. instead of calling the blowfish functions directly. +.Sh HISTORY +The Blowfish functions are available in all versions of SSLeay and OpenSSL. diff --git a/lib/libcrypto/man/BIO.3 b/lib/libcrypto/man/BIO.3 new file mode 100644 index 00000000000..f3523790031 --- /dev/null +++ b/lib/libcrypto/man/BIO.3 @@ -0,0 +1,56 @@ +.Dd July 17, 2014 +.Dt BIO 3 +.Os +.Sh NAME +.Nm BIO +.Nd I/O abstraction +.Sh SYNOPSIS +.In openssl/bio.h +.Sh DESCRIPTION +A BIO is an I/O abstraction, +it hides many of the underlying I/O details from an application. +If an application uses a BIO for its I/O, it can transparently handle +SSL connections, unencrypted network connections and file I/O. +.Pp +There are two types of BIO, a source/sink BIO and a filter BIO. +.Pp +As its name implies, a source/sink BIO is a source and/or sink of data, +examples include a socket BIO and a file BIO. +.Pp +A filter BIO takes data from one BIO and passes it through +to another, or to the application. +The data may be left unmodified (for example a message digest BIO) +or translated (for example an encryption BIO). +The effect of a filter BIO may change according to the I/O operation +it is performing: for example an encryption BIO will encrypt data +if it is being written to and decrypt data if it is being read from. +.Pp +BIOs can be joined together to form a chain +(a single BIO is a chain with one component). +A chain normally 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). +.Sh SEE ALSO +.Xr BIO_ctrl 3 , +.Xr BIO_f_base64 3 , +.Xr BIO_f_buffer 3 , +.Xr BIO_f_cipher 3 , +.Xr BIO_f_md 3 , +.Xr BIO_f_null 3 , +.Xr BIO_f_ssl 3 , +.Xr BIO_find_type 3 , +.Xr BIO_new 3 , +.Xr BIO_new_bio_pair 3 , +.Xr BIO_push 3 , +.Xr BIO_read 3 , +.Xr BIO_s_accept 3 , +.Xr BIO_s_bio 3 , +.Xr BIO_s_connect 3 , +.Xr BIO_s_fd 3 , +.Xr BIO_s_file 3 , +.Xr BIO_s_mem 3 , +.Xr BIO_s_null 3 , +.Xr BIO_s_socket 3 , +.Xr BIO_set_callback 3 , +.Xr BIO_should_retry 3 diff --git a/lib/libcrypto/man/BIO_ctrl.3 b/lib/libcrypto/man/BIO_ctrl.3 new file mode 100644 index 00000000000..75d665a4be2 --- /dev/null +++ b/lib/libcrypto/man/BIO_ctrl.3 @@ -0,0 +1,264 @@ +.Dd July 17, 2014 +.Dt BIO_CTRL 3 +.Os +.Sh NAME +.Nm BIO_ctrl , +.Nm BIO_callback_ctrl , +.Nm BIO_ptr_ctrl , +.Nm BIO_int_ctrl , +.Nm BIO_reset , +.Nm BIO_seek , +.Nm BIO_tell , +.Nm BIO_flush , +.Nm BIO_eof , +.Nm BIO_set_close , +.Nm BIO_get_close , +.Nm BIO_pending , +.Nm BIO_wpending , +.Nm BIO_ctrl_pending , +.Nm BIO_ctrl_wpending , +.Nm BIO_get_info_callback , +.Nm BIO_set_info_callback +.Nd BIO control operations +.Sh SYNOPSIS +.In openssl/bio.h +.Ft long +.Fo BIO_ctrl +.Fa "BIO *bp" +.Fa "int cmd" +.Fa "long larg" +.Fa "void *parg" +.Fc +.Ft long +.Fo BIO_callback_ctrl +.Fa "BIO *b" +.Fa "int cmd" +.Fa "void (*fp)(struct bio_st *, int, const char *, int, long, long)" +.Fc +.Ft char * +.Fo BIO_ptr_ctrl +.Fa "BIO *bp" +.Fa "int cmd" +.Fa "long larg" +.Fc +.Ft long +.Fo BIO_int_ctrl +.Fa "BIO *bp" +.Fa "int cmd" +.Fa "long larg" +.Fa "int iarg" +.Fc +.Ft int +.Fo BIO_reset +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_seek +.Fa "BIO *b" +.Fa "int ofs" +.Fc +.Ft int +.Fo BIO_tell +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_flush +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_eof +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_set_close +.Fa "BIO *b" +.Fa "long flag" +.Fc +.Ft int +.Fo BIO_get_close +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_pending +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_wpending +.Fa "BIO *b" +.Fc +.Ft size_t +.Fo BIO_ctrl_pending +.Fa "BIO *b" +.Fc +.Ft size_t +.Fo BIO_ctrl_wpending +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_get_info_callback +.Fa "BIO *b" +.Fa "bio_info_cb **cbp" +.Fc +.Ft int +.Fo BIO_set_info_callback +.Fa "BIO *b" +.Fa "bio_info_cb *cb" +.Fc +.Ft typedef void +.Fo bio_info_cb +.Fa "BIO *b" +.Fa "int oper" +.Fa "const char *ptr" +.Fa "int arg1" +.Fa "long arg2" +.Fa "long arg3" +.Fc +.Sh DESCRIPTION +.Fn BIO_ctrl , +.Fn BIO_callback_ctrl , +.Fn BIO_ptr_ctrl , +and +.Fn 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 BIO's manual +page as well as any special features of the standard calls. +.Pp +.Fn 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. +.Pp +.Fn BIO_seek +resets a file related BIO's (that is file descriptor and +FILE BIOs) file position pointer to +.Fa ofs +bytes from start of file. +.Pp +.Fn BIO_tell +returns the current file position of a file related BIO. +.Pp +.Fn 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. +.Pp +.Fn BIO_eof +returns 1 if the BIO has read EOF, the precise meaning of +"EOF" varies according to the BIO type. +.Pp +.Fn BIO_set_close +sets the BIO +.Fa b +close flag to +.Fa flag . +.Fa flag +can take the value +.Dv BIO_CLOSE +or +.Dv BIO_NOCLOSE . +Typically +.Dv 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. +.Pp +.Fn BIO_get_close +returns the BIO's close flag. +.Pp +.Fn BIO_pending , +.Fn BIO_ctrl_pending , +.Fn BIO_wpending , +and +.Fn BIO_ctrl_wpending +return the number of pending characters in the BIO's read and write buffers. +Not all BIOs support these calls. +.Fn BIO_ctrl_pending +and +.Fn BIO_ctrl_wpending +return a +.Vt size_t +type and are functions, +.Fn BIO_pending +and +.Fn BIO_wpending +are macros which call +.Fn BIO_ctrl . +.Sh RETURN VALUES +.Fn 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. +.Pp +.Fn BIO_seek +and +.Fn BIO_tell +both return the current file position on success +and -1 for failure, except file BIOs which for +.Fn BIO_seek +always return 0 for success and -1 for failure. +.Pp +.Fn BIO_flush +returns 1 for success and 0 or -1 for failure. +.Pp +.Fn BIO_eof +returns 1 if EOF has been reached 0 otherwise. +.Pp +.Fn BIO_set_close +always returns 1. +.Pp +.Fn BIO_get_close +returns the close flag value +.Dv BIO_CLOSE +or +.Dv BIO_NOCLOSE . +.Pp +.Fn BIO_pending , +.Fn BIO_ctrl_pending , +.Fn BIO_wpending , +and +.Fn BIO_ctrl_wpending +return the amount of pending data. +.Sh NOTES +Because it can write data, +.Fn BIO_flush +may return 0 or -1 indicating that the call should be retried later +in a similar manner to +.Fn BIO_write . +The +.Fn BIO_should_retry +call should be used and appropriate action taken is the call fails. +.Pp +The return values of +.Fn BIO_pending +and +.Fn 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 +.Vt FILE +structure's internal buffers but it is not possible +to determine this in a portably way. +For other types of BIO they may not be supported. +.Pp +If they do not internally handle a particular +.Fn BIO_ctrl +operation, filter BIOs 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 +.Fn BIO_seek , +but this may still succeed if the chain ends +in a FILE or file descriptor BIO. +.Pp +Source/sink BIOs return an 0 if they do not recognize the +.Fn BIO_ctrl +operation. +.Sh 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 +.Fn BIO_seek +on a file BIO for a successful operation. diff --git a/lib/libcrypto/man/BIO_f_base64.3 b/lib/libcrypto/man/BIO_f_base64.3 new file mode 100644 index 00000000000..e08191b84a8 --- /dev/null +++ b/lib/libcrypto/man/BIO_f_base64.3 @@ -0,0 +1,80 @@ +.Dd July 17, 2014 +.Dt BIO_F_BASE64 3 +.Os +.Sh NAME +.Nm BIO_f_base64 +.Nd base64 BIO filter +.Sh SYNOPSIS +.In openssl/bio.h +.In openssl/evp.h +.Ft BIO_METHOD * +.Fo BIO_f_base64 +.Fa void +.Fc +.Sh DESCRIPTION +.Fn 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. +.Pp +Base64 BIOs do not support +.Xr BIO_gets 3 +or +.Xr BIO_puts 3 . +.Pp +.Xr BIO_flush 3 +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. +.Pp +The flag +.Dv BIO_FLAGS_BASE64_NO_NL +can be set with +.Xr BIO_set_flags 3 +to encode the data all on one line +or expect the data to be all on one line. +.Sh NOTES +Because of the format of base64 encoding the end of the encoded +block cannot always be reliably determined. +.Sh RETURN VALUES +.Fn BIO_f_base64 +returns the base64 BIO method. +.Sh EXAMPLES +Base64 encode the string "Hello World\en" +and write the result to standard output: +.Bd -literal -offset indent +BIO *bio, *b64; +char message[] = "Hello World \en"; + +b64 = BIO_new(BIO_f_base64()); +bio = BIO_new_fp(stdout, BIO_NOCLOSE); +BIO_push(b64, bio); +BIO_write(b64, message, strlen(message)); +BIO_flush(b64); + +BIO_free_all(b64); +.Ed +.Pp +Read Base64 encoded data from standard input +and write the decoded data to standard output: +.Bd -literal -offset indent +BIO *bio, *b64, *bio_out; +char inbuf[512]; +int inlen; + +b64 = BIO_new(BIO_f_base64()); +bio = BIO_new_fp(stdin, BIO_NOCLOSE); +bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); +BIO_push(b64, bio); +while((inlen = BIO_read(b64, inbuf, 512)) > 0) + BIO_write(bio_out, inbuf, inlen); + +BIO_flush(bio_out); +BIO_free_all(b64); +.Ed +.Sh BUGS +The ambiguity of EOF in base64 encoded data can cause additional +data following the base64 encoded block to be misinterpreted. +.Pp +There should be some way of specifying a test that the BIO can perform +to reliably determine EOF (for example a MIME boundary). diff --git a/lib/libcrypto/man/BIO_f_buffer.3 b/lib/libcrypto/man/BIO_f_buffer.3 new file mode 100644 index 00000000000..c01ab4809b1 --- /dev/null +++ b/lib/libcrypto/man/BIO_f_buffer.3 @@ -0,0 +1,110 @@ +.Dd July 17, 2014 +.Dt BIO_F_BUFFER 3 +.Os +.Sh NAME +.Nm BIO_f_buffer +.Nd buffering BIO +.Sh SYNOPSIS +.In openssl/bio.h +.Ft BIO_METHOD * +.Fo BIO_f_buffer +.Fa void +.Fc +.Bd -literal +#define BIO_get_buffer_num_lines(b) \e + BIO_ctrl(b,BIO_C_GET_BUFF_NUM_LINES,0,NULL) +#define BIO_set_read_buffer_size(b,size) \e + BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,0) +#define BIO_set_write_buffer_size(b,size) \e + BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,1) +#define BIO_set_buffer_size(b,size) \e + BIO_ctrl(b,BIO_C_SET_BUFF_SIZE,size,NULL) +#define BIO_set_buffer_read_data(b,buf,num) \e + BIO_ctrl(b,BIO_C_SET_BUFF_READ_DATA,num,buf) +.Ed +.Sh DESCRIPTION +.Fn BIO_f_buffer +returns the buffering BIO method. +.Pp +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 +.Xr BIO_gets 3 +and +.Xr BIO_puts 3 +are supported. +.Pp +Calling +.Xr BIO_reset 3 +on a buffering BIO clears any buffered data. +.Pp +.Fn BIO_get_buffer_num_lines +returns the number of lines currently buffered. +.Pp +.Fn BIO_set_read_buffer_size , +.Fn BIO_set_write_buffer_size , +and +.Fn BIO_set_buffer_size +set the read, write or both read and write buffer sizes to +.Fa size . +The initial buffer size is +.Dv DEFAULT_BUFFER_SIZE , +currently 4096. +Any attempt to reduce the buffer size below +.Dv DEFAULT_BUFFER_SIZE +is ignored. +Any buffered data is cleared when the buffer is resized. +.Pp +.Fn BIO_set_buffer_read_data +clears the read buffer and fills it with +.Fa num +bytes of +.Fa buf . +If +.Fa num +is larger than the current buffer size the buffer is expanded. +.Sh NOTES +Buffering BIOs implement +.Xr BIO_gets 3 +by using +.Xr BIO_read 3 +operations on the next BIO in the chain. +By prepending a buffering BIO to a chain +it is therefore possible to provide +.Xr BIO_gets 3 +functionality if the following BIOs do not support it (for example SSL BIOs). +.Pp +Data is only written to the next BIO in the chain +when the write buffer fills or when +.Xr BIO_flush 3 +is called. +It is therefore important to call +.Xr BIO_flush 3 +whenever any pending data should be written +such as when removing a buffering BIO using +.Xr BIO_pop 3 . +.Xr BIO_flush 3 +may need to be retried if the ultimate source/sink BIO is non blocking. +.Sh RETURN VALUES +.Fn BIO_f_buffer +returns the buffering BIO method. +.Pp +.Fn BIO_get_buffer_num_lines +returns the number of lines buffered (may be 0). +.Pp +.Fn BIO_set_read_buffer_size , +.Fn BIO_set_write_buffer_size , +and +.Fn BIO_set_buffer_size +return 1 if the buffer was successfully resized or 0 for failure. +.Pp +.Fn BIO_set_buffer_read_data +returns 1 if the data was set correctly or 0 if there was an error. +.Sh SEE ALSO +.Xr BIO 3 , +.Xr BIO_ctrl 3 , +.Xr BIO_flush 3 , +.Xr BIO_pop 3 , +.Xr BIO_reset 3 diff --git a/lib/libcrypto/man/BIO_f_cipher.3 b/lib/libcrypto/man/BIO_f_cipher.3 new file mode 100644 index 00000000000..68f425eb75c --- /dev/null +++ b/lib/libcrypto/man/BIO_f_cipher.3 @@ -0,0 +1,114 @@ +.Dd July 17, 2014 +.Dt BIO_F_CIPHER 3 +.Os +.Sh NAME +.Nm BIO_f_cipher , +.Nm BIO_set_cipher , +.Nm BIO_get_cipher_status , +.Nm BIO_get_cipher_ctx +.Nd cipher BIO filter +.Sh SYNOPSIS +.In openssl/bio.h +.In openssl/evp.h +.Ft BIO_METHOD * +.Fo BIO_f_cipher +.Fa void +.Fc +.Ft void +.Fo BIO_set_cipher +.Fa "BIO *b" +.Fa "const EVP_CIPHER *cipher" +.Fa "unsigned char *key" +.Fa "unsigned char *iv" +.Fa "int enc" +.Fc +.Ft int +.Fo BIO_get_cipher_status +.Fa "BIO *b" +.Fc +.Ft int +.Fo BIO_get_cipher_ctx +.Fa "BIO *b" +.Fa "EVP_CIPHER_CTX **pctx" +.Fc +.Sh DESCRIPTION +.Fn 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 +.Xr EVP_CipherInit 3 , +.Xr EVP_CipherUpdate 3 , +and +.Xr EVP_CipherFinal 3 . +.Pp +Cipher BIOs do not support +.Xr BIO_gets 3 +or +.Xr BIO_puts 3 . +.Pp +.Xr BIO_flush 3 +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. +.Pp +.Fn BIO_set_cipher +sets the cipher of BIO +.Fa b +to +.Fa cipher +using key +.Fa key +and IV +.Fa iv . +.Fa enc +should be set to 1 for encryption and zero for decryption. +.Pp +When reading from an encryption BIO, the final block is automatically +decrypted and checked when EOF is detected. +.Fn BIO_get_cipher_status +is a +.Xr BIO_ctrl 3 +macro which can be called to determine +whether the decryption operation was successful. +.Pp +.Fn BIO_get_cipher_ctx +is a +.Xr BIO_ctrl 3 +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 +.Fn BIO_set_cipher +is not flexible enough for the applications needs. +.Sh NOTES +When encrypting, +.Xr BIO_flush 3 +must be called to flush the final block through the BIO. +If it is not, then the final block will fail a subsequent decrypt. +.Pp +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. +.Fn BIO_get_cipher_status +should be called to determine if the decrypt was successful. +.Pp +As always, if +.Xr BIO_gets 3 +or +.Xr BIO_puts 3 +support is needed, then it can be achieved +by preceding the cipher BIO with a buffering BIO. +.Sh RETURN VALUES +.Fn BIO_f_cipher +returns the cipher BIO method. +.Pp +.Fn BIO_set_cipher +does not return a value. +.Pp +.Fn BIO_get_cipher_status +returns 1 for a successful decrypt and 0 for failure. +.Pp +.Fn BIO_get_cipher_ctx +currently always returns 1. diff --git a/lib/libcrypto/man/BIO_f_md.3 b/lib/libcrypto/man/BIO_f_md.3 new file mode 100644 index 00000000000..de21722608c --- /dev/null +++ b/lib/libcrypto/man/BIO_f_md.3 @@ -0,0 +1,209 @@ +.Dd July 17, 2014 +.Dt BIO_F_MD 3 +.Os +.Sh NAME +.Nm BIO_f_md , +.Nm BIO_set_md , +.Nm BIO_get_md , +.Nm BIO_get_md_ctx +.Nd message digest BIO filter +.Sh SYNOPSIS +.In openssl/bio.h +.In openssl/evp.h +.Ft BIO_METHOD * +.Fo BIO_f_md +.Fa void +.Fc +.Ft int +.Fo BIO_set_md +.Fa "BIO *b" +.Fa "EVP_MD *md" +.Fc +.Ft int +.Fo BIO_get_md +.Fa "BIO *b" +.Fa "EVP_MD **mdp" +.Fc +.Ft int +.Fo BIO_get_md_ctx +.Fa "BIO *b" +.Fa "EVP_MD_CTX **mdcp" +.Fc +.Sh DESCRIPTION +.Fn 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 +.Fn EVP_DigestInit , +.Fn EVP_DigestUpdate , +and +.Fn EVP_DigestFinal . +.Pp +Any data written or read through a digest BIO using +.Xr BIO_read 3 +and +.Xr BIO_write 3 +is digested. +.Pp +.Xr BIO_gets 3 , +if its +.Sy size +parameter is large enough, +finishes the digest calculation and returns the digest value. +.Xr BIO_puts 3 +is +not supported. +.Pp +.Xr BIO_reset 3 +reinitialises a digest BIO. +.Pp +.Fn BIO_set_md +sets the message digest of BIO +.Fa b +to +.Fa md : +this must be called to initialize a digest BIO +before any data is passed through it. +It is a +.Xr BIO_ctrl 3 +macro. +.Pp +.Fn BIO_get_md +places the a pointer to the digest BIOs digest method in +.Fa mdp . +It is a +.Xr BIO_ctrl 3 +macro. +.Pp +.Fn BIO_get_md_ctx +returns the digest BIOs context in +.Fa mdcp . +.Sh NOTES +The context returned by +.Fn BIO_get_md_ctx +can be used in calls to +.Xr EVP_DigestFinal 3 +and also in the signature routines +.Xr EVP_SignFinal 3 +and +.Xr EVP_VerifyFinal 3 . +.Pp +The context returned by +.Fn 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. +.Pp +After the digest has been retrieved from a digest BIO, +it must be reinitialized by calling +.Xr BIO_reset 3 +or +.Fn BIO_set_md +before any more data is passed through it. +.Pp +If an application needs to call +.Xr BIO_gets 3 +or +.Xr BIO_puts 3 +through a chain containing digest BIOs, +then this can be done by prepending a buffering BIO. +.Pp +Before OpenSSL 1.0.0 the call to +.Fn BIO_get_md_ctx +would only work if the BIO had been initialized for example by calling +.Fn BIO_set_md . +In OpenSSL 1.0.0 and later the context is always returned +and the BIO is state is set to initialized. +This allows applications to initialize the context externally +if the standard calls such as +.Fn BIO_set_md +are not sufficiently flexible. +.Sh RETURN VALUES +.Fn BIO_f_md +returns the digest BIO method. +.Pp +.Fn BIO_set_md , +.Fn BIO_get_md , +and +.Fn BIO_get_md_ctx +return 1 for success and 0 for failure. +.Sh 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. +.Bd -literal -offset 2n +BIO *bio, *mdtmp; +const 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)); +.Ed +.Pp +The next example digests data by reading through a chain instead: +.Bd -literal -offset 2n +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); +.Ed +.Pp +This next example retrieves the message digests from a BIO chain +and outputs them. +This could be used with the examples above. +.Bd -literal -offset 2n +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("\en"); + mdtmp = BIO_next(mdtmp); +} while(mdtmp); +BIO_free_all(bio); +.Ed +.Sh BUGS +The lack of support for +.Xr BIO_puts 3 +and the non standard behaviour of +.Xr BIO_gets 3 +could be regarded as anomalous. +It could be argued that +.Xr BIO_gets 3 +and +.Xr BIO_puts 3 +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 +.Xr BIO_ctrl 3 +call. diff --git a/lib/libcrypto/man/BIO_f_null.3 b/lib/libcrypto/man/BIO_f_null.3 new file mode 100644 index 00000000000..a09cc776315 --- /dev/null +++ b/lib/libcrypto/man/BIO_f_null.3 @@ -0,0 +1,25 @@ +.Dd July 17, 2014 +.Dt BIO_F_NULL 3 +.Os +.Sh NAME +.Nm BIO_f_null +.Nd null filter +.Sh SYNOPSIS +.In openssl/bio.h +.Ft BIO_METHOD * +.Fo BIO_f_null +.Fa void +.Fc +.Sh DESCRIPTION +.Fn BIO_f_null +returns the null filter BIO method. +This is a filter BIO that does nothing. +.Pp +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. +.Sh NOTES +As may be apparent, a null filter BIO is not particularly useful. +.Sh RETURN VALUES +.Fn BIO_f_null +returns the null filter BIO method. diff --git a/lib/libcrypto/man/BIO_find_type.3 b/lib/libcrypto/man/BIO_find_type.3 new file mode 100644 index 00000000000..f573ad7675d --- /dev/null +++ b/lib/libcrypto/man/BIO_find_type.3 @@ -0,0 +1,117 @@ +.Dd July 17, 2014 +.Dt BIO_FIND_TYPE 3 +.Os +.Sh NAME +.Nm BIO_find_type , +.Nm BIO_next , +.Nm BIO_method_type +.Nd BIO chain traversal +.Sh SYNOPSIS +.In openssl/bio.h +.Ft BIO * +.Fo BIO_find_type +.Fa "BIO *b" +.Fa "int bio_type" +.Fc +.Ft BIO * +.Fo BIO_next +.Fa "BIO *b" +.Fc +.Fd #define BIO_method_type(b) ((b)->method->type) +.Fd #define BIO_TYPE_NONE 0 +.Fd #define BIO_TYPE_MEM (1|0x0400) +.Fd #define BIO_TYPE_FILE (2|0x0400) +.Fd #define BIO_TYPE_FD (4|0x0400|0x0100) +.Fd #define BIO_TYPE_SOCKET (5|0x0400|0x0100) +.Fd #define BIO_TYPE_NULL (6|0x0400) +.Fd #define BIO_TYPE_SSL (7|0x0200) +.Fd #define BIO_TYPE_MD (8|0x0200) +.Fd #define BIO_TYPE_BUFFER (9|0x0200) +.Fd #define BIO_TYPE_CIPHER (10|0x0200) +.Fd #define BIO_TYPE_BASE64 (11|0x0200) +.Fd #define BIO_TYPE_CONNECT (12|0x0400|0x0100) +.Fd #define BIO_TYPE_ACCEPT (13|0x0400|0x0100) +.Fd #define BIO_TYPE_PROXY_CLIENT (14|0x0200) +.Fd #define BIO_TYPE_PROXY_SERVER (15|0x0200) +.Fd #define BIO_TYPE_NBIO_TEST (16|0x0200) +.Fd #define BIO_TYPE_NULL_FILTER (17|0x0200) +.Fd #define BIO_TYPE_BER (18|0x0200) +.Fd #define BIO_TYPE_BIO (19|0x0400) +.Fd #define BIO_TYPE_DESCRIPTOR 0x0100 +.Fd #define BIO_TYPE_FILTER 0x0200 +.Fd #define BIO_TYPE_SOURCE_SINK 0x0400 +.Sh DESCRIPTION +The function +.Fn BIO_find_type +searches for a BIO of a given type in a chain, starting at BIO +.Fa b . +If +.Fa bio_type +is a specific type (such as +.Dv BIO_TYPE_MEM ) , +then a search is made for a BIO of that type. +If +.Fa bio_type +is a general type (such as +.Dv BIO_TYPE_SOURCE_SINK ) , +then the next matching BIO of the given general type is searched for. +.Fn BIO_find_type +returns the next matching BIO or +.Dv NULL +if none is found. +.Pp +Note: not all the +.Dv BIO_TYPE_* +types above have corresponding BIO implementations. +.Pp +.Fn 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 +.Fn BIO_find_type +to find all BIOs of a certain type. +.Pp +.Fn BIO_method_type +returns the type of a BIO. +.Sh RETURN VALUES +.Fn BIO_find_type +returns a matching BIO or +.Dv NULL +for no match. +.Pp +.Fn BIO_next +returns the next BIO in a chain. +.Pp +.Fn BIO_method_type +returns the type of the BIO +.Fa b . +.Sh NOTES +.Fn BIO_next +was added to OpenSSL 0.9.6 to provide a 'clean' way to traverse a BIO +chain or find multiple matches using +.Fn BIO_find_type . +Previous versions had to use: +.Pp +.Dl next = bio->next_bio; +.Sh BUGS +.Fn BIO_find_type +in OpenSSL 0.9.5a and earlier could not be safely passed a +.Dv NULL +pointer for the +.Fa b +argument. +.Sh EXAMPLE +Traverse a chain looking for digest BIOs: +.Bd -literal -offset 2n +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); +.Ed diff --git a/lib/libcrypto/man/BIO_new.3 b/lib/libcrypto/man/BIO_new.3 new file mode 100644 index 00000000000..5f5030cdfa2 --- /dev/null +++ b/lib/libcrypto/man/BIO_new.3 @@ -0,0 +1,104 @@ +.Dd July 17, 2014 +.Dt BIO_NEW 3 +.Os +.Sh NAME +.Nm BIO_new , +.Nm BIO_set , +.Nm BIO_free , +.Nm BIO_vfree , +.Nm BIO_free_all +.Nd BIO allocation and freeing functions +.Sh SYNOPSIS +.In openssl/bio.h +.Ft BIO * +.Fo BIO_new +.Fa "BIO_METHOD *type" +.Fc +.Ft int +.Fo BIO_set +.Fa "BIO *a" +.Fa "BIO_METHOD *type" +.Fc +.Ft int +.Fo BIO_free +.Fa "BIO *a" +.Fc +.Ft void +.Fo BIO_vfree +.Fa "BIO *a" +.Fc +.Ft void +.Fo BIO_free_all +.Fa "BIO *a" +.Fc +.Sh DESCRIPTION +The +.Fn BIO_new +function returns a new BIO using method +.Fa type . +.Pp +.Fn BIO_set +sets the method of an already existing BIO. +.Pp +.Fn BIO_free +frees up a single BIO, +.Fn BIO_vfree +also frees up a single BIO, but it does not return a value. +Calling +.Fn 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 +.Vt BIO_METHOD +descriptions. +.Pp +.Fn 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. +.Sh RETURN VALUES +.Fn BIO_new +returns a newly created BIO or +.Dv NULL +if the call fails. +.Pp +.Fn BIO_set +and +.Fn BIO_free +return 1 for success and 0 for failure. +.Pp +.Fn BIO_free_all +and +.Fn BIO_vfree +do not return values. +.Sh NOTES +Some BIOs (such as memory BIOs) can be used immediately after calling +.Fn BIO_new . +Others (such as file BIOs) need some additional initialization, and +frequently a utility function exists to create and initialize such BIOs. +.Pp +If +.Fn BIO_free +is called on a BIO chain, it will only free one BIO, +resulting in a memory leak. +.Pp +Calling +.Fn BIO_free_all +on a single BIO has the same effect as calling +.Fn BIO_free +on it other than the discarded return value. +.Pp +Normally the +.Fa type +argument is supplied by a function which returns a pointer to a +.Vt BIO_METHOD . +There is a naming convention for such functions: +a source/sink BIO is normally called +.Fn BIO_s_* +and a filter BIO +.Fn BIO_f_* . +.Sh EXAMPLES +Create a memory BIO: +.Pp +.Dl BIO *mem = BIO_new(BIO_s_mem()); diff --git a/lib/libcrypto/man/BIO_new_CMS.3 b/lib/libcrypto/man/BIO_new_CMS.3 new file mode 100644 index 00000000000..59c20347e5f --- /dev/null +++ b/lib/libcrypto/man/BIO_new_CMS.3 @@ -0,0 +1,83 @@ +.Dd October 2, 2010 +.Dt BIO_NEW_CMS 3 +.Os +.Sh NAME +.Nm BIO_new_CMS +.Nd CMS streaming filter BIO +.Sh SYNOPSIS +.In openssl/cms.h +.Ft BIO * +.Fo BIO_new_CMS +.Fa "BIO *out" +.Fa "CMS_ContentInfo *cms" +.Fc +.Sh DESCRIPTION +.Fn BIO_new_CMS +returns a streaming filter BIO chain based on +.Fa cms . +The output of the filter is written to +.Fa out . +Any data written to the chain is automatically translated +to a BER format CMS structure of the appropriate type. +.Sh RETURN VALUES +.Fn BIO_new_CMS +returns a BIO chain when successful or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh NOTES +The chain returned by this function behaves like a standard filter BIO. +It supports non blocking I/O. +Content is processed and streamed on the fly and not all held in memory +at once: so it is possible to encode very large structures. +After all content has been written through the chain +.Xr BIO_flush 3 +must be called to finalise the structure. +.Pp +The +.Dv CMS_STREAM +flag must be included in the corresponding +.Fa flags +parameter of the +.Fa cms +creation function. +.Pp +If an application wishes to write additional data to +.Fa out , +BIOs should be removed from the chain using +.Xr BIO_pop 3 +and freed with +.Xr BIO_free 3 +until +.Fa out +is reached. +If no additional data needs to be written, +.Xr BIO_free_all 3 +can be called to free up the whole chain. +.Pp +Any content written through the filter is used verbatim: +no canonical translation is performed. +.Pp +It is possible to chain multiple BIOs to, for example, +create a triple wrapped signed, enveloped, signed structure. +In this case it is the application's responsibility +to set the inner content type of any outer +.Vt CMS_ContentInfo +structures. +.Pp +Large numbers of small writes through the chain should be avoided as this +will produce an output consisting of lots of OCTET STRING structures. +Prepending a +.Xr BIO_f_buffer 3 +buffering BIO will prevent this. +.Sh SEE ALSO +.Xr CMS_encrypt 3 , +.Xr CMS_sign 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn BIO_new_CMS +was added to OpenSSL 1.0.0. +.Sh BUGS +There is currently no corresponding inverse BIO +which can decode a CMS structure on the fly. diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 5edbf7e3943..fcf94162483 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.16 2015/02/14 13:54:59 schwarze Exp $ +# $OpenBSD: Makefile,v 1.17 2015/02/14 14:09:01 schwarze Exp $ .include <bsd.own.mk> # for NOMAN @@ -10,9 +10,7 @@ MAN= \ ASN1_STRING_length.3 \ ASN1_STRING_new.3 \ ASN1_STRING_print_ex.3 \ - ASN1_generate_nconf.3 - -GENMAN= \ + ASN1_generate_nconf.3 \ BF_set_key.3 \ BIO.3 \ BIO_ctrl.3 \ @@ -23,6 +21,8 @@ GENMAN= \ BIO_f_null.3 \ BIO_find_type.3 \ BIO_new.3 \ + +GENMAN= \ BIO_push.3 \ BIO_read.3 \ BIO_s_accept.3 \ |