diff options
Diffstat (limited to 'doc')
33 files changed, 61 insertions, 983 deletions
diff --git a/doc/README b/doc/README index 6ecc14d9945..14469a82e3f 100644 --- a/doc/README +++ b/doc/README @@ -4,8 +4,6 @@ ssl/ssl.pod ......... Documentation of OpenSSL ssl.h+libssl.a openssl.txt ......... Assembled documentation files for OpenSSL [not final] ssleay.txt .......... Assembled documentation of ancestor SSLeay [obsolete] - standards.txt ....... Assembled pointers to standards, RFCs or internet drafts - that are related to OpenSSL. An archive of HTML documents for the SSLeay library is available from http://www.columbia.edu/~ariel/ssleay/ diff --git a/doc/apps/CA.pl.pod b/doc/apps/CA.pl.pod index 9d287f0c4d5..83e4c0af810 100644 --- a/doc/apps/CA.pl.pod +++ b/doc/apps/CA.pl.pod @@ -102,35 +102,6 @@ the request and finally create a PKCS#12 file containing it. CA.pl -signreq CA.pl -pkcs12 "My Test Certificate" -=head1 DSA CERTIFICATES - -Although the B<CA.pl> creates RSA CAs and requests it is still possible to -use it with DSA certificates and requests using the L<req(1)|req(1)> command -directly. The following example shows the steps that would typically be taken. - -Create some DSA parameters: - - openssl dsaparam -out dsap.pem 1024 - -Create a DSA CA certificate and private key: - - openssl req -x509 -newkey dsa:dsap.pem -keyout cacert.pem -out cacert.pem - -Create the CA directories and files: - - CA.pl -newca - -enter cacert.pem when prompted for the CA file name. - -Create a DSA certificate request and privat key (a different set of parameters -can optionally be created first): - - openssl req -out newreq.pem -newkey dsa:dsap.pem - -Sign the request: - - CA.pl -signreq - =head1 NOTES Most of the filenames mentioned can be modified by editing the B<CA.pl> script. diff --git a/doc/apps/ciphers.pod b/doc/apps/ciphers.pod index 21077614a72..2301e28251c 100644 --- a/doc/apps/ciphers.pod +++ b/doc/apps/ciphers.pod @@ -25,13 +25,9 @@ the appropriate cipherlist. =item B<-v> -verbose option. List ciphers with a complete description of -protocol version (SSLv2 or SSLv3; the latter includes TLS), key exchange, -authentication, encryption and mac algorithms used along with any key size +verbose option. List ciphers with a complete description of the authentication, +key exchange, encryption and mac algorithms used along with any key size restrictions and whether the algorithm is classed as an "export" cipher. -Note that without the B<-v> option, ciphers may seem to appear twice -in a cipher list; this is when similar ciphers are available for -SSL v2 and for SSL v3/TLS v1. =item B<-ssl3> diff --git a/doc/apps/dgst.pod b/doc/apps/dgst.pod index fcfd3ecf23f..cbf2cc529aa 100644 --- a/doc/apps/dgst.pod +++ b/doc/apps/dgst.pod @@ -6,7 +6,7 @@ dgst, md5, md2, sha1, sha, mdc2, ripemd160 - message digests =head1 SYNOPSIS -B<openssl> B<dgst> +[B<dgst>] [B<-md5|-md2|-sha1|-sha|mdc2|-ripemd160>] [B<-c>] [B<-d>] diff --git a/doc/apps/dhparam.pod b/doc/apps/dhparam.pod index ff8a6e5e5b6..6b237ec05a9 100644 --- a/doc/apps/dhparam.pod +++ b/doc/apps/dhparam.pod @@ -6,19 +6,18 @@ dhparam - DH parameter manipulation and generation =head1 SYNOPSIS -B<openssl dhparam> +B<openssl dh> [B<-inform DER|PEM>] [B<-outform DER|PEM>] -[B<-in> I<filename>] -[B<-out> I<filename>] -[B<-dsaparam>] +[B<-in filename>] +[B<-out filename>] [B<-noout>] [B<-text>] [B<-C>] [B<-2>] [B<-5>] -[B<-rand> I<file(s)>] -[I<numbits>] +[B<-rand file(s)>] +[numbits] =head1 DESCRIPTION @@ -40,46 +39,34 @@ additional header and footer lines. This specifies the output format, the options have the same meaning as the B<-inform> option. -=item B<-in> I<filename> +=item B<-in filename> This specifies the input filename to read parameters from or standard input if this option is not specified. -=item B<-out> I<filename> +=item B<-out filename> This specifies the output filename parameters to. Standard output is used if this option is not present. The output filename should B<not> be the same as the input filename. -=item B<-dsaparam> - -If this option is used, DSA rather than DH parameters are read or created; -they are converted to DH format. Otherwise, "strong" primes (such -that (p-1)/2 is also prime) will be used for DH parameter generation. - -DH parameter generation with the B<-dsaparam> option is much faster, -and the recommended exponent length is shorter, which makes DH key -exchange more efficient. Beware that with such DSA-style DH -parameters, a fresh DH key should be created for each use to -avoid small-subgroup attacks that may be possible otherwise. - =item B<-2>, B<-5> The generator to use, either 2 or 5. 2 is the default. If present then the input file is ignored and parameters are generated instead. -=item B<-rand> I<file(s)> +=item B<-rand file(s)> a file or files containing random data used to seed the random number generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +The separator is B<;> for MS-Windows, B<,> for OpenVSM, and B<:> for all others. -=item I<numbits> +=item B<numbits> this option specifies that a parameter set should be generated of size -I<numbits>. It must be the last option. If not present then a value of 512 +B<numbits>. It must be the last option. If not present then a value of 512 is used. If this option is present then the input file is ignored and parameters are generated instead. @@ -94,7 +81,7 @@ this option prints out the DH parameters in human readable form. =item B<-C> this option converts the parameters into C code. The parameters can then -be loaded by calling the B<get_dh>I<numbits>B<()> function. +be loaded by calling the B<get_dhXXX()> function. =back @@ -125,9 +112,4 @@ There should be a way to generate and manipulate DH keys. L<dsaparam(1)|dsaparam(1)> -=head1 HISTORY - -The B<dhparam> command was added in OpenSSL 0.9.5. -The B<-dsaparam> option was added in OpenSSL 0.9.6. - =cut diff --git a/doc/apps/dsaparam.pod b/doc/apps/dsaparam.pod index 50c2f61242f..8647f34698c 100644 --- a/doc/apps/dsaparam.pod +++ b/doc/apps/dsaparam.pod @@ -73,7 +73,7 @@ parameters. a file or files containing random data used to seed the random number generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +The separator is B<;> for MS-Windows, B<,> for OpenVSM, and B<:> for all others. =item B<numbits> diff --git a/doc/apps/gendsa.pod b/doc/apps/gendsa.pod index 74318fe7fb6..3314ace5172 100644 --- a/doc/apps/gendsa.pod +++ b/doc/apps/gendsa.pod @@ -34,7 +34,7 @@ If none of these options is specified no encryption is used. a file or files containing random data used to seed the random number generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +The separator is B<;> for MS-Windows, B<,> for OpenVSM, and B<:> for all others. =item B<paramfile> diff --git a/doc/apps/genrsa.pod b/doc/apps/genrsa.pod index cdcc03c1237..a2d878410b0 100644 --- a/doc/apps/genrsa.pod +++ b/doc/apps/genrsa.pod @@ -51,7 +51,7 @@ the public exponent to use, either 65537 or 3. The default is 65537. a file or files containing random data used to seed the random number generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +The separator is B<;> for MS-Windows, B<,> for OpenVSM, and B<:> for all others. =item B<numbits> @@ -83,6 +83,3 @@ be much larger (typically 1024 bits). =head1 SEE ALSO L<gendsa(1)|gendsa(1)> - -=cut - diff --git a/doc/apps/openssl.pod b/doc/apps/openssl.pod index 2fc61b6c217..9b1320606ba 100644 --- a/doc/apps/openssl.pod +++ b/doc/apps/openssl.pod @@ -12,10 +12,6 @@ I<command> [ I<command_opts> ] [ I<command_args> ] -B<openssl> [ B<list-standard-commands> | B<list-message-digest-commands> | B<list-cipher-commands> ] - -B<openssl> B<no->I<XXX> [ I<arbitrary options> ] - =head1 DESCRIPTION OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL @@ -39,22 +35,6 @@ The B<openssl> program provides a rich variety of commands (I<command> in the SYNOPSIS above), each of which often has a wealth of options and arguments (I<command_opts> and I<command_args> in the SYNOPSIS). -The pseudo-commands B<list-standard-commands>, B<list-message-digest-commands>, -and B<list-cipher-commands> output a list (one entry per line) of the names -of all standard commands, message digest commands, or cipher commands, -respectively, that are available in the present B<openssl> utility. - -The pseudo-command B<no->I<XXX> tests whether a command of the -specified name is available. If no command named I<XXX> exists, it -returns 0 (success) and prints B<no->I<XXX>; otherwise it returns 1 -and prints I<XXX>. In both cases, the output goes to B<stdout> and -nothing is printed to B<stderr>. Additional command line arguments -are always ignored. Since for each cipher there is a command of the -same name, this provides an easy way for shell scripts to test for the -availability of ciphers in the B<openssl> program. (B<no->I<XXX> is -not able to detect pseudo-commands such as B<quit>, -B<list->I<...>B<-commands>, or B<no->I<XXX> itself.) - =head2 STANDARD COMMANDS =over 10 @@ -123,10 +103,6 @@ Generation of hashed passwords. PKCS#7 Data Management. -=item L<B<rand>|rand(1)> - -Generate pseudo-random bytes. - =item L<B<req>|req(1)> X.509 Certificate Signing Request (CSR) Management. @@ -309,17 +285,14 @@ L<enc(1)|enc(1)>, L<gendsa(1)|gendsa(1)>, L<genrsa(1)|genrsa(1)>, L<nseq(1)|nseq(1)>, L<openssl(1)|openssl(1)>, L<passwd(1)|passwd(1)>, L<pkcs12(1)|pkcs12(1)>, L<pkcs7(1)|pkcs7(1)>, L<pkcs8(1)|pkcs8(1)>, -L<rand(1)|rand(1)>, L<req(1)|req(1)>, L<rsa(1)|rsa(1)>, L<s_client(1)|s_client(1)>, +L<req(1)|req(1)>, L<rsa(1)|rsa(1)>, L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<smime(1)|smime(1)>, L<spkac(1)|spkac(1)>, L<verify(1)|verify(1)>, L<version(1)|version(1)>, L<x509(1)|x509(1)>, L<crypto(3)|crypto(3)>, L<ssl(3)|ssl(3)> =head1 HISTORY -The openssl(1) document appeared in OpenSSL 0.9.2. -The B<list->I<XXX>B<-commands> pseudo-commands were added in OpenSSL 0.9.3; -the B<no->I<XXX> pseudo-commands were added in OpenSSL 0.9.5a. -For notes on the availability of other commands, see their individual -manual pages. +The openssl(1) document appeared in OpenSSL 0.9.2 =cut + diff --git a/doc/apps/pkcs12.pod b/doc/apps/pkcs12.pod index c4009998b8a..241f9c4a8b0 100644 --- a/doc/apps/pkcs12.pod +++ b/doc/apps/pkcs12.pod @@ -244,7 +244,7 @@ to be needed to use MAC iterations counts but they are now used by default. a file or files containing random data used to seed the random number generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +The separator is B<;> for MS-Windows, B<,> for OpenVSM, and B<:> for all others. =back diff --git a/doc/apps/rand.pod b/doc/apps/rand.pod deleted file mode 100644 index cbf8768801b..00000000000 --- a/doc/apps/rand.pod +++ /dev/null @@ -1,50 +0,0 @@ -=pod - -=head1 NAME - -rand - generate pseudo-random bytes - -=head1 SYNOPSIS - -B<openssl rand> -[B<-out> I<file>] -[B<-rand> I<file(s)>] -[B<-base64>] -I<num> - -=head1 DESCRIPTION - -The B<rand> command outputs I<num> pseudo-random bytes after seeding -the random number generater once. As in other B<openssl> command -line tools, PRNG seeding uses the file I<$HOME/>B<.rnd> or B<.rnd> -in addition to the files given in the B<-rand> option. A new -I<$HOME>/B<.rnd> or B<.rnd> file will be written back if enough -seeding was obtained from these sources. - -=head1 OPTIONS - -=over 4 - -=item B<-out> I<file> - -Write to I<file> instead of standard output. - -=item B<-rand> I<file(s)> - -Use specified file or files or EGD socket (see L<RAND_egd(3)|RAND_egd(3)>) -for seeding the random number generator. -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-base64> - -Perform base64 encoding on the output. - -=back - -=head1 SEE ALSO - -L<RAND_bytes(3)|RAND_bytes(3)> - -=cut diff --git a/doc/apps/s_client.pod b/doc/apps/s_client.pod index 2f803753199..3ede134164c 100644 --- a/doc/apps/s_client.pod +++ b/doc/apps/s_client.pod @@ -22,7 +22,6 @@ B<openssl> B<s_client> [B<-state>] [B<-nbio>] [B<-crlf>] -[B<-ign_eof>] [B<-quiet>] [B<-ssl2>] [B<-ssl3>] @@ -123,15 +122,9 @@ turns on non-blocking I/O this option translated a line feed from the terminal into CR+LF as required by some servers. -=item B<-ign_eof> - -inhibit shutting down the connection when end of file is reached in the -input. - =item B<-quiet> -inhibit printing of session and certificate information. This implicitely -turns on B<-ign_eof> as well. +inhibit printing of session and certificate information. =item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> @@ -162,10 +155,9 @@ command for more information. If a connection is established with an SSL server then any data received from the server is displayed and any key presses will be sent to the -server. When used interactively (which means neither B<-quiet> nor B<-ign_eof> -have been given), the session will be renegociated if the line begins with an -B<R>, and if the line begins with a B<Q> or if end of file is reached, the -connection will be closed down. +server. If the line begins with an B<R> then the session will be +renegotiated. If the line begins with a B<Q> the connection will be closed +down. =head1 NOTES diff --git a/doc/apps/smime.pod b/doc/apps/smime.pod index 5dee9356068..631ecdc241e 100644 --- a/doc/apps/smime.pod +++ b/doc/apps/smime.pod @@ -179,7 +179,7 @@ the B<-recip> or B<-signer> file. a file or files containing random data used to seed the random number generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +The separator is B<;> for MS-Windows, B<,> for OpenVSM, and B<:> for all others. =item B<cert.pem...> diff --git a/doc/apps/x509.pod b/doc/apps/x509.pod index e4ae5468da3..b127182bbbf 100644 --- a/doc/apps/x509.pod +++ b/doc/apps/x509.pod @@ -212,10 +212,9 @@ clears all the prohibited or rejected uses of the certificate. =item B<-addtrust arg> -adds a trusted certificate use. Any object name can be used here -but currently only B<clientAuth> (SSL client use), B<serverAuth> -(SSL server use) and B<emailProtection> (S/MIME email) are used. -Other OpenSSL applications may define additional uses. +adds a trusted certificate use. Currently acceptable values +are B<all> (any purpose), B<sslclient> (SSL client use), B<sslserver> +(SSL server use) B<email> (S/MIME email) and B<objsign> (Object signing). =item B<-addreject arg> diff --git a/doc/crypto/BN_mod_mul_montgomery.pod b/doc/crypto/BN_mod_mul_montgomery.pod index b190b4013db..0f0c1375af2 100644 --- a/doc/crypto/BN_mod_mul_montgomery.pod +++ b/doc/crypto/BN_mod_mul_montgomery.pod @@ -49,7 +49,7 @@ 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. +BN_to_montgomery() computes Mont(B<a>,R^2). For all functions, B<ctx> is a previously allocated B<BN_CTX> used for temporary variables. diff --git a/doc/crypto/DH_set_method.pod b/doc/crypto/DH_set_method.pod index a8f75bdd9d0..dca41d8dbc8 100644 --- a/doc/crypto/DH_set_method.pod +++ b/doc/crypto/DH_set_method.pod @@ -56,7 +56,7 @@ the default method is used. /* 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) */ + /* compute r = a ^ p mod m. May be NULL */ int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); diff --git a/doc/crypto/DSA_set_method.pod b/doc/crypto/DSA_set_method.pod index edec46413d6..0b13ec9237c 100644 --- a/doc/crypto/DSA_set_method.pod +++ b/doc/crypto/DSA_set_method.pod @@ -62,13 +62,12 @@ struct 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) */ + /* compute rr = a1^p1 * a2^p2 mod m. May be NULL */ 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) */ + /* compute r = a ^ p mod m. May be NULL */ int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a, const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); diff --git a/doc/crypto/ERR_error_string.pod b/doc/crypto/ERR_error_string.pod index d09620e9350..0d2417599cd 100644 --- a/doc/crypto/ERR_error_string.pod +++ b/doc/crypto/ERR_error_string.pod @@ -9,7 +9,6 @@ ERR_error_string - obtain human-readable error message #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); @@ -18,13 +17,9 @@ ERR_error_string - obtain human-readable error message =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 +error code B<e>, and places it at B<buf>. B<buf> must be at least 120 +bytes long. If B<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: @@ -50,7 +45,7 @@ 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. +string if B<buf == NULL>, B<buf> otherwise. ERR_lib_error_string(), ERR_func_error_string() and ERR_reason_error_string() return the strings, and B<NULL> if @@ -66,6 +61,5 @@ 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/doc/crypto/ERR_remove_state.pod b/doc/crypto/ERR_remove_state.pod index 72925fb9f47..ebcdc0f5a5b 100644 --- a/doc/crypto/ERR_remove_state.pod +++ b/doc/crypto/ERR_remove_state.pod @@ -16,7 +16,7 @@ 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 +threads, they must be freed when threads are terminated in oder to avoid memory leaks. =head1 RETURN VALUE diff --git a/doc/crypto/EVP_OpenInit.pod b/doc/crypto/EVP_OpenInit.pod deleted file mode 100644 index 9707a4b3997..00000000000 --- a/doc/crypto/EVP_OpenInit.pod +++ /dev/null @@ -1,51 +0,0 @@ -=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); - void EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); - void 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() initialises 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 RETURN VALUES - -EVP_OpenInit() returns -1 on error or an non zero integer (actually the -recovered secret key size) if successful. - -EVP_SealUpdate() does not return a value. - -EVP_SealFinal() 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/doc/crypto/EVP_SealInit.pod b/doc/crypto/EVP_SealInit.pod deleted file mode 100644 index 1579d110fa2..00000000000 --- a/doc/crypto/EVP_SealInit.pod +++ /dev/null @@ -1,70 +0,0 @@ -=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); - void EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); - void 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() initialises 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 -1 on error or B<npubk> if successful. - -EVP_SealUpdate() and EVP_SealFinal() do not return values. - -=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. - -=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/doc/crypto/EVP_SignInit.pod b/doc/crypto/EVP_SignInit.pod deleted file mode 100644 index bbc9203c9ca..00000000000 --- a/doc/crypto/EVP_SignInit.pod +++ /dev/null @@ -1,85 +0,0 @@ -=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() initialises 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 funtion 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 initialiase -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/doc/crypto/EVP_VerifyInit.pod b/doc/crypto/EVP_VerifyInit.pod deleted file mode 100644 index 3b5e07f4ade..00000000000 --- a/doc/crypto/EVP_VerifyInit.pod +++ /dev/null @@ -1,71 +0,0 @@ -=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() initialises 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 funtion 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 initialiase 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_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/doc/crypto/RAND_add.pod b/doc/crypto/RAND_add.pod index 67c66f3e0c9..0a13ec2a92b 100644 --- a/doc/crypto/RAND_add.pod +++ b/doc/crypto/RAND_add.pod @@ -2,8 +2,7 @@ =head1 NAME -RAND_add, RAND_seed, RAND_status, RAND_event, RAND_screen - add -entropy to the PRNG +RAND_add, RAND_seed, RAND_screen - add entropy to the PRNG =head1 SYNOPSIS @@ -15,7 +14,6 @@ entropy to the PRNG int RAND_status(void); - int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); void RAND_screen(void); =head1 DESCRIPTION @@ -42,24 +40,17 @@ 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. +For applications that can catch Windows events, seeding the PRNG with +the parameters of B<WM_MOUSEMOVE> events 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. +RAND_status() returns 1 if the PRNG has been seeded with enough data, +0 otherwise. The other functions do not return values. @@ -72,6 +63,6 @@ L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> 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. +0.9.5. =cut diff --git a/doc/crypto/RAND_set_rand_method.pod b/doc/crypto/RAND_set_rand_method.pod index 464eba416d4..466e9b8767b 100644 --- a/doc/crypto/RAND_set_rand_method.pod +++ b/doc/crypto/RAND_set_rand_method.pod @@ -34,12 +34,10 @@ RAND_get_rand_method() returns a pointer to the current method. 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(). +RAND_bytes(), RAND_cleanup(), RAND_add() and RAND_pseudo_rand(). Each component may be NULL if the function is not implemented. =head1 RETURN VALUES diff --git a/doc/crypto/RSA_set_method.pod b/doc/crypto/RSA_set_method.pod index 14b0b4cf359..deb1183a235 100644 --- a/doc/crypto/RSA_set_method.pod +++ b/doc/crypto/RSA_set_method.pod @@ -87,11 +87,10 @@ the default method is used. 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) */ + /* compute r0 = r0 ^ I mod rsa->n. May be NULL */ int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa); - /* compute r = a ^ p mod m (May be NULL for some implementations) */ + /* compute r = a ^ p mod m. May be NULL */ int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); diff --git a/doc/crypto/blowfish.pod b/doc/crypto/blowfish.pod index 4320af0809d..e8c7114311b 100644 --- a/doc/crypto/blowfish.pod +++ b/doc/crypto/blowfish.pod @@ -28,7 +28,7 @@ BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption =head1 DESCRIPTION This library implements the Blowfish cipher, which is invented and described -by Counterpane (see http://www.counterpane.com/blowfish.html ). +by Counterpane (see http://www.counterpane.com/blowfish/ ). 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 @@ -57,31 +57,28 @@ 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 initialisation 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 initialised with anything, but the -recipient needs to know what it was initialised with, or it won't be able -to decrypt. Some programs and protocols simplify this, like SSH, where -B<ivec> is simply initialised to zero. +B<ivec> which must be initially filled with zeros, but then just need to be +passed along into the next call of the same function for the same message. 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 initialised -to zero when B<ivec> is initialised. +to zero when B<ivec> is filled with zeros. 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 initialisation vector. +long initialisation vector, which must be initially filled with zeros. 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 initialisation vector. B<num> must point at an integer which must -be initially zero. +8 byte long initialisation vector, which must be initially filled with zeros. +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 initialised diff --git a/doc/crypto/des.pod b/doc/crypto/des.pod deleted file mode 100644 index c553210ef28..00000000000 --- a/doc/crypto/des.pod +++ /dev/null @@ -1,376 +0,0 @@ -=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 dependant 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 -chaing 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 -standarf 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 tranformations: - -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 ([email protected]). Modified for the OpenSSL project -(http://www.openssl.org). - -=cut diff --git a/doc/crypto/des_modes.pod b/doc/crypto/des_modes.pod index 1aa3ac763b9..d8148c86fc8 100644 --- a/doc/crypto/des_modes.pod +++ b/doc/crypto/des_modes.pod @@ -248,6 +248,3 @@ it to: L<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<idea(3)|idea(3)>, L<rc2(3)|rc2(3)> - -=cut - diff --git a/doc/crypto/rsa.pod b/doc/crypto/rsa.pod index eb8ba612c48..0486c044a68 100644 --- a/doc/crypto/rsa.pod +++ b/doc/crypto/rsa.pod @@ -86,9 +86,8 @@ contain public as well as private RSA keys: 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. +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 diff --git a/doc/ssl/SSL_get_error.pod b/doc/ssl/SSL_get_error.pod index cde0efc3ce7..9cacdedc575 100644 --- a/doc/ssl/SSL_get_error.pod +++ b/doc/ssl/SSL_get_error.pod @@ -40,7 +40,7 @@ if and only if B<ret E<gt> 0>. The SSL connection has been closed. If the protocol version is SSL 3.0 or TLS 1.0, this result code is returned only if a closure -alert has occurred in the protocol, i.e. if the connection has been +alerts has occurred in the protocol, i.e. if the connection has been closed cleanly. =item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod index 362c414bb82..e53876654a7 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -163,7 +163,7 @@ Determine the number of bits in I<cipher>. Because of export crippled ciphers there are two bits: The bits the algorithm supports in general (stored to I<alg_bits>) and the bits which are actually used (the return value). -=item const char *B<SSL_CIPHER_get_name>(SSL_CIPHER *cipher); +=item char *B<SSL_CIPHER_get_name>(SSL_CIPHER *cipher); Return the internal name of I<cipher> as a string. These are the various strings defined by the I<SSL2_TXT_xxx>, I<SSL3_TXT_xxx> and I<TLS1_TXT_xxx> @@ -437,7 +437,7 @@ connection defined in the B<SSL> structure. =item X509 *B<SSL_get_certificate>(SSL *ssl); -=item const char *B<SSL_get_cipher>(SSL *ssl); +=item SSL_CIPHER *B<SSL_get_cipher>(SSL *ssl); =item int B<SSL_get_cipher_bits>(SSL *ssl, int *alg_bits); diff --git a/doc/standards.txt b/doc/standards.txt deleted file mode 100644 index b451907567b..00000000000 --- a/doc/standards.txt +++ /dev/null @@ -1,101 +0,0 @@ -Standards related to OpenSSL -============================ - -[Please, this is currently a draft. I made a first try at finding - documents that describe parts of what OpenSSL implements. There are - big gaps, and I've most certainly done something wrong. Please - correct whatever is... Also, this note should be removed when this - file is reaching a somewhat correct state. -- Richard Levitte] - - -All pointers in here will be either URL's or blobs of text borrowed -from miscellaneous indexes, like rfc-index.txt (index of RFCs), -1id-index.txt (index of Internet drafts) and the like. - -To find the latest possible RFCs, it's recommended to either browse -ftp://ftp.isi.edu/in-notes/ or go to http://www.rfc-editor.org/ and -use the search mechanism found there. -To find the latest possible Internet drafts, it's recommended to -browse ftp://ftp.isi.edu/internet-drafts/. -To find the latest possible PKCS, it's recommended to browse -http://www.rsasecurity.com/rsalabs/pkcs/. - - -Implemented: ------------- - -These are documents that describe things that are implemented in OpenSSL. - -1319 The MD2 Message-Digest Algorithm. B. Kaliski. April 1992. - (Format: TXT=25661 bytes) (Status: INFORMATIONAL) - -1320 The MD4 Message-Digest Algorithm. R. Rivest. April 1992. (Format: - TXT=32407 bytes) (Status: INFORMATIONAL) - -1321 The MD5 Message-Digest Algorithm. R. Rivest. April 1992. (Format: - TXT=35222 bytes) (Status: INFORMATIONAL) - -2246 The TLS Protocol Version 1.0. T. Dierks, C. Allen. January 1999. - (Format: TXT=170401 bytes) (Status: PROPOSED STANDARD) - -2268 A Description of the RC2(r) Encryption Algorithm. R. Rivest. - January 1998. (Format: TXT=19048 bytes) (Status: INFORMATIONAL) - -2314 PKCS 10: Certification Request Syntax Version 1.5. B. Kaliski. - March 1998. (Format: TXT=15814 bytes) (Status: INFORMATIONAL) - -2315 PKCS 7: Cryptographic Message Syntax Version 1.5. B. Kaliski. - March 1998. (Format: TXT=69679 bytes) (Status: INFORMATIONAL) - -2437 PKCS #1: RSA Cryptography Specifications Version 2.0. B. Kaliski, - J. Staddon. October 1998. (Format: TXT=73529 bytes) (Obsoletes - RFC2313) (Status: INFORMATIONAL) - -2459 Internet X.509 Public Key Infrastructure Certificate and CRL - Profile. R. Housley, W. Ford, W. Polk, D. Solo. January 1999. - (Format: TXT=278438 bytes) (Status: PROPOSED STANDARD) - -PKCS#12: Personal Informatoin Exchange Syntax Standard, version 1.0. - - -Related: --------- - -These are documents that are close to OpenSSL, for example the -STARTTLS documents. - -2487 SMTP Service Extension for Secure SMTP over TLS. P. Hoffman. - January 1999. (Format: TXT=15120 bytes) (Status: PROPOSED STANDARD) - -2585 Internet X.509 Public Key Infrastructure Operational Protocols: - FTP and HTTP. R. Housley, P. Hoffman. May 1999. (Format: TXT=14813 - bytes) (Status: PROPOSED STANDARD) - -2595 Using TLS with IMAP, POP3 and ACAP. C. Newman. June 1999. - (Format: TXT=32440 bytes) (Status: PROPOSED STANDARD) - -2712 Addition of Kerberos Cipher Suites to Transport Layer Security - (TLS). A. Medvinsky, M. Hur. October 1999. (Format: TXT=13763 bytes) - (Status: PROPOSED STANDARD) - -2817 Upgrading to TLS Within HTTP/1.1. R. Khare, S. Lawrence. May - 2000. (Format: TXT=27598 bytes) (Updates RFC2616) (Status: PROPOSED - STANDARD) - -2818 HTTP Over TLS. E. Rescorla. May 2000. (Format: TXT=15170 bytes) - (Status: INFORMATIONAL) - - "Securing FTP with TLS", 01/27/2000, <draft-murray-auth-ftp-ssl-05.txt> - - -To be implemented: ------------------- - -These are documents that describe things that are planed to be -implemented in the hopefully short future. - -2560 X.509 Internet Public Key Infrastructure Online Certificate - Status Protocol - OCSP. M. Myers, R. Ankney, A. Malpani, S. Galperin, - C. Adams. June 1999. (Format: TXT=43243 bytes) (Status: PROPOSED - STANDARD) - |