Aren/NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

OpenSSL 0.9.6a

Browse Source
This commit is contained in:
itojun 2001-04-12 03:10:36 +00:00
parent d94ce2f426
commit 75902e8d9b
206 changed files with 12211 additions and 3596 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
crypto/dist/openssl/VMS/install.com vendored
View File

@ -34,10 +34,8 @@ $ IF F$PARSE("WRK_SSLINCLUDE:") .EQS. "" THEN -
$ IF F$PARSE("WRK_SSLROOT:[VMS]") .EQS. "" THEN -
CREATE/DIR/LOG WRK_SSLROOT:[VMS]
$
$ EXHEADER := vms_idhacks.h
$
$ COPY 'EXHEADER' WRK_SSLINCLUDE: /LOG
$ SET FILE/PROT=WORLD:RE WRK_SSLINCLUDE:'EXHEADER'
$ IF F$SEARCH("WRK_SSLINCLUDE:vms_idhacks.h") .NES. "" THEN -
DELETE WRK_SSLINCLUDE:vms_idhacks.h;*
$
$ OPEN/WRITE SF WRK_SSLROOT:[VMS]OPENSSL_STARTUP.COM
$ WRITE SYS$OUTPUT "%OPEN-I-CREATED, ",F$SEARCH("WRK_SSLROOT:[VMS]OPENSSL_STARTUP.COM")," created."

2
crypto/dist/openssl/doc/README vendored
View File

@ -4,6 +4,8 @@
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/

11
crypto/dist/openssl/doc/apps/CA.pl.pod vendored
View File

@ -69,9 +69,16 @@ list box), otherwise the name "My Certificate" is used.
calls the B<ca> program to sign a certificate request. It expects the request
to be in the file "newreq.pem". The new certificate is written to the file
"newcert.pem" except in the case of the B<-xcert> option when it is written
"newcert.pem" except in the case of the B<-xsign> option when it is written
to standard output.
=item B<-signCA>
this option is the same as the B<-signreq> option except it uses the configuration
file section B<v3_ca> and so makes the signed request a valid CA certificate. This
is useful when creating intermediate CA from a root CA.
=item B<-signcert>
this option is the same as B<-sign> except it expects a self signed certificate
@ -122,7 +129,7 @@ Create the CA directories and files:
enter cacert.pem when prompted for the CA file name.
Create a DSA certificate request and privat key (a different set of parameters
Create a DSA certificate request and private key (a different set of parameters
can optionally be created first):
openssl req -out newreq.pem -newkey dsa:dsap.pem

9
crypto/dist/openssl/doc/apps/ca.pod vendored
View File

@ -23,6 +23,7 @@ B<openssl> B<ca>
[B<-policy arg>]
[B<-keyfile arg>]
[B<-key arg>]
[B<-passin arg>]
[B<-cert file>]
[B<-in file>]
[B<-out file>]
@ -99,6 +100,10 @@ the password used to encrypt the private key. Since on some
systems the command line arguments are visible (e.g. Unix with
the 'ps' utility) this option should be used with caution.
=item B<-passin arg>
the key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-verbose>
this prints extra details about the operations being performed.
@ -342,6 +347,10 @@ Sign a certificate request:
openssl ca -in req.pem -out newcert.pem
Sign a certificate request, using CA extensions:
openssl ca -in req.pem -extensions v3_ca -out newcert.pem
Generate a CRL
openssl ca -gencrl -out crl.pem

8
crypto/dist/openssl/doc/apps/ciphers.pod vendored
View File

@ -25,9 +25,13 @@ the appropriate cipherlist.
=item B<-v>
verbose option. List ciphers with a complete description of the authentication,
key exchange, encryption and mac algorithms used along with any key size
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
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>

67
crypto/dist/openssl/doc/apps/dgst.pod vendored
View File

@ -2,25 +2,32 @@
=head1 NAME
dgst, md5, md2, sha1, sha, mdc2, ripemd160 - message digests
dgst, md5, md4, md2, sha1, sha, mdc2, ripemd160 - message digests
=head1 SYNOPSIS
B<openssl> B<dgst>
[B<-md5|-md2|-sha1|-sha|mdc2|-ripemd160>]
[B<-md5|-md4|-md2|-sha1|-sha|-mdc2|-ripemd160|-dss1>]
[B<-c>]
[B<-d>]
[B<-hex>]
[B<-binary>]
[B<-out filename>]
[B<-sign filename>]
[B<-verify filename>]
[B<-prverify filename>]
[B<-signature filename>]
[B<file...>]
[B<md5|md2|sha1|sha|mdc2|ripemd160>]
[B<md5|md4|md2|sha1|sha|mdc2|ripemd160>]
[B<-c>]
[B<-d>]
[B<file...>]
=head1 DESCRIPTION
The digest functions print out the message digest of a supplied file or files
in hexadecimal form.
The digest functions output the message digest of a supplied file or files
in hexadecimal form. They can also be used for digital signing and verification.
=head1 OPTIONS
@ -28,12 +35,51 @@ in hexadecimal form.
=item B<-c>
print out the digest in two digit groups separated by colons.
print out the digest in two digit groups separated by colons, only relevant if
B<hex> format output is used.
=item B<-d>
print out BIO debugging information.
=item B<-hex>
digest is to be output as a hex dump. This is the default case for a "normal"
digest as opposed to a digital signature.
=item B<-binary>
output the digest or signature in binary form.
=item B<-out filename>
filename to output to, or standard output by default.
=item B<-sign filename>
digitally sign the digest using the private key in "filename".
=item B<-verify filename>
verify the signature using the the public key in "filename".
The output is either "Verification OK" or "Verification Failure".
=item B<-prverify filename>
verify the signature using the the private key in "filename".
=item B<-signature filename>
the actual signature to verify.
=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
all others.
=item B<file...>
file or files to digest. If no files are specified then standard input is
@ -46,4 +92,13 @@ used.
The digest of choice for all new applications is SHA1. Other digests are
however still widely used.
If you wish to sign or verify data using the DSA algorithm then the dss1
digest must be used.
A source of random numbers is required for certain signing algorithms, in
particular DSA.
The signing and verify options should only be used if a single file is
being signed or verified.
=cut

2
crypto/dist/openssl/doc/apps/dhparam.pod vendored
View File

@ -73,7 +73,7 @@ input file is ignored and parameters are generated instead.
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 OpenVSM, and B<:> for
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item I<numbits>

2
crypto/dist/openssl/doc/apps/dsaparam.pod vendored
View File

@ -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 OpenVSM, and B<:> for
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<numbits>

2
crypto/dist/openssl/doc/apps/gendsa.pod vendored
View File

@ -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 OpenVSM, and B<:> for
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<paramfile>

2
crypto/dist/openssl/doc/apps/genrsa.pod vendored
View File

@ -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 OpenVSM, and B<:> for
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<numbits>

19
crypto/dist/openssl/doc/apps/openssl.pod vendored
View File

@ -83,9 +83,10 @@ CRL to PKCS#7 Conversion.
Message Digest Calculation.
=item L<B<dh>|dh(1)>
=item B<dh>
Diffie-Hellman Data Management.
Diffie-Hellman Parameter Management.
Obsoleted by L<B<dhparam>|dhparam(1)>.
=item L<B<dsa>|dsa(1)>
@ -103,9 +104,14 @@ Encoding with Ciphers.
Error Number to Error String Conversion.
=item L<B<gendh>|gendh(1)>
=item L<B<dhparam>|dhparam(1)>
Generation and Management of Diffie-Hellman Parameters.
=item B<gendh>
Generation of Diffie-Hellman Parameters.
Obsoleted by L<B<dhparam>|dhparam(1)>.
=item L<B<gendsa>|gendsa(1)>
@ -135,6 +141,10 @@ X.509 Certificate Signing Request (CSR) Management.
RSA Data Management.
=item L<B<rsautl>|rsautl(1)>
RSA utility for signing, verification, encryption, and decryption.
=item L<B<s_client>|s_client(1)>
This implements a generic SSL/TLS client which can establish a transparent
@ -309,7 +319,8 @@ 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<rand(1)|rand(1)>, L<req(1)|req(1)>, L<rsa(1)|rsa(1)>,
L<rsautl(1)|rsautl(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)>

13
crypto/dist/openssl/doc/apps/passwd.pod vendored
View File

@ -8,6 +8,7 @@ passwd - compute password hashes
B<openssl passwd>
[B<-crypt>]
[B<-1>]
[B<-apr1>]
[B<-salt> I<string>]
[B<-in> I<file>]
@ -22,8 +23,8 @@ The B<passwd> command computes the hash of a password typed at
run-time or the hash of each password in a list. The password list is
taken from the named file for option B<-in file>, from stdin for
option B<-stdin>, and from the command line otherwise.
The Unix standard algorithm B<crypt> and the MD5-based B<apr1> algorithm
are available.
The Unix standard algorithm B<crypt> and the MD5-based BSD password
algorithm B<1> and its Apache variant B<apr1> are available.
=head1 OPTIONS
@ -33,9 +34,13 @@ are available.
Use the B<crypt> algorithm (default).
=item B<-1>
Use the MD5 based BSD password algorithm B<1>.
=item B<-apr1>
Use the B<apr1> algorithm.
Use the B<apr1> algorithm (Apache variant of the BSD algorithm).
=item B<-salt> I<string>
@ -64,6 +69,8 @@ to each password hash.
B<openssl passwd -crypt -salt xx password> prints B<xxj31ZMTZzkVA>.
B<openssl passwd -1 -salt xxxxxxxx password> prints B<$1$xxxxxxxx$8XJIcl6ZXqBMCK0qFevqT1>.
B<openssl passwd -apr1 -salt xxxxxxxx password> prints B<$apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0>.
=cut

22
crypto/dist/openssl/doc/apps/pkcs12.pod vendored
View File

@ -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 OpenVSM, and B<:> for
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=back
@ -304,6 +304,26 @@ Include some extra certificates:
Some would argue that the PKCS#12 standard is one big bug :-)
Versions of OpenSSL before 0.9.6a had a bug in the PKCS#12 key generation
routines. Under rare circumstances this could produce a PKCS#12 file encrypted
with an invalid key. As a result some PKCS#12 files which triggered this bug
from other implementations (MSIE or Netscape) could not be decrypted
by OpenSSL and similarly OpenSSL could produce PKCS#12 files which could
not be decrypted by other implementations. The chances of producing such
a file are relatively small: less than 1 in 256.
A side effect of fixing this bug is that any old invalidly encrypted PKCS#12
files cannot no longer be parsed by the fixed version. Under such circumstances
the B<pkcs12> utility will report that the MAC is OK but fail with a decryption
error when extracting private keys.
This problem can be resolved by extracting the private keys and certificates
from the PKCS#12 file using an older version of OpenSSL and recreating the PKCS#12
file from the keys and certificates using a newer version of OpenSSL. For example:
old-openssl -in bad.p12 -out keycerts.pem
openssl -in keycerts.pem -export -name "My PKCS#12 file" -out fixed.p12
=head1 SEE ALSO
L<pkcs8(1)|pkcs8(1)>

2
crypto/dist/openssl/doc/apps/rand.pod vendored
View File

@ -34,7 +34,7 @@ Write to I<file> instead of standard output.
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 OpenVSM, and B<:> for
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-base64>

10
crypto/dist/openssl/doc/apps/req.pod vendored
View File

@ -19,6 +19,7 @@ B<openssl> B<req>
[B<-verify>]
[B<-modulus>]
[B<-new>]
[B<-rand file(s)>]
[B<-newkey rsa:bits>]
[B<-newkey dsa:file>]
[B<-nodes>]
@ -104,6 +105,14 @@ in the configuration file and any requested extensions.
If the B<-key> option is not used it will generate a new RSA private
key using information specified in the configuration file.
=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
all others.
=item B<-newkey arg>
this option creates a new certificate request and a new private
@ -158,6 +167,7 @@ when the B<-x509> option is being used this specifies the number of
days to certify the certificate for. The default is 30 days.
=item B<-extensions section>
=item B<-reqexts section>
these options specify alternative sections to include certificate

31
crypto/dist/openssl/doc/apps/rsa.pod vendored
View File

@ -14,6 +14,7 @@ B<openssl> B<rsa>
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-sgckey>]
[B<-des>]
[B<-des3>]
[B<-idea>]
@ -42,9 +43,8 @@ This specifies the input format. The B<DER> option uses an ASN1 DER encoded
form compatible with the PKCS#1 RSAPrivateKey or SubjectPublicKeyInfo format.
The B<PEM> form is the default format: it consists of the B<DER> format base64
encoded with additional header and footer lines. On input PKCS#8 format private
keys are also accepted. The B<NET> form is a format compatible with older Netscape
servers and MS IIS, this uses unsalted RC4 for its encryption. It is not very
secure and so should only be used when necessary.
keys are also accepted. The B<NET> form is a format is described in the B<NOTES>
section.
=item B<-outform DER|NET|PEM>
@ -74,6 +74,11 @@ filename.
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-sgckey>
use the modified NET algorithm used with some versions of Microsoft IIS and SGC
keys.
=item B<-des|-des3|-idea>
These options encrypt the private key with the DES, triple DES, or the
@ -126,6 +131,18 @@ The PEM public key format uses the header and footer lines:
-----BEGIN PUBLIC KEY-----
-----END PUBLIC KEY-----
The B<NET> form is a format compatible with older Netscape servers
and Microsoft IIS .key files, this uses unsalted RC4 for its encryption.
It is not very secure and so should only be used when necessary.
Some newer version of IIS have additional data in the exported .key
files. To use thse with the utility view the file with a binary editor
and look for the string "private-key", then trace back to the byte
sequence 0x30, 0x82 (this is an ASN1 SEQUENCE). Copy all the data
from this point onwards to another file and use that as the input
to the B<rsa> utility with the B<-inform NET> option. If you get
an error after entering the password try the B<-sgckey> option.
=head1 EXAMPLES
To remove the pass phrase on an RSA private key:
@ -148,6 +165,14 @@ To just output the public part of a private key:
openssl rsa -in key.pem -pubout -out pubkey.pem
=head1 BUGS
The command line password arguments don't currently work with
B<NET> format.
There should be an option that automatically handles .key files,
without having to manually edit them.
=head1 SEE ALSO
L<pkcs8(1)|pkcs8(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>,

183
crypto/dist/openssl/doc/apps/rsautl.pod vendored Normal file
View File

@ -0,0 +1,183 @@
=pod
=head1 NAME
rsautl - RSA utility
=head1 SYNOPSIS
B<openssl> B<rsautl>
[B<-in file>]
[B<-out file>]
[B<-inkey file>]
[B<-pubin>]
[B<-certin>]
[B<-sign>]
[B<-verify>]
[B<-encrypt>]
[B<-decrypt>]
[B<-pkcs>]
[B<-ssl>]
[B<-raw>]
[B<-hexdump>]
[B<-asn1parse>]
=head1 DESCRIPTION
The B<rsautl> command can be used to sign, verify, encrypt and decrypt
data using the RSA algorithm.
=head1 COMMAND OPTIONS
=over 4
=item B<-in filename>
This specifies the input filename to read data from or standard input
if this option is not specified.
=item B<-out filename>
specifies the output filename to write to or standard output by
default.
=item B<-inkey file>
the input key file, by default it should be an RSA private key.
=item B<-pubin>
the input file is an RSA public key.
=item B<-certin>
the input is a certificate containing an RSA public key.
=item B<-sign>
sign the input data and output the signed result. This requires
and RSA private key.
=item B<-verify>
verify the input data and output the recovered data.
=item B<-encrypt>
encrypt the input data using an RSA public key.
=item B<-decrypt>
decrypt the input data using an RSA private key.
=item B<-pkcs, -oaep, -ssl, -raw>
the padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP,
special padding used in SSL v2 backwards compatible handshakes,
or no padding, respectively.
For signatures, only B<-pkcs> and B<-raw> can be used.
=item B<-hexdump>
hex dump the output data.
=item B<-asn1parse>
asn1parse the output data, this is useful when combined with the
B<-verify> option.
=back
=head1 NOTES
B<rsautl> because it uses the RSA algorithm directly can only be
used to sign or verify small pieces of data.
=head1 EXAMPLES
Sign some data using a private key:
openssl rsautl -sign -in file -inkey key.pem -out sig
Recover the signed data
openssl rsautl -sign -in sig -inkey key.pem
Examine the raw signed data:
openssl rsautl -sign -in file -inkey key.pem -raw -hexdump
0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64 .....hello world
The PKCS#1 block formatting is evident from this. If this was done using
encrypt and decrypt the block would have been of type 2 (the second byte)
and random padding data visible instead of the 0xff bytes.
It is possible to analyse the signature of certificates using this
utility in conjunction with B<asn1parse>. Consider the self signed
example in certs/pca-cert.pem . Running B<asn1parse> as follows yields:
openssl asn1parse -in pca-cert.pem
0:d=0 hl=4 l= 742 cons: SEQUENCE
4:d=1 hl=4 l= 591 cons: SEQUENCE
8:d=2 hl=2 l= 3 cons: cont [ 0 ]
10:d=3 hl=2 l= 1 prim: INTEGER :02
13:d=2 hl=2 l= 1 prim: INTEGER :00
16:d=2 hl=2 l= 13 cons: SEQUENCE
18:d=3 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption
29:d=3 hl=2 l= 0 prim: NULL
31:d=2 hl=2 l= 92 cons: SEQUENCE
33:d=3 hl=2 l= 11 cons: SET
35:d=4 hl=2 l= 9 cons: SEQUENCE
37:d=5 hl=2 l= 3 prim: OBJECT :countryName
42:d=5 hl=2 l= 2 prim: PRINTABLESTRING :AU
....
599:d=1 hl=2 l= 13 cons: SEQUENCE
601:d=2 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption
612:d=2 hl=2 l= 0 prim: NULL
614:d=1 hl=3 l= 129 prim: BIT STRING
The final BIT STRING contains the actual signature. It can be extracted with:
openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614
The certificate public key can be extracted with:
openssl x509 -in test/testx509.pem -pubout -noout >pubkey.pem
The signature can be analysed with:
openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin
0:d=0 hl=2 l= 32 cons: SEQUENCE
2:d=1 hl=2 l= 12 cons: SEQUENCE
4:d=2 hl=2 l= 8 prim: OBJECT :md5
14:d=2 hl=2 l= 0 prim: NULL
16:d=1 hl=2 l= 16 prim: OCTET STRING
0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5 .F...Js.7...H%..
This is the parsed version of an ASN1 DigestInfo structure. It can be seen that
the digest used was md5. The actual part of the certificate that was signed can
be extracted with:
openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4
and its digest computed with:
openssl md5 -c tbs
MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5
which it can be seen agrees with the recovered value above.
=head1 SEE ALSO
L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>

9
crypto/dist/openssl/doc/apps/s_client.pod vendored
View File

@ -32,6 +32,7 @@ B<openssl> B<s_client>
[B<-no_tls1>]
[B<-bugs>]
[B<-cipher cipherlist>]
[B<-rand file(s)>]
=head1 DESCRIPTION
@ -156,6 +157,14 @@ the server determines which cipher suite is used it should take the first
supported cipher in the list sent by the client. See the B<ciphers>
command for more information.
=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
all others.
=back
=head1 CONNECTED COMMANDS

11
crypto/dist/openssl/doc/apps/s_server.pod vendored
View File

@ -39,6 +39,7 @@ B<openssl> B<s_client>
[B<-hack>]
[B<-www>]
[B<-WWW>]
[B<-rand file(s)>]
=head1 DESCRIPTION
@ -94,7 +95,7 @@ using a set of DH parameters. If not specified then an attempt is made to
load the parameters from the server certificate file. If this fails then
a static set of parameters hard coded into the s_server program will be used.
=item B<-nodhe>
=item B<-no_dhe>
if this option is set then no DH parameters will be loaded effectively
disabling the ephemeral DH cipher suites.
@ -186,6 +187,14 @@ emulates a simple web server. Pages will be resolved relative to the
current directory, for example if the URL https://myhost/page.html is
requested the file ./page.html will be loaded.
=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
all others.
=back
=head1 CONNECTED COMMANDS

57
crypto/dist/openssl/doc/apps/smime.pod vendored
View File

@ -22,8 +22,12 @@ B<openssl> B<smime>
[B<-signer file>]
[B<-recip file>]
[B<-in file>]
[B<-inform SMIME|PEM|DER>]
[B<-passin arg>]
[B<-inkey file>]
[B<-out file>]
[B<-outform SMIME|PEM|DER>]
[B<-content file>]
[B<-to addr>]
[B<-from ad>]
[B<-subject s>]
@ -74,11 +78,37 @@ takes an input message and writes out a PEM encoded PKCS#7 structure.
the input message to be encrypted or signed or the MIME message to
be decrypted or verified.
=item B<-inform SMIME|PEM|DER>
this specifies the input format for the PKCS#7 structure. The default
is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER>
format change this to expect PEM and DER format PKCS#7 structures
instead. This currently only affects the input format of the PKCS#7
structure, if no PKCS#7 structure is being input (for example with
B<-encrypt> or B<-sign>) this option has no effect.
=item B<-out filename>
the message text that has been decrypted or verified or the output MIME
format message that has been signed or verified.
=item B<-outform SMIME|PEM|DER>
this specifies the output format for the PKCS#7 structure. The default
is B<SMIME> which write an S/MIME format message. B<PEM> and B<DER>
format change this to write PEM and DER format PKCS#7 structures
instead. This currently only affects the output format of the PKCS#7
structure, if no PKCS#7 structure is being output (for example with
B<-verify> or B<-decrypt>) this option has no effect.
=item B<-content filename>
This specifies a file containing the detached content, this is only
useful with the B<-verify> command. This is only usable if the PKCS#7
structure is using the detached signature form where the content is
not included. This option will override any content if the input format
is S/MIME and it uses the multipart/signed MIME content type.
=item B<-text>
this option adds plain text (text/plain) MIME headers to the supplied
@ -174,12 +204,17 @@ corresponding certificate. If this option is not specified then the
private key must be included in the certificate file specified with
the B<-recip> or B<-signer> file.
=item B<-passin arg>
the private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=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 OpenVSM, and B<:> for
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<cert.pem...>
@ -204,7 +239,7 @@ a blank line. Piping the mail directly to sendmail is one way to
achieve the correct format.
The supplied message to be signed or encrypted must include the
necessary MIME headers: or many S/MIME clients wont display it
necessary MIME headers or many S/MIME clients wont display it
properly (if at all). You can use the B<-text> option to automatically
add plain text headers.
@ -290,7 +325,7 @@ Send encrypted mail using triple DES:
Sign and encrypt mail:
openssl smime -sign -in ml.txt -signer my.pem -text \
| openssl -encrypt -out mail.msg \
| openssl smime -encrypt -out mail.msg \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed and Encrypted message" -des3 user.pem
@ -301,6 +336,22 @@ Decrypt mail:
openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
The output from Netscape form signing is a PKCS#7 structure with the
detached signature format. You can use this program to verify the
signature by line wrapping the base64 encoded structure and surrounding
it with:
-----BEGIN PKCS7----
-----END PKCS7----
and using the command,
openssl smime -verify -inform PEM -in signature.pem -content content.txt
alternatively you can base64 decode the signature and use
openssl smime -verify -inform DER -in signature.der -content content.txt
=head1 BUGS
The MIME parser isn't very clever: it seems to handle most messages that I've thrown

2
crypto/dist/openssl/doc/apps/speed.pod vendored
View File

@ -39,7 +39,7 @@ This command is used to test the performance of cryptographic algorithms.
=head1 OPTIONS
If an option is given, B<speed> test that algorithm, otherwise all of
If any options are given, B<speed> tests those algorithms, otherwise all of
the above are tested.
=cut

63
crypto/dist/openssl/doc/apps/verify.pod vendored
View File

@ -2,7 +2,7 @@
=head1 NAME
pkcs7 - PKCS#7 utility
verify - Utility to verify certificates.
=head1 SYNOPSIS
@ -12,6 +12,7 @@ B<openssl> B<verify>
[B<-purpose purpose>]
[B<-untrusted file>]
[B<-help>]
[B<-issuer_checks>]
[B<-verbose>]
[B<->]
[certificates]
@ -57,6 +58,14 @@ prints out a usage message.
print extra information about the operations being performed.
=item B<-issuer_checks>
print out diagnostics relating to searches for the issuer certificate
of the current certificate. This shows why each candidate issuer
certificate was rejected. However the presence of rejection messages
does not itself imply that anything is wrong: during the normal
verify process several rejections may take place.
=item B<->
marks the last option. All arguments following this are assumed to be
@ -88,9 +97,21 @@ The verify operation consists of a number of separate steps.
Firstly a certificate chain is built up starting from the supplied certificate
and ending in the root CA. It is an error if the whole chain cannot be built
up. The chain is built up by looking up a certificate whose subject name
matches the issuer name of the current certificate. If a certificate is found
whose subject and issuer names are identical it is assumed to be the root CA.
up. The chain is built up by looking up the issuers certificate of the current
certificate. If a certificate is found which is its own issuer it is assumed
to be the root CA.
The process of 'looking up the issuers certificate' itself involves a number
of steps. In versions of OpenSSL before 0.9.5a the first certificate whose
subject name matched the issuer of the current certificate was assumed to be
the issuers certificate. In OpenSSL 0.9.6 and later all certificates
whose subject name matches the issuer name of the current certificate are
subject to further tests. The relevant authority key identifier components
of the current certificate (if present) must match the subject key identifier
(if present) and issuer and serial number of the candidate issuer, in addition
the keyUsage extension of the candidate issuer (if present) must permit
certificate signing.
The lookup first looks in the list of untrusted certificates and if no match
is found the remaining lookups are from the trusted certificates. The root CA
is always looked up in the trusted certificate list: if the certificate to
@ -260,12 +281,46 @@ the root CA is not marked as trusted for the specified purpose.
the root CA is marked to reject the specified purpose.
=item B<29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch>
the current candidate issuer certificate was rejected because its subject name
did not match the issuer name of the current certificate. Only displayed when
the B<-issuer_checks> option is set.
=item B<30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch>
the current candidate issuer certificate was rejected because its subject key
identifier was present and did not match the authority key identifier current
certificate. Only displayed when the B<-issuer_checks> option is set.
=item B<31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch>
the current candidate issuer certificate was rejected because its issuer name
and serial number was present and did not match the authority key identifier
of the current certificate. Only displayed when the B<-issuer_checks> option is set.
=item B<32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing>
the current candidate issuer certificate was rejected because its keyUsage extension
does not permit certificate signing.
=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
an application specific error. Unused.
=back
=head1 BUGS
Although the issuer checks are a considerably improvement over the old technique they still
suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that
trusted certificates with matching subject name must either appear in a file (as specified by the
B<-CAfile> option) or a directory (as specified by B<-CApath>. If they occur in both then only
the certificates in the file will be recognised.
Previous versions of OpenSSL assume certificates with matching subject name are identical and
mishandled them.
=head1 SEE ALSO
L<x509(1)|x509(1)>

176
crypto/dist/openssl/doc/apps/x509.pod vendored
View File

@ -19,6 +19,8 @@ B<openssl> B<x509>
[B<-hash>]
[B<-subject>]
[B<-issuer>]
[B<-nameopt option>]
[B<-email>]
[B<-startdate>]
[B<-enddate>]
[B<-purpose>]
@ -137,6 +139,16 @@ outputs the subject name.
outputs the issuer name.
=item B<-nameopt option>
option which determine how the subject or issuer names are displayed. This
option may be used more than once to set multiple options. See the B<NAME
OPTIONS> section for more information.
=item B<-email>
outputs the email address(es) if any.
=item B<-startdate>
prints out the start date of the certificate, that is the notBefore date.
@ -330,6 +342,138 @@ specified then the extensions should either be contained in the unnamed
=back
=head1 NAME OPTIONS
The B<nameopt> command line switch determines how the subject and issuer
names are displayed. If no B<nameopt> switch is present the default "oneline"
format is used which is compatible with previous versions of OpenSSL.
Each option is described in detail below, all options can be preceded by
a B<-> to turn the option off. Only the first four will normally be used.
=over 4
=item B<compat>
use the old format. This is equivalent to specifying no name options at all.
=item B<RFC2253>
displays names compatible with RFC2253 equivalent to B<esc_2253>, B<esc_ctrl>,
B<esc_msb>, B<utf8>, B<dump_nostr>, B<dump_unknown>, B<dump_der>,
B<sep_comma_plus>, B<dn_rev> and B<sname>.
=item B<oneline>
a oneline format which is more readable than RFC2253. It is equivalent to
specifying the B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>,
B<dump_der>, B<use_quote>, B<sep_comma_plus_spc>, B<spc_eq> and B<sname>
options.
=item B<multiline>
a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>,
B<spc_eq> and B<lname>.
=item B<esc_2253>
escape the "special" characters required by RFC2253 in a field That is
B<,+"E<lt>E<gt>;>. Additionally B<#> is escaped at the beginnging of a string
and a space character at the beginning or end of a string.
=item B<esc_ctrl>
escape control characters. That is those with ASCII values less than
0x20 (space) and the delete (0x7f) character. They are escaped using the
RFC2253 \XX notation (where XX are two hex digits representing the
character value).
=item B<esc_msb>
escape characters with the MSB set, that is with ASCII values larger than
127.
=item B<use_quote>
escapes some characters by surrounding the whole string with B<"> characters,
without the option all escaping is done with the B<\> character.
=item B<utf8>
convert all strings to UTF8 format first. This is required by RFC2253. If
you are lucky enough to have a UTF8 compatible terminal then the use
of this option (and B<not> setting B<esc_msb>) may result in the correct
display of multibyte (international) characters. Is this option is not
present then multibyte characters larger than 0xff will be represented
using the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits.
Also if this option is off any UTF8Strings will be converted to their
character form first.
=item B<no_type>
this option does not attempt to interpret multibyte characters in any
way. That is their content octets are merely dumped as though one octet
represents each character. This is useful for diagnostic purposes but
will result in rather odd looking output.
=item B<show_type>
show the type of the ASN1 character string. The type precedes the
field contents. For example "BMPSTRING: Hello World".
=item B<dump_der>
when this option is set any fields that need to be hexdumped will
be dumped using the DER encoding of the field. Otherwise just the
content octets will be displayed. Both options use the RFC2253
B<#XXXX...> format.
=item B<dump_nostr>
dump non character string types (for example OCTET STRING) if this
option is not set then non character string types will be displayed
as though each content octet repesents a single character.
=item B<dump_all>
dump all fields. This option when used with B<dump_der> allows the
DER encoding of the structure to be unambiguously determined.
=item B<dump_unknown>
dump any field whose OID is not recognised by OpenSSL.
=item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>,
B<sep_multiline>
these options determine the field separators. The first character is
between RDNs and the second between multiple AVAs (multiple AVAs are
very rare and their use is discouraged). The options ending in
"space" additionally place a space after the separator to make it
more readable. The B<sep_multiline> uses a linefeed character for
the RDN separator and a spaced B<+> for the AVA separator. It also
indents the fields by four characters.
=item B<dn_rev>
reverse the fields of the DN. This is required by RFC2253. As a side
effect this also reverses the order of multiple AVAs but this is
permissible.
=item B<nofname>, B<sname>, B<lname>, B<oid>
these options alter how the field name is displayed. B<nofname> does
not display the field at all. B<sname> uses the "short name" form
(CN for commonName for example). B<lname> uses the long form.
B<oid> represents the OID in numerical form and is useful for
diagnostic purpose.
=item B<spc_eq>
places spaces round the B<=> character which follows the field
name.
=back
=head1 EXAMPLES
Note: in these examples the '\' means the example should be all on one
@ -343,6 +487,19 @@ Display the certificate serial number:
openssl x509 -in cert.pem -noout -serial
Display the certificate subject name:
openssl x509 -in cert.pem -noout -subject
Display the certificate subject name in RFC2253 form:
openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
Display the certificate subject name in oneline form on a terminal
supporting UTF8:
openssl x509 -in cert.pem -noout -subject -nameopt oneline -nameopt -escmsb
Display the certificate MD5 fingerprint:
openssl x509 -in cert.pem -noout -fingerprint
@ -362,13 +519,13 @@ Convert a certificate to a certificate request:
Convert a certificate request into a self signed certificate using
extensions for a CA:
openssl x509 -req -in careq.pem -config openssl.cnf -extensions v3_ca \
openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
-signkey key.pem -out cacert.pem
Sign a certificate request using the CA certificate above and add user
certificate extensions:
openssl x509 -req -in req.pem -config openssl.cnf -extensions v3_usr \
openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
-CA cacert.pem -CAkey key.pem -CAcreateserial
@ -395,6 +552,11 @@ Trusted certificates have the lines
-----BEGIN TRUSTED CERTIFICATE----
-----END TRUSTED CERTIFICATE----
The conversion to UTF8 format used with the name options assumes that
T61Strings use the ISO8859-1 character set. This is wrong but Netscape
and MSIE do this as do many certificates. So although this is incorrect
it is more likely to display the majority of certificates correctly.
The B<-fingerprint> option takes the digest of the DER encoded certificate.
This is commonly called a "fingerprint". Because of the nature of message
digests the fingerprint of a certificate is unique to that certificate and
@ -402,6 +564,10 @@ two certificates with the same fingerprint can be considered to be the same.
The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
The B<-email> option searches the subject name and the subject alternative
name extension. Only unique email addresses will be printed out: it will
not print the same address more than once.
=head1 CERTIFICATE EXTENSIONS
The B<-purpose> option checks the certificate extensions and determines
@ -517,10 +683,6 @@ must be present.
=head1 BUGS
The way DNs are printed is in a "historical SSLeay" format which doesn't
follow any published standard. It should follow some standard like RFC2253
or RFC1779 with options to make the stuff more readable.
Extensions in certificates are not transferred to certificate requests and
vice versa.
@ -532,7 +694,7 @@ There should be options to explicitly set such things as start and end
dates rather than an offset from the current time.
The code to implement the verify behaviour described in the B<TRUST SETTINGS>
is currently being developed. It thus describes the intended behavior rather
is currently being developed. It thus describes the intended behaviour rather
than the current behaviour. It is hoped that it will represent reality in
OpenSSL 0.9.5 and later.

128
crypto/dist/openssl/doc/crypto/BIO_ctrl.pod vendored Normal file
View File

@ -0,0 +1,128 @@
=pod
=head1 NAME
BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
BIO_get_info_callback, BIO_set_info_callback - BIO control operations
=head1 SYNOPSIS
#include <openssl/bio.h>
long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg);
long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long));
char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg);
long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg);
int BIO_reset(BIO *b);
int BIO_seek(BIO *b, int ofs);
int BIO_tell(BIO *b);
int BIO_flush(BIO *b);
int BIO_eof(BIO *b);
int BIO_set_close(BIO *b,long flag);
int BIO_get_close(BIO *b);
int BIO_pending(BIO *b);
int BIO_wpending(BIO *b);
size_t BIO_ctrl_pending(BIO *b);
size_t BIO_ctrl_wpending(BIO *b);
int BIO_get_info_callback(BIO *b,bio_info_cb **cbp);
int BIO_set_info_callback(BIO *b,bio_info_cb *cb);
typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
=head1 DESCRIPTION
BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl()
are BIO "control" operations taking arguments of various types.
These functions are not normally called directly, various macros
are used instead. The standard macros are described below, macros
specific to a particular type of BIO are described in the specific
BIOs manual page as well as any special features of the standard
calls.
BIO_reset() typically resets a BIO to some initial state, in the case
of file related BIOs for example it rewinds the file pointer to the
start of the file.
BIO_seek() resets a file related BIO's (that is file descriptor and
FILE BIOs) file position pointer to B<ofs> bytes from start of file.
BIO_tell() returns the current file position of a file related BIO.
BIO_flush() normally writes out any internally buffered data, in some
cases it is used to signal EOF and that no more data will be written.
BIO_eof() returns 1 if the BIO has read EOF, the precise meaning of
"EOF" varies according to the BIO type.
BIO_set_close() sets the BIO B<b> close flag to B<flag>. B<flag> can
take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used
in a source/sink BIO to indicate that the underlying I/O stream should
be closed when the BIO is freed.
BIO_get_close() returns the BIOs close flag.
BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
return the number of pending characters in the BIOs read and write buffers.
Not all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending()
return a size_t type and are functions, BIO_pending() and BIO_wpending() are
macros which call BIO_ctrl().
=head1 RETURN VALUES
BIO_reset() normally returns 1 for success and 0 or -1 for failure. File
BIOs are an exception, they return 0 for success and -1 for failure.
BIO_seek() and BIO_tell() both return the current file position on success
and -1 for failure, except file BIOs which for BIO_seek() always return 0
for success and -1 for failure.
BIO_flush() returns 1 for success and 0 or -1 for failure.
BIO_eof() returns 1 if EOF has been reached 0 otherwise.
BIO_set_close() always returns 1.
BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE.
BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
return the amount of pending data.
=head1 NOTES
BIO_flush(), because it can write data may return 0 or -1 indicating
that the call should be retried later in a similar manner to BIO_write().
The BIO_should_retry() call should be used and appropriate action taken
is the call fails.
The return values of BIO_pending() and BIO_wpending() may not reliably
determine the amount of pending data in all cases. For example in the
case of a file BIO some data may be available in the FILE structures
internal buffers but it is not possible to determine this in a
portably way. For other types of BIO they may not be supported.
Filter BIOs if they do not internally handle a particular BIO_ctrl()
operation usually pass the operation to the next BIO in the chain.
This often means there is no need to locate the required BIO for
a particular operation, it can be called on a chain and it will
be automatically passed to the relevant BIO. However this can cause
unexpected results: for example no current filter BIOs implement
BIO_seek(), but this may still succeed if the chain ends in a FILE
or file descriptor BIO.
Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl()
operation.
=head1 BUGS
Some of the return values are ambiguous and care should be taken. In
particular a return value of 0 can be returned if an operation is not
supported, if an error occurred, if EOF has not been reached and in
the case of BIO_seek() on a file BIO for a successful operation.
=head1 SEE ALSO
TBA

82
crypto/dist/openssl/doc/crypto/BIO_f_base64.pod vendored Normal file
View File

@ -0,0 +1,82 @@
=pod
=head1 NAME
BIO_f_base64 - base64 BIO filter
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>
BIO_METHOD * BIO_f_base64(void);
=head1 DESCRIPTION
BIO_f_base64() returns the base64 BIO method. This is a filter
BIO that base64 encodes any data written through it and decodes
any data read through it.
Base64 BIOs do not support BIO_gets() or BIO_puts().
BIO_flush() on a base64 BIO that is being written through is
used to signal that no more data is to be encoded: this is used
to flush the final block through the BIO.
The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags()
to encode the data all on one line or expect the data to be all
on one line.
=head1 NOTES
Because of the format of base64 encoding the end of the encoded
block cannot always be reliably determined.
=head1 RETURN VALUES
BIO_f_base64() returns the base64 BIO method.
=head1 EXAMPLES
Base64 encode the string "Hello World\n" and write the result
to standard output:
BIO *bio, *b64;
char message[] = "Hello World \n";
b64 = BIO_new(BIO_f_base64());
bio = BIO_new_fp(stdout, BIO_NOCLOSE);
bio = BIO_push(b64, bio);
BIO_write(bio, message, strlen(message));
BIO_flush(bio);
BIO_free_all(bio);
Read Base64 encoded data from standard input and write the decoded
data to standard output:
BIO *bio, *b64, bio_out;
char inbuf[512];
int inlen;
char message[] = "Hello World \n";
b64 = BIO_new(BIO_f_base64());
bio = BIO_new_fp(stdin, BIO_NOCLOSE);
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
bio = BIO_push(b64, bio);
while((inlen = BIO_read(bio, inbuf, strlen(message))) > 0)
BIO_write(bio_out, inbuf, inlen);
BIO_free_all(bio);
=head1 BUGS
The ambiguity of EOF in base64 encoded data can cause additional
data following the base64 encoded block to be misinterpreted.
There should be some way of specifying a test that the BIO can perform
to reliably determine EOF (for example a MIME boundary).
=head1 SEE ALSO
TBA

69
crypto/dist/openssl/doc/crypto/BIO_f_buffer.pod vendored Normal file
View File

@ -0,0 +1,69 @@
=pod
=head1 NAME
BIO_f_buffer - buffering BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_f_buffer(void);
#define BIO_get_buffer_num_lines(b) BIO_ctrl(b,BIO_C_GET_BUFF_NUM_LINES,0,NULL)
#define BIO_set_read_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,0)
#define BIO_set_write_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,1)
#define BIO_set_buffer_size(b,size) BIO_ctrl(b,BIO_C_SET_BUFF_SIZE,size,NULL)
#define BIO_set_buffer_read_data(b,buf,num) BIO_ctrl(b,BIO_C_SET_BUFF_READ_DATA,num,buf)
=head1 DESCRIPTION
BIO_f_buffer() returns the buffering BIO method.
Data written to a buffering BIO is buffered and periodically written
to the next BIO in the chain. Data read from a buffering BIO comes from
an internal buffer which is filled from the next BIO in the chain.
Both BIO_gets() and BIO_puts() are supported.
Calling BIO_reset() on a buffering BIO clears any buffered data.
BIO_get_buffer_num_lines() returns the number of lines currently buffered.
BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()
set the read, write or both read and write buffer sizes to B<size>. The initial
buffer size is DEFAULT_BUFFER_SIZE, currently 1024. Any attempt to reduce the
buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared
when the buffer is resized.
BIO_set_buffer_read_data() clears the read buffer and fills it with B<num>
bytes of B<buf>. If B<num> is larger than the current buffer size the buffer
is expanded.
=head1 NOTES
Buffering BIOs implement BIO_gets() by using BIO_read() operations on the
next BIO in the chain. By prepending a buffering BIO to a chain it is therefore
possible to provide BIO_gets() functionality if the following BIOs do not
support it (for example SSL BIOs).
Data is only written to the next BIO in the chain when the write buffer fills
or when BIO_flush() is called. It is therefore important to call BIO_flush()
whenever any pending data should be written such as when removing a buffering
BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate
source/sink BIO is non blocking.
=head1 RETURN VALUES
BIO_f_buffer() returns the buffering BIO method.
BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0).
BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()
return 1 if the buffer was successfully resized or 0 for failure.
BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if
there was an error.
=head1 SEE ALSO
TBA

76
crypto/dist/openssl/doc/crypto/BIO_f_cipher.pod vendored Normal file
View File

@ -0,0 +1,76 @@
=pod
=head1 NAME
BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>
BIO_METHOD * BIO_f_cipher(void);
void BIO_set_cipher(BIO *b,const EVP_CIPHER *cipher,
unsigned char *key, unsigned char *iv, int enc);
int BIO_get_cipher_status(BIO *b)
int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx)
=head1 DESCRIPTION
BIO_f_cipher() returns the cipher BIO method. This is a filter
BIO that encrypts any data written through it, and decrypts any data
read from it. It is a BIO wrapper for the cipher routines
EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal().
Cipher BIOs do not support BIO_gets() or BIO_puts().
BIO_flush() on an encryption BIO that is being written through is
used to signal that no more data is to be encrypted: this is used
to flush and possibly pad the final block through the BIO.
BIO_set_cipher() sets the cipher of BIO <b> to B<cipher> using key B<key>
and IV B<iv>. B<enc> should be set to 1 for encryption and zero for
decryption.
When reading from an encryption BIO the final block is automatically
decrypted and checked when EOF is detected. BIO_get_cipher_status()
is a BIO_ctrl() macro which can be called to determine whether the
decryption operation was successful.
BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal
BIO cipher context. The retrieved context can be used in conjunction
with the standard cipher routines to set it up. This is useful when
BIO_set_cipher() is not flexible enough for the applications needs.
=head1 NOTES
When encrypting BIO_flush() B<must> be called to flush the final block
through the BIO. If it is not then the final block will fail a subsequent
decrypt.
When decrypting an error on the final block is signalled by a zero
return value from the read operation. A successful decrypt followed
by EOF will also return zero for the final read. BIO_get_cipher_status()
should be called to determine if the decrypt was successful.
As always, if BIO_gets() or BIO_puts() support is needed then it can
be achieved by preceding the cipher BIO with a buffering BIO.
=head1 RETURN VALUES
BIO_f_cipher() returns the cipher BIO method.
BIO_set_cipher() does not return a value.
BIO_get_cipher_status() returns 1 for a successful decrypt and 0
for failure.
BIO_get_cipher_ctx() currently always returns 1.
=head1 EXAMPLES
TBA
=head1 SEE ALSO
TBA

138
crypto/dist/openssl/doc/crypto/BIO_f_md.pod vendored Normal file
View File

@ -0,0 +1,138 @@
=pod
=head1 NAME
BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>
BIO_METHOD * BIO_f_md(void);
int BIO_set_md(BIO *b,EVP_MD *md);
int BIO_get_md(BIO *b,EVP_MD **mdp);
int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp);
=head1 DESCRIPTION
BIO_f_md() returns the message digest BIO method. This is a filter
BIO that digests any data passed through it, it is a BIO wrapper
for the digest routines EVP_DigestInit(), EVP_DigestUpdate()
and EVP_DigestFinal().
Any data written or read through a digest BIO using BIO_read() and
BIO_write() is digested.
BIO_gets(), if its B<size> parameter is large enough finishes the
digest calculation and returns the digest value. BIO_puts() is
not supported.
BIO_reset() reinitializes a digest BIO.
BIO_set_md() sets the message digest of BIO B<b> to B<md>: this
must be called to initialize a digest BIO before any data is
passed through it. It is a BIO_ctrl() macro.
BIO_get_md() places the a pointer to the digest BIOs digest method
in B<mdp>, it is a BIO_ctrl() macro.
BIO_get_md_ctx() returns the digest BIOs context into B<mdcp>.
=head1 NOTES
The context returned by BIO_get_md_ctx() can be used in calls
to EVP_DigestFinal() and also the signature routines EVP_SignFinal()
and EVP_VerifyFinal().
The context returned by BIO_get_md_ctx() is an internal context
structure. Changes made to this context will affect the digest
BIO itself and the context pointer will become invalid when the digest
BIO is freed.
After the digest has been retrieved from a digest BIO it must be
reinitialized by calling BIO_reset(), or BIO_set_md() before any more
data is passed through it.
If an application needs to call BIO_gets() or BIO_puts() through
a chain containing digest BIOs then this can be done by prepending
a buffering BIO.
=head1 RETURN VALUES
BIO_f_md() returns the digest BIO method.
BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and
0 for failure.
=head1 EXAMPLES
The following example creates a BIO chain containing an SHA1 and MD5
digest BIO and passes the string "Hello World" through it. Error
checking has been omitted for clarity.
BIO *bio, *mdtmp;
char message[] = "Hello World";
bio = BIO_new(BIO_s_null());
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_sha1());
/* For BIO_push() we want to append the sink BIO and keep a note of
* the start of the chain.
*/
bio = BIO_push(mdtmp, bio);
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_md5());
bio = BIO_push(mdtmp, bio);
/* Note: mdtmp can now be discarded */
BIO_write(bio, message, strlen(message));
The next example digests data by reading through a chain instead:
BIO *bio, *mdtmp;
char buf[1024];
int rdlen;
bio = BIO_new_file(file, "rb");
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_sha1());
bio = BIO_push(mdtmp, bio);
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_md5());
bio = BIO_push(mdtmp, bio);
do {
rdlen = BIO_read(bio, buf, sizeof(buf));
/* Might want to do something with the data here */
} while(rdlen > 0);
This next example retrieves the message digests from a BIO chain and
outputs them. This could be used with the examples above.
BIO *mdtmp;
unsigned char mdbuf[EVP_MAX_MD_SIZE];
int mdlen;
int i;
mdtmp = bio; /* Assume bio has previously been set up */
do {
EVP_MD *md;
mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
if(!mdtmp) break;
BIO_get_md(mdtmp, &md);
printf("%s digest", OBJ_nid2sn(EVP_MD_type(md)));
mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
printf("\n");
mdtmp = BIO_next(mdtmp);
} while(mdtmp);
BIO_free_all(bio);
=head1 BUGS
The lack of support for BIO_puts() and the non standard behaviour of
BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets()
and BIO_puts() should be passed to the next BIO in the chain and digest
the data passed through and that digests should be retrieved using a
separate BIO_ctrl() call.
=head1 SEE ALSO
TBA

32
crypto/dist/openssl/doc/crypto/BIO_f_null.pod vendored Normal file
View File

@ -0,0 +1,32 @@
=pod
=head1 NAME
BIO_f_null - null filter
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_f_null(void);
=head1 DESCRIPTION
BIO_f_null() returns the null filter BIO method. This is a filter BIO
that does nothing.
All requests to a null filter BIO are passed through to the next BIO in
the chain: this means that a BIO chain containing a null filter BIO
behaves just as though the BIO was not there.
=head1 NOTES
As may be apparent a null filter BIO is not particularly useful.
=head1 RETURN VALUES
BIO_f_null() returns the null filter BIO method.
=head1 SEE ALSO
TBA

313
crypto/dist/openssl/doc/crypto/BIO_f_ssl.pod vendored Normal file
View File

@ -0,0 +1,313 @@
=pod
=head1 NAME
BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes,
BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl,
BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id,
BIO_ssl_shutdown - SSL BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/ssl.h>
BIO_METHOD *BIO_f_ssl(void);
#define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl)
#define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp)
#define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL)
#define BIO_set_ssl_renegotiate_bytes(b,num) \
BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL);
#define BIO_set_ssl_renegotiate_timeout(b,seconds) \
BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL);
#define BIO_get_num_renegotiates(b) \
BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL);
BIO *BIO_new_ssl(SSL_CTX *ctx,int client);
BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
int BIO_ssl_copy_session_id(BIO *to,BIO *from);
void BIO_ssl_shutdown(BIO *bio);
#define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)
=head1 DESCRIPTION
BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which
is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to
SSL I/O.
I/O performed on an SSL BIO communicates using the SSL protocol with
the SSLs read and write BIOs. If an SSL connection is not established
then an attempt is made to establish one on the first I/O call.
If a BIO is appended to an SSL BIO using BIO_push() it is automatically
used as the SSL BIOs read and write BIOs.
Calling BIO_reset() on an SSL BIO closes down any current SSL connection
by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in
the chain: this will typically disconnect the underlying transport.
The SSL BIO is then reset to the initial accept or connect state.
If the close flag is set when an SSL BIO is freed then the internal
SSL structure is also freed using SSL_free().
BIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using
the close flag B<c>.
BIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be
manipulated using the standard SSL library functions.
BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client>
is 1 client mode is set. If B<client> is 0 server mode is set.
BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count
to B<num>. When set after every B<num> bytes of I/O (read and write)
the SSL session is automatically renegotiated. B<num> must be at
least 512 bytes.
BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to
B<seconds>. When the renegotiate timeout elapses the session is
automatically renegotiated.
BIO_get_num_renegotiates() returns the total number of session
renegotiations due to I/O or timeout.
BIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using
client mode if B<client> is non zero.
BIO_new_ssl_connect() creates a new BIO chain consisting of an
SSL BIO (using B<ctx>) followed by a connect BIO.
BIO_new_buffer_ssl_connect() creates a new BIO chain consisting
of a buffering BIO, an SSL BIO (using B<ctx>) and a connect
BIO.
BIO_ssl_copy_session_id() copies an SSL session id between
BIO chains B<from> and B<to>. It does this by locating the
SSL BIOs in each chain and calling SSL_copy_session_id() on
the internal SSL pointer.
BIO_ssl_shutdown() closes down an SSL connection on BIO
chain B<bio>. It does this by locating the SSL BIO in the
chain and calling SSL_shutdown() on its internal SSL
pointer.
BIO_do_handshake() attempts to complete an SSL handshake on the
supplied BIO and establish the SSL connection. It returns 1
if the connection was established successfully. A zero or negative
value is returned if the connection could not be established, the
call BIO_should_retry() should be used for non blocking connect BIOs
to determine if the call should be retried. If an SSL connection has
already been established this call has no effect.
=head1 NOTES
SSL BIOs are exceptional in that if the underlying transport
is non blocking they can still request a retry in exceptional
circumstances. Specifically this will happen if a session
renegotiation takes place during a BIO_read() operation, one
case where this happens is when SGC or step up occurs.
In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be
set to disable this behaviour. That is when this flag is set
an SSL BIO using a blocking transport will never request a
retry.
Since unknown BIO_ctrl() operations are sent through filter
BIOs the servers name and port can be set using BIO_set_host()
on the BIO returned by BIO_new_ssl_connect() without having
to locate the connect BIO first.
Applications do not have to call BIO_do_handshake() but may wish
to do so to separate the handshake process from other I/O
processing.
=head1 RETURN VALUES
TBA
=head1 EXAMPLE
This SSL/TLS client example, attempts to retrieve a page from an
SSL/TLS web server. The I/O routines are identical to those of the
unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>.
BIO *sbio, *out;
int len;
char tmpbuf[1024];
SSL_CTX *ctx;
SSL *ssl;
ERR_load_crypto_strings();
ERR_load_SSL_strings();
OpenSSL_add_all_algorithms();
/* We would seed the PRNG here if the platform didn't
* do it automatically
*/
ctx = SSL_CTX_new(SSLv23_client_method());
/* We'd normally set some stuff like the verify paths and
* mode here because as things stand this will connect to
* any server whose certificate is signed by any CA.
*/
sbio = BIO_new_ssl_connect(ctx);
BIO_get_ssl(sbio, &ssl);
if(!ssl) {
fprintf(stderr, "Can't locate SSL pointer\n");
/* whatever ... */
}
/* Don't want any retries */
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
/* We might want to do other things with ssl here */
BIO_set_conn_hostname(sbio, "localhost:https");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
if(BIO_do_connect(sbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
}
if(BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error establishing SSL connection\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
}
/* Could examine ssl here to get connection info */
BIO_puts(sbio, "GET / HTTP/1.0\n\n");
for(;;) {
len = BIO_read(sbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(out, tmpbuf, len);
}
BIO_free_all(sbio);
BIO_free(out);
Here is a simple server example. It makes use of a buffering
BIO to allow lines to be read from the SSL BIO using BIO_gets.
It creates a pseudo web page containing the actual request from
a client and also echoes the request to standard output.
BIO *sbio, *bbio, *acpt, *out;
int len;
char tmpbuf[1024];
SSL_CTX *ctx;
SSL *ssl;
ERR_load_crypto_strings();
ERR_load_SSL_strings();
OpenSSL_add_all_algorithms();
/* Might seed PRNG here */
ctx = SSL_CTX_new(SSLv23_server_method());
if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM)
|| !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM)
|| !SSL_CTX_check_private_key(ctx)) {
fprintf(stderr, "Error setting up SSL_CTX\n");
ERR_print_errors_fp(stderr);
return 0;
}
/* Might do other things here like setting verify locations and
* DH and/or RSA temporary key callbacks
*/
/* New SSL BIO setup as server */
sbio=BIO_new_ssl(ctx,0);
BIO_get_ssl(sbio, &ssl);
if(!ssl) {
fprintf(stderr, "Can't locate SSL pointer\n");
/* whatever ... */
}
/* Don't want any retries */
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
/* Create the buffering BIO */
bbio = BIO_new(BIO_f_buffer());
/* Add to chain */
sbio = BIO_push(bbio, sbio);
acpt=BIO_new_accept("4433");
/* By doing this when a new connection is established
* we automatically have sbio inserted into it. The
* BIO chain is now 'swallowed' by the accept BIO and
* will be freed when the accept BIO is freed.
*/
BIO_set_accept_bios(acpt,sbio);
out = BIO_new_fp(stdout, BIO_NOCLOSE);
/* Setup accept BIO */
if(BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error setting up accept BIO\n");
ERR_print_errors_fp(stderr);
return 0;
}
/* Now wait for incoming connection */
if(BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error in connection\n");
ERR_print_errors_fp(stderr);
return 0;
}
/* We only want one connection so remove and free
* accept BIO
*/
sbio = BIO_pop(acpt);
BIO_free_all(acpt);
if(BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error in SSL handshake\n");
ERR_print_errors_fp(stderr);
return 0;
}
BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/html\r\n\r\n");
BIO_puts(sbio, "<pre>\r\nConnection Established\r\nRequest headers:\r\n");
BIO_puts(sbio, "--------------------------------------------------\r\n");
for(;;) {
len = BIO_gets(sbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(sbio, tmpbuf, len);
BIO_write(out, tmpbuf, len);
/* Look for blank line signifying end of headers*/
if((tmpbuf[0] == '\r') || (tmpbuf[0] == '\n')) break;
}
BIO_puts(sbio, "--------------------------------------------------\r\n");
BIO_puts(sbio, "</pre>\r\n");
/* Since there is a buffering BIO present we had better flush it */
BIO_flush(sbio);
BIO_free_all(sbio);
=head1 SEE ALSO
TBA

98
crypto/dist/openssl/doc/crypto/BIO_find_type.pod vendored Normal file
View File

@ -0,0 +1,98 @@
=pod
=head1 NAME
BIO_find_type, BIO_next - BIO chain traversal
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO * BIO_find_type(BIO *b,int bio_type);
BIO * BIO_next(BIO *b);
#define BIO_method_type(b) ((b)->method->type)
#define BIO_TYPE_NONE 0
#define BIO_TYPE_MEM (1|0x0400)
#define BIO_TYPE_FILE (2|0x0400)
#define BIO_TYPE_FD (4|0x0400|0x0100)
#define BIO_TYPE_SOCKET (5|0x0400|0x0100)
#define BIO_TYPE_NULL (6|0x0400)
#define BIO_TYPE_SSL (7|0x0200)
#define BIO_TYPE_MD (8|0x0200)
#define BIO_TYPE_BUFFER (9|0x0200)
#define BIO_TYPE_CIPHER (10|0x0200)
#define BIO_TYPE_BASE64 (11|0x0200)
#define BIO_TYPE_CONNECT (12|0x0400|0x0100)
#define BIO_TYPE_ACCEPT (13|0x0400|0x0100)
#define BIO_TYPE_PROXY_CLIENT (14|0x0200)
#define BIO_TYPE_PROXY_SERVER (15|0x0200)
#define BIO_TYPE_NBIO_TEST (16|0x0200)
#define BIO_TYPE_NULL_FILTER (17|0x0200)
#define BIO_TYPE_BER (18|0x0200)
#define BIO_TYPE_BIO (19|0x0400)
#define BIO_TYPE_DESCRIPTOR 0x0100
#define BIO_TYPE_FILTER 0x0200
#define BIO_TYPE_SOURCE_SINK 0x0400
=head1 DESCRIPTION
The BIO_find_type() searches for a BIO of a given type in a chain, starting
at BIO B<b>. If B<type> is a specific type (such as BIO_TYPE_MEM) then a search
is made for a BIO of that type. If B<type> is a general type (such as
B<BIO_TYPE_SOURCE_SINK>) then the next matching BIO of the given general type is
searched for. BIO_find_type() returns the next matching BIO or NULL if none is
found.
Note: not all the B<BIO_TYPE_*> types above have corresponding BIO implementations.
BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs
in a chain or used in conjunction with BIO_find_type() to find all BIOs of a
certain type.
BIO_method_type() returns the type of a BIO.
=head1 RETURN VALUES
BIO_find_type() returns a matching BIO or NULL for no match.
BIO_next() returns the next BIO in a chain.
BIO_method_type() returns the type of the BIO B<b>.
=head1 NOTES
BIO_next() was added to OpenSSL 0.9.6 to provide a 'clean' way to traverse a BIO
chain or find multiple matches using BIO_find_type(). Previous versions had to
use:
next = bio->next_bio;
=head1 BUGS
BIO_find_type() in OpenSSL 0.9.5a and earlier could not be safely passed a
NULL pointer for the B<b> argument.
=head1 EXAMPLE
Traverse a chain looking for digest BIOs:
BIO *btmp;
btmp = in_bio; /* in_bio is chain to search through */
do {
btmp = BIO_find_type(btmp, BIO_TYPE_MD);
if(btmp == NULL) break; /* Not found */
/* btmp is a digest BIO, do something with it ...*/
...
btmp = BIO_next(btmp);
} while(btmp);
=head1 SEE ALSO
TBA

65
crypto/dist/openssl/doc/crypto/BIO_new.pod vendored Normal file
View File

@ -0,0 +1,65 @@
=pod
=head1 NAME
BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO * BIO_new(BIO_METHOD *type);
int BIO_set(BIO *a,BIO_METHOD *type);
int BIO_free(BIO *a);
void BIO_vfree(BIO *a);
void BIO_free_all(BIO *a);
=head1 DESCRIPTION
The BIO_new() function returns a new BIO using method B<type>.
BIO_set() sets the method of an already existing BIO.
BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO
but it does not return a value. Calling BIO_free() may also have some effect
on the underlying I/O structure, for example it may close the file being
referred to under certain circumstances. For more details see the individual
BIO_METHOD descriptions.
BIO_free_all() frees up an entire BIO chain, it does not halt if an error
occurs freeing up an individual BIO in the chain.
=head1 RETURN VALUES
BIO_new() returns a newly created BIO or NULL if the call fails.
BIO_set(), BIO_free() return 1 for success and 0 for failure.
BIO_free_all() and BIO_vfree() do not return values.
=head1 NOTES
Some BIOs (such as memory BIOs) can be used immediately after calling
BIO_new(). Others (such as file BIOs) need some additional initialization,
and frequently a utility function exists to create and initialize such BIOs.
If BIO_free() is called on a BIO chain it will only free one BIO resulting
in a memory leak.
Calling BIO_free_all() a single BIO has the same effect as calling BIO_free()
on it other than the discarded return value.
Normally the B<type> argument is supplied by a function which returns a
pointer to a BIO_METHOD. There is a naming convention for such functions:
a source/sink BIO is normally called BIO_s_*() and a filter BIO
BIO_f_*();
=head1 EXAMPLE
Create a memory BIO:
BIO *mem = BIO_new(BIO_s_mem());
=head1 SEE ALSO
TBA

102
crypto/dist/openssl/doc/crypto/BIO_new_bio_pair.pod vendored Normal file
View File

@ -0,0 +1,102 @@
=pod
=head1 NAME
BIO_new_bio_pair - create a new BIO pair
=head1 SYNOPSIS
#include <openssl/bio.h>
int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
=head1 DESCRIPTION
BIO_new_bio_pair() creates a buffering BIO pair. It has two endpoints between
data can be buffered. Its typical use is to connect one endpoint as underlying
input/output BIO to an SSL and access the other one controlled by the program
instead of accessing the network connection directly.
The two new BIOs B<bio1> and B<bio2> are symmetric with respect to their
functionality. The size of their buffers is determined by B<writebuf1> and
B<writebuf2>. If the size give is 0, the default size is used.
BIO_new_bio_pair() does not check whether B<bio1> or B<bio2> do point to
some other BIO, the values are overwritten, BIO_free() is not called.
The two BIOs, even though forming a BIO pair and must be BIO_free()'ed
separately. This can be of importance, as some SSL-functions like SSL_set_bio()
or SSL_free() call BIO_free() implicitly, so that the peer-BIO is left
untouched and must also be BIO_free()'ed.
=head1 EXAMPLE
The BIO pair can be used to have full control over the network access of an
application. The application can call select() on the socket as required
without having to go through the SSL-interface.
BIO *internal_bio, *network_bio;
...
BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
SSL_set_bio(ssl, internal_bio);
SSL_operations();
...
application | TLS-engine
| |
+----------> SSL_operations()
| /\ ||
| || \/
| BIO-pair (internal_bio)
+----------< BIO-pair (network_bio)
| |
socket |
...
SSL_free(ssl); /* implicitly frees internal_bio */
BIO_free(network_bio);
...
As the BIO pair will only buffer the data and never directly access the
connection, it behaves non-blocking and will return as soon as the write
buffer is full or the read buffer is drained. Then the application has to
flush the write buffer and/or fill the read buffer.
Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO
and must be transfered to the network. Use BIO_ctrl_get_read_request() to
find out, how many bytes must be written into the buffer before the
SSL_operation() can successfully be continued.
=head1 IMPORTANT
As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ
condition, but there is still data in the write buffer. An application must
not rely on the error value of SSL_operation() but must assure that the
write buffer is always flushed first. Otherwise a deadlock may occur as
the peer might be waiting for the data before being able to continue.
=head1 RETURN VALUES
The following return values can occur:
=over 4
=item 1
The BIO pair was created successfully. The new BIOs are available in
B<bio1> and B<bio2>.
=item 0
The operation failed. The NULL pointer is stored into the locations for
B<bio1> and B<bio2>. Check the error stack for more information.
=back
=head1 SEE ALSO
L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
L<BIO_ctrl_pending(3)|BIO_ctrl_pending(3)>,
L<BIO_ctrl_get_read_request(3)|BIO_ctrl_get_read_request(3)>
=cut

69
crypto/dist/openssl/doc/crypto/BIO_push.pod vendored Normal file
View File

@ -0,0 +1,69 @@
=pod
=head1 NAME
BIO_push, BIO_pop - add and remove BIOs from a chain.
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO * BIO_push(BIO *b,BIO *append);
BIO * BIO_pop(BIO *b);
=head1 DESCRIPTION
The BIO_push() function appends the BIO B<append> to B<b>, it returns
B<b>.
BIO_pop() removes the BIO B<b> from a chain and returns the next BIO
in the chain, or NULL if there is no next BIO. The removed BIO then
becomes a single BIO with no association with the original chain,
it can thus be freed or attached to a different chain.
=head1 NOTES
The names of these functions are perhaps a little misleading. BIO_push()
joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain,
the deleted BIO does not need to be at the end of a chain.
The process of calling BIO_push() and BIO_pop() on a BIO may have additional
consequences (a control call is made to the affected BIOs) any effects will
be noted in the descriptions of individual BIOs.
=head1 EXAMPLES
For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
a base64 BIO and B<f> is a file BIO.
If the call:
BIO_push(b64, f);
is made then the new chain will be B<b64-chain>. After making the calls
BIO_push(md2, b64);
BIO_push(md1, md2);
the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested
by B<md1> and B<md2>, B<base64> encoded and written to B<f>.
It should be noted that reading causes data to pass in the reverse
direction, that is data is read from B<f>, base64 B<decoded> and digested
by B<md1> and B<md2>. If the call:
BIO_pop(md2);
The call will return B<b64> and the new chain will be B<md1-b64-f> data can
be written to B<md1> as before.
=head1 RETURN VALUES
BIO_push() returns the end of the chain, B<b>.
BIO_pop() returns the next BIO in the chain, or NULL if there is no next
BIO.
=head1 SEE ALSO
TBA

66
crypto/dist/openssl/doc/crypto/BIO_read.pod vendored Normal file
View File

@ -0,0 +1,66 @@
=pod
=head1 NAME
BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions
=head1 SYNOPSIS
#include <openssl/bio.h>
int BIO_read(BIO *b, void *buf, int len);
int BIO_gets(BIO *b,char *buf, int size);
int BIO_write(BIO *b, const void *buf, int len);
int BIO_puts(BIO *b,const char *buf);
=head1 DESCRIPTION
BIO_read() attempts to read B<len> bytes from BIO B<b> and places
the data in B<buf>.
BIO_gets() performs the BIOs "gets" operation and places the data
in B<buf>. Usually this operation will attempt to read a line of data
from the BIO of maximum length B<len>. There are exceptions to this
however, for example BIO_gets() on a digest BIO will calculate and
return the digest and other BIOs may not support BIO_gets() at all.
BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>.
BIO_puts() attempts to write a null terminated string B<buf> to BIO B<b>
=head1 RETURN VALUES
All these functions return either the amount of data successfully read or
written (if the return value is positive) or that no data was successfully
read or written if the result is 0 or -1. If the return value is -2 then
the operation is not implemented in the specific BIO type.
=head1 NOTES
A 0 or -1 return is not necessarily an indication of an error. In
particular when the source/sink is non-blocking or of a certain type
it may merely be an indication that no data is currently available and that
the application should retry the operation later.
One technique sometimes used with blocking sockets is to use a system call
(such as select(), poll() or equivalent) to determine when data is available
and then call read() to read the data. The equivalent with BIOs (that is call
select() on the underlying I/O structure and then call BIO_read() to
read the data) should B<not> be used because a single call to BIO_read()
can cause several reads (and writes in the case of SSL BIOs) on the underlying
I/O structure and may block as a result. Instead select() (or equivalent)
should be combined with non blocking I/O so successive reads will request
a retry instead of blocking.
See L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to
determine the cause of a retry and other I/O issues.
If the BIO_gets() function is not supported by a BIO then it possible to
work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)>
to the chain.
=head1 SEE ALSO
L<BIO_should_retry(3)|BIO_should_retry(3)>
TBA

184
crypto/dist/openssl/doc/crypto/BIO_s_accept.pod vendored Normal file
View File

@ -0,0 +1,184 @@
=pod
=head1 NAME
BIO_s_accept, BIO_set_nbio, BIO_set_accept_port, BIO_get_accept_port,
BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode,
BIO_get_bind_mode, BIO_do_accept - accept BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_accept(void);
#define BIO_set_accept_port(b,name) BIO_ctrl(b,BIO_C_SET_ACCEPT,0,(char *)name)
#define BIO_get_accept_port(b) BIO_ptr_ctrl(b,BIO_C_GET_ACCEPT,0)
BIO *BIO_new_accept(char *host_port);
#define BIO_set_nbio_accept(b,n) BIO_ctrl(b,BIO_C_SET_ACCEPT,1,(n)?"a":NULL)
#define BIO_set_accept_bios(b,bio) BIO_ctrl(b,BIO_C_SET_ACCEPT,2,(char *)bio)
#define BIO_set_bind_mode(b,mode) BIO_ctrl(b,BIO_C_SET_BIND_MODE,mode,NULL)
#define BIO_get_bind_mode(b,mode) BIO_ctrl(b,BIO_C_GET_BIND_MODE,0,NULL)
#define BIO_BIND_NORMAL 0
#define BIO_BIND_REUSEADDR_IF_UNUSED 1
#define BIO_BIND_REUSEADDR 2
#define BIO_do_accept(b) BIO_do_handshake(b)
=head1 DESCRIPTION
BIO_s_accept() returns the accept BIO method. This is a wrapper
round the platform's TCP/IP socket accept routines.
Using accept BIOs TCP/IP connections can be accepted and data
transferred using only BIO routines. In this way any platform
specific operations are hidden by the BIO abstraction.
Read and write operations on an accept BIO will perform I/O
on the underlying connection. If no connection is established
and the port (see below) is set up properly then the BIO
waits for an incoming connection.
Accept BIOs support BIO_puts() but not BIO_gets().
If the close flag is set on an accept BIO then any active
connection on that chain is shutdown and the socket closed when
the BIO is freed.
Calling BIO_reset() on a accept BIO will close any active
connection and reset the BIO into a state where it awaits another
incoming connection.
BIO_get_fd() and BIO_set_fd() can be called to retrieve or set
the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)>
BIO_set_accept_port() uses the string B<name> to set the accept
port. The port is represented as a string of the form "host:port",
where "host" is the interface to use and "port" is the port.
Either or both values can be "*" which is interpreted as meaning
any interface or port respectively. "port" has the same syntax
as the port specified in BIO_set_conn_port() for connect BIOs,
that is it can be a numerical port string or a string to lookup
using getservbyname() and a string table.
BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into
a single call: that is it creates a new accept BIO with port
B<host_port>.
BIO_set_nbio_accept() sets the accept socket to blocking mode
(the default) if B<n> is 0 or non blocking mode if B<n> is 1.
BIO_set_accept_bios() can be used to set a chain of BIOs which
will be duplicated and prepended to the chain when an incoming
connection is received. This is useful if, for example, a
buffering or SSL BIO is required for each connection. The
chain of BIOs must not be freed after this call, they will
be automatically freed when the accept BIO is freed.
BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve
the current bind mode. If BIO_BIND_NORMAL (the default) is set
then another socket cannot be bound to the same port. If
BIO_BIND_REUSEADDR is set then other sockets can bind to the
same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and
attempt is first made to use BIO_BIN_NORMAL, if this fails
and the port is not in use then a second attempt is made
using BIO_BIND_REUSEADDR.
BIO_do_accept() serves two functions. When it is first
called, after the accept BIO has been setup, it will attempt
to create the accept socket and bind an address to it. Second
and subsequent calls to BIO_do_accept() will await an incoming
connection.
=head1 NOTES
When an accept BIO is at the end of a chain it will await an
incoming connection before processing I/O calls. When an accept
BIO is not at then end of a chain it passes I/O calls to the next
BIO in the chain.
When a connection is established a new socket BIO is created for
the connection and appended to the chain. That is the chain is now
accept->socket. This effectively means that attempting I/O on
an initial accept socket will await an incoming connection then
perform I/O on it.
If any additional BIOs have been set using BIO_set_accept_bios()
then they are placed between the socket and the accept BIO,
that is the chain will be accept->otherbios->socket.
If a server wishes to process multiple connections (as is normally
the case) then the accept BIO must be made available for further
incoming connections. This can be done by waiting for a connection and
then calling:
connection = BIO_pop(accept);
After this call B<connection> will contain a BIO for the recently
established connection and B<accept> will now be a single BIO
again which can be used to await further incoming connections.
If no further connections will be accepted the B<accept> can
be freed using BIO_free().
If only a single connection will be processed it is possible to
perform I/O using the accept BIO itself. This is often undesirable
however because the accept BIO will still accept additional incoming
connections. This can be resolved by using BIO_pop() (see above)
and freeing up the accept BIO after the initial connection.
=head1 RETURN VALUES
TBA
=head1 EXAMPLE
This example accepts two connections on port 4444, sends messages
down each and finally closes both down.
BIO *abio, *cbio, *cbio2;
ERR_load_crypto_strings();
abio = BIO_new_accept("4444");
/* First call to BIO_accept() sets up accept BIO */
if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error setting up accept\n");
ERR_print_errors_fp(stderr);
exit(0);
}
/* Wait for incoming connection */
if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(0);
}
fprintf(stderr, "Connection 1 established\n");
/* Retrieve BIO for connection */
cbio = BIO_pop(abio);
BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n");
fprintf(stderr, "Sent out data on connection 1\n");
/* Wait for another connection */
if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(0);
}
fprintf(stderr, "Connection 2 established\n");
/* Close accept BIO to refuse further connections */
cbio2 = BIO_pop(abio);
BIO_free(abio);
BIO_puts(cbio2, "Connection 2: Sending out Data on second\n");
fprintf(stderr, "Sent out data on connection 2\n");
BIO_puts(cbio, "Connection 1: Second connection established\n");
/* Close the two established connections */
BIO_free(cbio);
BIO_free(cbio2);
=head1 SEE ALSO
TBA

130
crypto/dist/openssl/doc/crypto/BIO_s_bio.pod vendored Normal file
View File

@ -0,0 +1,130 @@
=pod
=head1 NAME
BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr,
BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair,
BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request,
BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD *BIO_s_bio(void);
#define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2)
#define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL)
#define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL)
#define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL)
#define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL)
int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
#define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL)
size_t BIO_ctrl_get_write_guarantee(BIO *b);
#define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL)
size_t BIO_ctrl_get_read_request(BIO *b);
int BIO_ctrl_reset_read_request(BIO *b);
=head1 DESCRIPTION
BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink
BIOs where data written to either half of the pair is buffered and can be read from
the other half. Both halves must usually by handled by the same application thread
since no locking is done on the internal data structures.
Since BIO chains typically end in a source/sink BIO it is possible to make this
one half of a BIO pair and have all the data processed by the chain under application
control.
One typical use of BIO pairs is to place TLS/SSL I/O under application control, this
can be used when the application wishes to use a non standard transport for
TLS/SSL or the normal socket routines are inappropriate.
Calls to BIO_read() will read data from the buffer or request a retry if no
data is available.
Calls to BIO_write() will place data in the buffer or request a retry if the
buffer is full.
The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to
determine the amount of pending data in the read or write buffer.
BIO_reset() clears any data in the write buffer.
BIO_make_bio_pair() joins two separate BIOs into a connected pair.
BIO_destroy_pair() destroys the association between two connected BIOs. Freeing
up any half of the pair will automatically destroy the association.
BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further
writes on BIO B<b> are allowed (they will return an error). Reads on the other
half of the pair will return any pending data or EOF when all pending data has
been read.
BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>.
If the size is not initialized a default value is used. This is currently
17K, sufficient for a maximum size TLS record.
BIO_get_write_buf_size() returns the size of the write buffer.
BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and
BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2>
with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is
zero then the default size is used.
BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum
length of data that can be currently written to the BIO. Writes larger than this
value will return a value from BIO_write() less than the amount requested or if the
buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function
whereas BIO_get_write_guarantee() is a macro.
BIO_get_read_request() and BIO_ctrl_get_read_request() return the
amount of data requested, or the buffer size if it is less, if the
last read attempt at the other half of the BIO pair failed due to an
empty buffer. This can be used to determine how much data should be
written to the BIO so the next read will succeed: this is most useful
in TLS/SSL applications where the amount of data read is usually
meaningful rather than just a buffer size. After a successful read
this call will return zero. It also will return zero once new data
has been written satisfying the read request or part of it.
Note that BIO_get_read_request() never returns an amount larger
than that returned by BIO_get_write_guarantee().
BIO_ctrl_reset_read_request() can also be used to reset the value returned by
BIO_get_read_request() to zero.
=head1 NOTES
Both halves of a BIO pair should be freed. That is even if one half is implicit
freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed.
When used in bidirectional applications (such as TLS/SSL) care should be taken to
flush any data in the write buffer. This can be done by calling BIO_pending()
on the other half of the pair and, if any data is pending, reading it and sending
it to the underlying transport. This must be done before any normal processing
(such as calling select() ) due to a request and BIO_should_read() being true.
To see why this is important consider a case where a request is sent using
BIO_write() and a response read with BIO_read(), this can occur during an
TLS/SSL handshake for example. BIO_write() will succeed and place data in the write
buffer. BIO_read() will initially fail and BIO_should_read() will be true. If
the application then waits for data to be available on the underlying transport
before flushing the write buffer it will never succeed because the request was
never sent!
=head1 EXAMPLE
TBA
=head1 SEE ALSO
L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
L<BIO_should_retry(3)|BIO_should_retry(3)>, L<BIO_read(3)|BIO_read(3)>
=cut

182
crypto/dist/openssl/doc/crypto/BIO_s_connect.pod vendored Normal file
View File

@ -0,0 +1,182 @@
=pod
=head1 NAME
BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port,
BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
BIO_set_nbio, BIO_do_connect - connect BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_connect(void);
#define BIO_set_conn_hostname(b,name) BIO_ctrl(b,BIO_C_SET_CONNECT,0,(char *)name)
#define BIO_set_conn_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,1,(char *)port)
#define BIO_set_conn_ip(b,ip) BIO_ctrl(b,BIO_C_SET_CONNECT,2,(char *)ip)
#define BIO_set_conn_int_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,3,(char *)port)
#define BIO_get_conn_hostname(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,0)
#define BIO_get_conn_port(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,1)
#define BIO_get_conn_ip(b,ip) BIO_ptr_ctrl(b,BIO_C_SET_CONNECT,2)
#define BIO_get_conn_int_port(b,port) BIO_int_ctrl(b,BIO_C_SET_CONNECT,3,port)
#define BIO_set_nbio(b,n) BIO_ctrl(b,BIO_C_SET_NBIO,(n),NULL)
#define BIO_do_connect(b) BIO_do_handshake(b)
=head1 DESCRIPTION
BIO_s_connect() returns the connect BIO method. This is a wrapper
round the platform's TCP/IP socket connection routines.
Using connect BIOs TCP/IP connections can be made and data
transferred using only BIO routines. In this way any platform
specific operations are hidden by the BIO abstraction.
Read and write operations on a connect BIO will perform I/O
on the underlying connection. If no connection is established
and the port and hostname (see below) is set up properly then
a connection is established first.
Connect BIOs support BIO_puts() but not BIO_gets().
If the close flag is set on a connect BIO then any active
connection is shutdown and the socket closed when the BIO
is freed.
Calling BIO_reset() on a connect BIO will close any active
connection and reset the BIO into a state where it can connect
to the same host again.
BIO_get_fd() places the underlying socket in B<c> if it is not NULL,
it also returns the socket . If B<c> is not NULL it should be of
type (int *).
BIO_set_conn_hostname() uses the string B<name> to set the hostname
The hostname can be an IP address. The hostname can also include the
port in the form hostname:port . It is also acceptable to use the
form "hostname/any/other/path" or "hostname:port/any/other/path".
BIO_set_conn_port() sets the port to B<port>. B<port> can be the
numerical form or a string such as "http". A string will be looked
up first using getservbyname() on the host platform but if that
fails a standard table of port names will be used. Currently the
list is http, telnet, socks, https, ssl, ftp, gopher and wais.
BIO_set_conn_ip() sets the IP address to B<ip> using binary form,
that is four bytes specifying the IP address in big-endian form.
BIO_set_conn_int_port() sets the port using B<port>. B<port> should
be of type (int *).
BIO_get_conn_hostname() returns the hostname of the connect BIO or
NULL if the BIO is initialized but no hostname is set.
This return value is an internal pointer which should not be modified.
BIO_get_conn_port() returns the port as a string.
BIO_get_conn_ip() returns the IP address in binary form.
BIO_get_conn_int_port() returns the port as an int.
BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is
zero then blocking I/O is set. If B<n> is 1 then non blocking I/O
is set. Blocking I/O is the default. The call to BIO_set_nbio()
should be made before the connection is established because
non blocking I/O is set during the connect process.
BIO_do_connect() attempts to connect the supplied BIO. It returns 1
if the connection was established successfully. A zero or negative
value is returned if the connection could not be established, the
call BIO_should_retry() should be used for non blocking connect BIOs
to determine if the call should be retried.
=head1 NOTES
If blocking I/O is set then a non positive return value from any
I/O call is caused by an error condition, although a zero return
will normally mean that the connection was closed.
If the port name is supplied as part of the host name then this will
override any value set with BIO_set_conn_port(). This may be undesirable
if the application does not wish to allow connection to arbitrary
ports. This can be avoided by checking for the presence of the ':'
character in the passed hostname and either indicating an error or
truncating the string at that point.
The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(),
BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a
connection attempt is made. Before any connection attempt the values
returned are those set by the application itself.
Applications do not have to call BIO_do_connect() but may wish to do
so to separate the connection process from other I/O processing.
If non blocking I/O is set then retries will be requested as appropriate.
It addition to BIO_should_read() and BIO_should_write() it is also
possible for BIO_should_io_special() to be true during the initial
connection process with the reason BIO_RR_CONNECT. If this is returned
then this is an indication that a connection attempt would block,
the application should then take appropriate action to wait until
the underlying socket has connected and retry the call.
=head1 RETURN VALUES
BIO_s_connect() returns the connect BIO method.
BIO_get_fd() returns the socket or -1 if the BIO has not
been initialized.
BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and
BIO_set_conn_int_port() always return 1.
BIO_get_conn_hostname() returns the connected hostname or NULL is
none was set.
BIO_get_conn_port() returns a string representing the connected
port or NULL if not set.
BIO_get_conn_ip() returns a pointer to the connected IP address in
binary form or all zeros if not set.
BIO_get_conn_int_port() returns the connected port or 0 if none was
set.
BIO_set_nbio() always returns 1.
BIO_do_connect() returns 1 if the connection was successfully
established and 0 or -1 if the connection failed.
=head1 EXAMPLE
This is example connects to a webserver on the local host and attempts
to retrieve a page and copy the result to standard output.
BIO *cbio, *out;
int len;
char tmpbuf[1024];
ERR_load_crypto_strings();
cbio = BIO_new_connect("localhost:http");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
if(BIO_do_connect(cbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
}
BIO_puts(cbio, "GET / HTTP/1.0\n\n");
for(;;) {
len = BIO_read(cbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(out, tmpbuf, len);
}
BIO_free(cbio);
BIO_free(out);
=head1 SEE ALSO
TBA

89
crypto/dist/openssl/doc/crypto/BIO_s_fd.pod vendored Normal file
View File

@ -0,0 +1,89 @@
=pod
=head1 NAME
BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_fd(void);
#define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd)
#define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c)
BIO *BIO_new_fd(int fd, int close_flag);
=head1 DESCRIPTION
BIO_s_fd() returns the file descriptor BIO method. This is a wrapper
round the platforms file descriptor routines such as read() and write().
BIO_read() and BIO_write() read or write the underlying descriptor.
BIO_puts() is supported but BIO_gets() is not.
If the close flag is set then then close() is called on the underlying
file descriptor when the BIO is freed.
BIO_reset() attempts to change the file pointer to the start of file
using lseek(fd, 0, 0).
BIO_seek() sets the file pointer to position B<ofs> from start of file
using lseek(fd, ofs, 0).
BIO_tell() returns the current file position by calling lseek(fd, 0, 1).
BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close
flag to B<c>.
BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also
returns the file descriptor. If B<c> is not NULL it should be of type
(int *).
BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>.
=head1 NOTES
The behaviour of BIO_read() and BIO_write() depends on the behavior of the
platforms read() and write() calls on the descriptor. If the underlying
file descriptor is in a non blocking mode then the BIO will behave in the
manner described in the L<BIO_read(3)|BIO_read(3)> and L<BIO_should_retry(3)|BIO_should_retry(3)>
manual pages.
File descriptor BIOs should not be used for socket I/O. Use socket BIOs
instead.
=head1 RETURN VALUES
BIO_s_fd() returns the file descriptor BIO method.
BIO_reset() returns zero for success and -1 if an error occurred.
BIO_seek() and BIO_tell() return the current file position or -1
is an error occurred. These values reflect the underlying lseek()
behaviour.
BIO_set_fd() always returns 1.
BIO_get_fd() returns the file descriptor or -1 if the BIO has not
been initialized.
BIO_new_fd() returns the newly allocated BIO or NULL is an error
occurred.
=head1 EXAMPLE
This is a file descriptor BIO version of "Hello World":
BIO *out;
out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
BIO_printf(out, "Hello World\n");
BIO_free(out);
=head1 SEE ALSO
L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
L<BIO_reset(3)|BIO_reset(3)>, L<BIO_read(3)|BIO_read(3)>,
L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>

144
crypto/dist/openssl/doc/crypto/BIO_s_file.pod vendored Normal file
View File

@ -0,0 +1,144 @@
=pod
=head1 NAME
BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp,
BIO_read_filename, BIO_write_filename, BIO_append_filename,
BIO_rw_filename - FILE bio
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_file(void);
BIO *BIO_new_file(const char *filename, const char *mode);
BIO *BIO_new_fp(FILE *stream, int flags);
BIO_set_fp(BIO *b,FILE *fp, int flags);
BIO_get_fp(BIO *b,FILE **fpp);
int BIO_read_filename(BIO *b, char *name)
int BIO_write_filename(BIO *b, char *name)
int BIO_append_filename(BIO *b, char *name)
int BIO_rw_filename(BIO *b, char *name)
=head1 DESCRIPTION
BIO_s_file() returns the BIO file method. As its name implies it
is a wrapper round the stdio FILE structure and it is a
source/sink BIO.
Calls to BIO_read() and BIO_write() read and write data to the
underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs.
BIO_flush() on a file BIO calls the fflush() function on the wrapped
stream.
BIO_reset() attempts to change the file pointer to the start of file
using fseek(stream, 0, 0).
BIO_seek() sets the file pointer to position B<ofs> from start of file
using fseek(stream, ofs, 0).
BIO_eof() calls feof().
Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO
is freed.
BIO_new_file() creates a new file BIO with mode B<mode> the meaning
of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE
flag is set on the returned BIO.
BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be:
BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying
stream to text mode, default is binary: this only has any effect under
Win32).
BIO_set_fp() set the fp of a file BIO to B<fp>. B<flags> has the same
meaning as in BIO_new_fp(), it is a macro.
BIO_get_fp() retrieves the fp of a file BIO, it is a macro.
BIO_seek() is a macro that sets the position pointer to B<offset> bytes
from the start of file.
BIO_tell() returns the value of the position pointer.
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
BIO_rw_filename() set the file BIO B<b> to use file B<name> for
reading, writing, append or read write respectively.
=head1 NOTES
When wrapping stdout, stdin or stderr the underlying stream should not
normally be closed so the BIO_NOCLOSE flag should be set.
Because the file BIO calls the underlying stdio functions any quirks
in stdio behaviour will be mirrored by the corresponding BIO.
=head1 EXAMPLES
File BIO "hello world":
BIO *bio_out;
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
BIO_printf(bio_out, "Hello World\n");
Alternative technique:
BIO *bio_out;
bio_out = BIO_new(BIO_s_file());
if(bio_out == NULL) /* Error ... */
if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
BIO_printf(bio_out, "Hello World\n");
Write to a file:
BIO *out;
out = BIO_new_file("filename.txt", "w");
if(!out) /* Error occurred */
BIO_printf(out, "Hello World\n");
BIO_free(out);
Alternative technique:
BIO *out;
out = BIO_new(BIO_s_file());
if(out == NULL) /* Error ... */
if(!BIO_write_filename(out, "filename.txt")) /* Error ... */
BIO_printf(out, "Hello World\n");
BIO_free(out);
=head1 RETURN VALUES
BIO_s_file() returns the file BIO method.
BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error
occurred.
BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure
(although the current implementation never return 0).
BIO_seek() returns the same value as the underlying fseek() function:
0 for success or -1 for failure.
BIO_tell() returns the current file position.
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
BIO_rw_filename() return 1 for success or 0 for failure.
=head1 BUGS
BIO_reset() and BIO_seek() are implemented using fseek() on the underlying
stream. The return value for fseek() is 0 for success or -1 if an error
occurred this differs from other types of BIO which will typically return
1 for success and a non positive value if an error occurred.
=head1 SEE ALSO
L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
L<BIO_reset(3)|BIO_reset(3)>, L<BIO_flush(3)|BIO_flush(3)>,
L<BIO_read(3)|BIO_read(3)>,
L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>

115
crypto/dist/openssl/doc/crypto/BIO_s_mem.pod vendored Normal file
View File

@ -0,0 +1,115 @@
=pod
=head1 NAME
BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf,
BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_mem(void);
BIO_set_mem_eof_return(BIO *b,int v)
long BIO_get_mem_data(BIO *b, char **pp)
BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c)
BIO_get_mem_ptr(BIO *b,BUF_MEM **pp)
BIO *BIO_new_mem_buf(void *buf, int len);
=head1 DESCRIPTION
BIO_s_mem() return the memory BIO method function.
A memory BIO is a source/sink BIO which uses memory for its I/O. Data
written to a memory BIO is stored in a BUF_MEM structure which is extended
as appropriate to accommodate the stored data.
Any data written to a memory BIO can be recalled by reading from it.
Unless the memory BIO is read only any data read from it is deleted from
the BIO.
Memory BIOs support BIO_gets() and BIO_puts().
If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying
BUF_MEM structure is also freed.
Calling BIO_reset() on a read write memory BIO clears any data in it. On a
read only BIO it restores the BIO to its original state and the read only
data can be read again.
BIO_eof() is true if no data is in the BIO.
BIO_ctrl_pending() returns the number of bytes currently stored.
BIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is
empty. If the B<v> is zero then an empty memory BIO will return EOF (that is
it will return zero and BIO_should_retry(b) will be false. If B<v> is non
zero then it will return B<v> when it is empty and it will set the read retry
flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal
positive return value B<v> should be set to a negative value, typically -1.
BIO_get_mem_data() sets B<pp> to a pointer to the start of the memory BIOs data
and returns the total amount of data available. It is implemented as a macro.
BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the
close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE.
It is a macro.
BIO_get_mem_ptr() places the underlying BUF_MEM structure in B<pp>. It is
a macro.
BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>,
if B<len> is -1 then the B<buf> is assumed to be null terminated and its
length is determined by B<strlen>. The BIO is set to a read only state and
as a result cannot be written to. This is useful when some data needs to be
made available from a static area of memory in the form of a BIO. The
supplied data is read directly from the supplied buffer: it is B<not> copied
first, so the supplied area of memory must be unchanged until the BIO is freed.
=head1 NOTES
Writes to memory BIOs will always succeed if memory is available: that is
their size can grow indefinitely.
Every read from a read write memory BIO will remove the data just read with
an internal copy operation, if a BIO contains a lots of data and it is
read in small chunks the operation can be very slow. The use of a read only
memory BIO avoids this problem. If the BIO must be read write then adding
a buffering BIO to the chain will speed up the process.
=head1 BUGS
There should be an option to set the maximum size of a memory BIO.
There should be a way to "rewind" a read write BIO without destroying
its contents.
The copying operation should not occur after every small read of a large BIO
to improve efficiency.
=head1 EXAMPLE
Create a memory BIO and write some data to it:
BIO *mem = BIO_new(BIO_s_mem());
BIO_puts(mem, "Hello World\n");
Create a read only memory BIO:
char data[] = "Hello World";
BIO *mem;
mem = BIO_new_mem_buf(data, -1);
Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
BUF_MEM *bptr;
BIO_get_mem_ptr(mem, &bptr);
BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
BIO_free(mem);
=head1 SEE ALSO
TBA

37
crypto/dist/openssl/doc/crypto/BIO_s_null.pod vendored Normal file
View File

@ -0,0 +1,37 @@
=pod
=head1 NAME
BIO_s_null - null data sink
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_null(void);
=head1 DESCRIPTION
BIO_s_null() returns the null sink BIO method. Data written to
the null sink is discarded, reads return EOF.
=head1 NOTES
A null sink BIO behaves in a similar manner to the Unix /dev/null
device.
A null bio can be placed on the end of a chain to discard any data
passed through it.
A null sink is useful if, for example, an application wishes to digest some
data by writing through a digest bio but not send the digested data anywhere.
Since a BIO chain must normally include a source/sink BIO this can be achieved
by adding a null sink BIO to the end of the chain
=head1 RETURN VALUES
BIO_s_null() returns the null sink BIO method.
=head1 SEE ALSO
TBA

61
crypto/dist/openssl/doc/crypto/BIO_s_socket.pod vendored Normal file
View File

@ -0,0 +1,61 @@
=pod
=head1 NAME
BIO_s_socket, BIO_new_socket - socket BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_socket(void);
#define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd)
#define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c)
BIO *BIO_new_socket(int sock, int close_flag);
=head1 DESCRIPTION
BIO_s_socket() returns the socket BIO method. This is a wrapper
round the platform's socket routines.
BIO_read() and BIO_write() read or write the underlying socket.
BIO_puts() is supported but BIO_gets() is not.
If the close flag is set then the socket is shut down and closed
when the BIO is freed.
BIO_set_fd() sets the socket of BIO B<b> to B<fd> and the close
flag to B<c>.
BIO_get_fd() places the socket in B<c> if it is not NULL, it also
returns the socket . If B<c> is not NULL it should be of type (int *).
BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>.
=head1 NOTES
Socket BIOs also support any relevant functionality of file descriptor
BIOs.
The reason for having separate file descriptor and socket BIOs is that on some
platforms sockets are not file descriptors and use distinct I/O routines,
Windows is one such platform. Any code mixing the two will not work on
all platforms.
=head1 RETURN VALUES
BIO_s_socket() returns the socket BIO method.
BIO_set_fd() always returns 1.
BIO_get_fd() returns the socket or -1 if the BIO has not been
initialized.
BIO_new_socket() returns the newly allocated BIO or NULL is an error
occurred.
=head1 SEE ALSO
TBA

108
crypto/dist/openssl/doc/crypto/BIO_set_callback.pod vendored Normal file
View File

@ -0,0 +1,108 @@
=pod
=head1 NAME
BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
BIO_debug_callback - BIO callback functions
=head1 SYNOPSIS
#include <openssl/bio.h>
#define BIO_set_callback(b,cb) ((b)->callback=(cb))
#define BIO_get_callback(b) ((b)->callback)
#define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg))
#define BIO_get_callback_arg(b) ((b)->cb_arg)
long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,
long argl,long ret);
typedef long callback(BIO *b, int oper, const char *argp,
int argi, long argl, long retvalue);
=head1 DESCRIPTION
BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback,
they are both macros. The callback is called during most high level BIO
operations. It can be used for debugging purposes to trace operations on
a BIO or to modify its operation.
BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be
used to set and retrieve an argument for use in the callback.
BIO_debug_callback() is a standard debugging callback which prints
out information relating to each BIO operation. If the callback
argument is set if is interpreted as a BIO to send the information
to, otherwise stderr is used.
callback() is the callback function itself. The meaning of each
argument is described below.
The BIO the callback is attached to is passed in B<b>.
B<oper> is set to the operation being performed. For some operations
the callback is called twice, once before and once after the actual
operation, the latter case has B<oper> or'ed with BIO_CB_RETURN.
The meaning of the arguments B<argp>, B<argi> and B<argl> depends on
the value of B<oper>, that is the operation being performed.
B<retvalue> is the return value that would be returned to the
application if no callback were present. The actual value returned
is the return value of the callback itself. In the case of callbacks
called before the actual BIO operation 1 is placed in retvalue, if
the return value is not positive it will be immediately returned to
the application and the BIO operation will not be performed.
The callback should normally simply return B<retvalue> when it has
finished processing, unless if specifically wishes to modify the
value returned to the application.
=head1 CALLBACK OPERATIONS
=over 4
=item B<BIO_free(b)>
callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the
free operation.
=item B<BIO_read(b, out, outl)>
callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before
the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
after.
=item B<BIO_write(b, in, inl)>
callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before
the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
after.
=item B<BIO_gets(b, out, outl)>
callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before
the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
after.
=item B<BIO_puts(b, in)>
callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before
the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
after.
=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)>
callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and
callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.
=back
=head1 EXAMPLE
The BIO_debug_callback() function is a good example, its source is
in crypto/bio/bio_cb.c
=head1 SEE ALSO
TBA

114
crypto/dist/openssl/doc/crypto/BIO_should_retry.pod vendored Normal file
View File

@ -0,0 +1,114 @@
=pod
=head1 NAME
BIO_should_retry, BIO_should_read, BIO_should_write,
BIO_should_io_special, BIO_retry_type, BIO_should_retry,
BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions
=head1 SYNOPSIS
#include <openssl/bio.h>
#define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ)
#define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE)
#define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL)
#define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS)
#define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY)
#define BIO_FLAGS_READ 0x01
#define BIO_FLAGS_WRITE 0x02
#define BIO_FLAGS_IO_SPECIAL 0x04
#define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL)
#define BIO_FLAGS_SHOULD_RETRY 0x08
BIO * BIO_get_retry_BIO(BIO *bio, int *reason);
int BIO_get_retry_reason(BIO *bio);
=head1 DESCRIPTION
These functions determine why a BIO is not able to read or write data.
They will typically be called after a failed BIO_read() or BIO_write()
call.
BIO_should_retry() is true if the call that produced this condition
should then be retried at a later time.
If BIO_should_retry() is false then the cause is an error condition.
BIO_should_read() is true if the cause of the condition is that a BIO
needs to read data.
BIO_should_write() is true if the cause of the condition is that a BIO
needs to read data.
BIO_should_io_special() is true if some "special" condition, that is a
reason other than reading or writing is the cause of the condition.
BIO_get_retry_reason() returns a mask of the cause of a retry condition
consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>,
B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of
these.
BIO_get_retry_BIO() determines the precise reason for the special
condition, it returns the BIO that caused this condition and if
B<reason> is not NULL it contains the reason code. The meaning of
the reason code and the action that should be taken depends on
the type of BIO that resulted in this condition.
BIO_get_retry_reason() returns the reason for a special condition if
passed the relevant BIO, for example as returned by BIO_get_retry_BIO().
=head1 NOTES
If BIO_should_retry() returns false then the precise "error condition"
depends on the BIO type that caused it and the return code of the BIO
operation. For example if a call to BIO_read() on a socket BIO returns
0 and BIO_should_retry() is false then the cause will be that the
connection closed. A similar condition on a file BIO will mean that it
has reached EOF. Some BIO types may place additional information on
the error queue. For more details see the individual BIO type manual
pages.
If the underlying I/O structure is in a blocking mode almost all current
BIO types will not request a retry, because the underlying I/O
calls will not. If the application knows that the BIO type will never
signal a retry then it need not call BIO_should_retry() after a failed
BIO I/O call. This is typically done with file BIOs.
SSL BIOs are the only current exception to this rule: they can request a
retry even if the underlying I/O structure is blocking, if a handshake
occurs during a call to BIO_read(). An application can retry the failed
call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY
on the underlying SSL structure.
While an application may retry a failed non blocking call immediately
this is likely to be very inefficient because the call will fail
repeatedly until data can be processed or is available. An application
will normally wait until the necessary condition is satisfied. How
this is done depends on the underlying I/O structure.
For example if the cause is ultimately a socket and BIO_should_read()
is true then a call to select() may be made to wait until data is
available and then retry the BIO operation. By combining the retry
conditions of several non blocking BIOs in a single select() call
it is possible to service several BIOs in a single thread, though
the performance may be poor if SSL BIOs are present because long delays
can occur during the initial handshake process.
It is possible for a BIO to block indefinitely if the underlying I/O
structure cannot process or return any data. This depends on the behaviour of
the platforms I/O functions. This is often not desirable: one solution
is to use non blocking I/O and use a timeout on the select() (or
equivalent) call.
=head1 BUGS
The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O:
that is they cannot retry after a partial read or write. This is usually
worked around by only passing the relevant data to ASN1 functions when
the entire structure can be read or written.
=head1 SEE ALSO
TBA

3
crypto/dist/openssl/doc/crypto/BN_CTX_start.pod vendored
View File

@ -17,7 +17,8 @@ BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables
=head1 DESCRIPTION
These functions are used to obtain temporary B<BIGNUM> variables from
a B<BN_CTX> in order to save the overhead of repeatedly creating and
a B<BN_CTX> (which can been created by using L<BN_CTX_new(3)|BN_CTX_new(3)>)
in order to save the overhead of repeatedly creating and
freeing B<BIGNUM>s in functions that are called from inside a loop.
A function must call BN_CTX_start() first. Then, BN_CTX_get() may be

2
crypto/dist/openssl/doc/crypto/BN_bn2bin.pod vendored
View File

@ -36,7 +36,7 @@ NULL, a new B<BIGNUM> is created.
BN_bn2hex() and BN_bn2dec() return printable strings containing the
hexadecimal and decimal encoding of B<a> respectively. For negative
numbers, the string is prefaced with a leading '-'. The string must be
Free()d later.
freed later using OPENSSL_free().
BN_hex2bn() converts the string B<str> containing a hexadecimal number
to a B<BIGNUM> and stores it in **B<bn>. If *B<bn> is NULL, a new

4
crypto/dist/openssl/doc/crypto/BN_mod_mul_montgomery.pod vendored
View File

@ -39,7 +39,7 @@ BN_MONT_CTX_init() initializes an existing uninitialized B<BN_MONT_CTX>.
BN_MONT_CTX_set() sets up the B<mont> structure from the modulus B<m>
by precomputing its inverse and a value R.
BN_MONT_CTX_copy() copies the B<N_MONT_CTX> B<from> to B<to>.
BN_MONT_CTX_copy() copies the B<BN_MONT_CTX> B<from> to B<to>.
BN_MONT_CTX_free() frees the components of the B<BN_MONT_CTX>, and, if
it was created by BN_MONT_CTX_new(), also the structure itself.
@ -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).
BN_to_montgomery() computes Mont(B<a>,R^2), i.e. B<a>*R.
For all functions, B<ctx> is a previously allocated B<BN_CTX> used for
temporary variables.

2
crypto/dist/openssl/doc/crypto/BN_mod_mul_reciprocal.pod vendored
View File

@ -2,7 +2,7 @@
=head1 NAME
BN_mod_mul_reciprocal, BN_RECP_CTX_new, BN_RECP_CTX_init,
BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_init,
BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using
reciprocal

22
crypto/dist/openssl/doc/crypto/BN_rand.pod vendored
View File

@ -12,24 +12,31 @@ BN_rand, BN_pseudo_rand - generate pseudo-random number
int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
=head1 DESCRIPTION
BN_rand() generates a cryptographically strong pseudo-random number of
B<bits> bits in length and stores it in B<rnd>. If B<top> is true, the
two most significant bits of the number will be set to 1, so that the
product of two such random numbers will always have 2*B<bits> length.
If B<bottom> is true, the number will be odd.
B<bits> bits in length and stores it in B<rnd>. If B<top> is -1, the
most significant bit of the random number can be zero. If B<top> is 0,
it is set to 1, and if B<top> is 1, the two most significant bits of
the number will be set to 1, so that the product of two such random
numbers will always have 2*B<bits> length. If B<bottom> is true, the
number will be odd.
BN_pseudo_rand() does the same, but pseudo-random numbers generated by
this function are not necessarily unpredictable. They can be used for
non-cryptographic purposes and for certain purposes in cryptographic
protocols, but usually not for key generation etc.
The PRNG must be seeded prior to calling BN_rand().
BN_rand_range() generates a cryptographically strong pseudo-random
number B<rnd> in the range 0 <lt>= B<rnd> E<lt> B<range>.
The PRNG must be seeded prior to calling BN_rand() or BN_rand_range().
=head1 RETURN VALUES
BN_rand() and BN_pseudo_rand() return 1 on success, 0 on error.
The functions return 1 on success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 SEE ALSO
@ -40,6 +47,7 @@ L<RAND_add(3)|RAND_add(3)>, L<RAND_bytes(3)|RAND_bytes(3)>
=head1 HISTORY
BN_rand() is available in all versions of SSLeay and OpenSSL.
BN_pseudo_rand() was added in OpenSSL 0.9.5.
BN_pseudo_rand() was added in OpenSSL 0.9.5. The B<top> == -1 case
and the function BN_rand_range() were added in OpenSSL 0.9.6a.
=cut

3
crypto/dist/openssl/doc/crypto/BN_zero.pod vendored
View File

@ -2,7 +2,8 @@
=head1 NAME
BN_zero, BN_one, BN_set_word, BN_get_word - BIGNUM assignment operations
BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word - BIGNUM assignment
operations
=head1 SYNOPSIS

7
crypto/dist/openssl/doc/crypto/DH_set_method.pod vendored
View File

@ -36,9 +36,6 @@ method.
DH_set_method() selects B<meth> for all operations using the structure B<dh>.
DH_get_method() returns a pointer to the method currently selected
for B<dh>.
DH_new_method() allocates and initializes a B<DH> structure so that
B<method> will be used for the DH operations. If B<method> is B<NULL>,
the default method is used.
@ -75,8 +72,8 @@ the default method is used.
=head1 RETURN VALUES
DH_OpenSSL(), DH_get_default_method() and DH_get_method() return
pointers to the respective B<DH_METHOD>s.
DH_OpenSSL() and DH_get_default_method() return pointers to the respective
B<DH_METHOD>s.
DH_set_default_method() returns no value.

13
crypto/dist/openssl/doc/crypto/DSA_set_method.pod vendored
View File

@ -3,11 +3,11 @@
=head1 NAME
DSA_set_default_method, DSA_get_default_method, DSA_set_method,
DSA_new_method, DSA_OpenSSL - select RSA method
DSA_new_method, DSA_OpenSSL - select DSA method
=head1 SYNOPSIS
#include <openssl/DSA.h>
#include <openssl/dsa.h>
void DSA_set_default_method(DSA_METHOD *meth);
@ -34,10 +34,7 @@ structures created later.
DSA_get_default_method() returns a pointer to the current default
method.
DSA_set_method() selects B<meth> for all operations using the structure B<DSA>.
DSA_get_method() returns a pointer to the method currently selected
for B<DSA>.
DSA_set_method() selects B<meth> for all operations using the structure B<dsa>.
DSA_new_method() allocates and initializes a B<DSA> structure so that
B<method> will be used for the DSA operations. If B<method> is B<NULL>,
@ -87,8 +84,8 @@ struct
=head1 RETURN VALUES
DSA_OpenSSL(), DSA_get_default_method() and DSA_get_method() return
pointers to the respective B<DSA_METHOD>s.
DSA_OpenSSL() and DSA_get_default_method() return pointers to the
respective B<DSA_METHOD>s.
DSA_set_default_method() returns no value.

16
crypto/dist/openssl/doc/crypto/ERR_error_string.pod vendored
View File

@ -2,13 +2,16 @@
=head1 NAME
ERR_error_string - obtain human-readable error message
ERR_error_string, ERR_error_string_n, ERR_lib_error_string,
ERR_func_error_string, ERR_reason_error_string - obtain human-readable
error message
=head1 SYNOPSIS
#include <openssl/err.h>
char *ERR_error_string(unsigned long e, char *buf);
char *ERR_error_string_n(unsigned long e, char *buf, size_t len);
const char *ERR_lib_error_string(unsigned long e);
const char *ERR_func_error_string(unsigned long e);
@ -17,9 +20,13 @@ ERR_error_string - obtain human-readable error message
=head1 DESCRIPTION
ERR_error_string() generates a human-readable string representing the
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
error code I<e>, and places it at I<buf>. I<buf> must be at least 120
bytes long. If I<buf> is B<NULL>, the error string is placed in a
static buffer.
ERR_error_string_n() is a variant of ERR_error_string() that writes
at most I<len> characters (including the terminating 0)
and truncates the string if necessary.
For ERR_error_string_n(), I<buf> may not be B<NULL>.
The string will have the following format:
@ -45,7 +52,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 B<buf == NULL>, B<buf> otherwise.
string if I<buf> B<== NULL>, I<buf> otherwise.
ERR_lib_error_string(), ERR_func_error_string() and
ERR_reason_error_string() return the strings, and B<NULL> if
@ -61,5 +68,6 @@ 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

5
crypto/dist/openssl/doc/crypto/ERR_get_error.pod vendored
View File

@ -2,7 +2,8 @@
=head1 NAME
ERR_get_error, ERR_peek_error - obtain error code
ERR_get_error, ERR_peek_error, ERR_get_error_line, ERR_peek_error_line,
ERR_get_error_line_data, ERR_peek_error_line_data - obtain error code and data
=head1 SYNOPSIS
@ -40,7 +41,7 @@ the error occurred in *B<file> and *B<line>, unless these are B<NULL>.
ERR_get_error_line_data() and ERR_peek_error_line_data() store
additional data and flags associated with the error code in *B<data>
and *B<flags>, unless these are B<NULL>. *B<data> contains a string
if *B<flags>&B<ERR_TXT_STRING>. If it has been allocated by Malloc(),
if *B<flags>&B<ERR_TXT_STRING>. If it has been allocated by OPENSSL_malloc(),
*B<flags>&B<ERR_TXT_MALLOCED> is true.
=head1 RETURN VALUES

2
crypto/dist/openssl/doc/crypto/ERR_remove_state.pod vendored
View File

@ -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 oder to
threads, they must be freed when threads are terminated in order to
avoid memory leaks.
=head1 RETURN VALUE

15
crypto/dist/openssl/doc/crypto/EVP_DigestInit.pod vendored
View File

@ -2,7 +2,12 @@
=head1 NAME
EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal - EVP digest routines
EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal, EVP_MAX_MD_SIZE,
EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size,
EVP_MD_CTX_md, EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type,
EVP_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1, EVP_dss, EVP_dss1, EVP_mdc2,
EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj -
EVP digest routines
=head1 SYNOPSIS
@ -45,12 +50,12 @@ EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal - EVP digest routines
The EVP digest routines are a high level interface to message digests.
EVP_DigestInit() initialises a digest context B<ctx> to use a digest
EVP_DigestInit() initializes a digest context B<ctx> to use a digest
B<type>: this will typically be supplied by a function such as
EVP_sha1().
EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the
digest context B<ctx>. This funtion can be called several times on the
digest context B<ctx>. This function can be called several times on the
same B<ctx> to hash additional data.
EVP_DigestFinal() retrieves the digest value from B<ctx> and places
@ -58,7 +63,7 @@ it in B<md>. If the B<s> parameter is not NULL then the number of
bytes of data written (i.e. the length of the digest) will be written
to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written.
After calling EVP_DigestFinal() no additional calls to EVP_DigestUpdate()
can be made, but EVP_DigestInit() can be called to initialiase a new
can be made, but EVP_DigestInit() can be called to initialize a new
digest operation.
EVP_MD_CTX_copy() can be used to copy the message digest state from
@ -97,7 +102,7 @@ returns is of zero length.
EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
return an B<EVP_MD> structure when passed a digest name, a digest NID or
an ASN1_OBJECT structure respectively. The digest table must be initialised
an ASN1_OBJECT structure respectively. The digest table must be initialized
using, for example, OpenSSL_add_all_digests() for these functions to work.
=head1 RETURN VALUES

199
crypto/dist/openssl/doc/crypto/EVP_EncryptInit.pod vendored
View File

@ -2,34 +2,46 @@
=head1 NAME
EVP_EncryptInit, EVP_EncryptUpdate, EVP_EncryptFinal - EVP cipher routines
EVP_EncryptInit, EVP_EncryptUpdate, EVP_EncryptFinal, EVP_DecryptInit,
EVP_DecryptUpdate, EVP_DecryptFinal, EVP_CipherInit, EVP_CipherUpdate,
EVP_CipherFinal, EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl,
EVP_CIPHER_CTX_cleanup, EVP_get_cipherbyname, EVP_get_cipherbynid,
EVP_get_cipherbyobj, EVP_CIPHER_nid, EVP_CIPHER_block_size,
EVP_CIPHER_key_length, EVP_CIPHER_iv_length, EVP_CIPHER_flags,
EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher, EVP_CIPHER_CTX_nid,
EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, EVP_CIPHER_CTX_iv_length,
EVP_CIPHER_CTX_get_app_data, EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type,
EVP_CIPHER_CTX_flags, EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1,
EVP_CIPHER_asn1_to_param - EVP cipher routines
=head1 SYNOPSIS
#include <openssl/evp.h>
void EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
unsigned char *key, unsigned char *iv);
void EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, unsigned char *in, int inl);
void EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl);
void EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
unsigned char *key, unsigned char *iv);
void EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, unsigned char *in, int inl);
int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
int *outl);
void EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
unsigned char *key, unsigned char *iv, int enc);
void EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, unsigned char *in, int inl);
int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
int *outl);
void EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a);
int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);
int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a);
const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
#define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a))
@ -38,15 +50,21 @@ EVP_EncryptInit, EVP_EncryptUpdate, EVP_EncryptFinal - EVP cipher routines
#define EVP_CIPHER_nid(e) ((e)->nid)
#define EVP_CIPHER_block_size(e) ((e)->block_size)
#define EVP_CIPHER_key_length(e) ((e)->key_len)
#define EVP_CIPHER_iv_length(e) ((e)->iv_len)
#define EVP_CIPHER_iv_length(e) ((e)->iv_len)
#define EVP_CIPHER_flags(e) ((e)->flags)
#define EVP_CIPHER_mode(e) ((e)->flags) & EVP_CIPH_MODE)
int EVP_CIPHER_type(const EVP_CIPHER *ctx);
#define EVP_CIPHER_CTX_cipher(e) ((e)->cipher)
#define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid)
#define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size)
#define EVP_CIPHER_CTX_key_length(e) ((e)->cipher->key_len)
#define EVP_CIPHER_CTX_key_length(e) ((e)->key_len)
#define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len)
#define EVP_CIPHER_CTX_get_app_data(e) ((e)->app_data)
#define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d))
#define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c))
#define EVP_CIPHER_CTX_flags(e) ((e)->cipher->flags)
#define EVP_CIPHER_CTX_mode(e) ((e)->cipher->flags & EVP_CIPH_MODE)
int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
@ -56,16 +74,14 @@ EVP_EncryptInit, EVP_EncryptUpdate, EVP_EncryptFinal - EVP cipher routines
The EVP cipher routines are a high level interface to certain
symmetric ciphers.
EVP_EncryptInit() initialises a cipher context B<ctx> for encryption
EVP_EncryptInit() initializes a cipher context B<ctx> for encryption
with cipher B<type>. B<type> is normally supplied by a function such
as EVP_des_cbc() . B<key> is the symmetric key to use and B<iv> is the
IV to use (if necessary), the actual number of bytes used for the
key and IV depends on the cipher. It is possible to set all parameters
to NULL except B<type> in an initial call and supply the remaining
parameters in subsequent calls. This is normally done when the
EVP_CIPHER_asn1_to_param() function is called to set the cipher
parameters from an ASN1 AlgorithmIdentifier and the key from a
different source.
parameters in subsequent calls, all of which have B<type> set to NULL.
This is done when the default cipher parameters are not appropriate.
EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and
writes the encrypted version to B<out>. This function can be called
@ -93,7 +109,8 @@ cipher block size is 1 in which case B<inl> bytes is sufficient.
EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal() are functions
that can be used for decryption or encryption. The operation performed
depends on the value of the B<enc> parameter. It should be set to 1 for
encryption and 0 for decryption.
encryption, 0 for decryption and -1 to leave the value unchanged (the
actual value of 'enc' being supplied in a previous call).
EVP_CIPHER_CTX_cleanup() clears all information from a cipher context.
It should be called after all operations using a cipher are complete
@ -111,7 +128,13 @@ IDENTIFIER.
EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length
for all ciphers.
for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a
given cipher, the value of EVP_CIPHER_CTX_key_length() may be different
for variable key length ciphers.
EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx.
If the cipher is a fixed length cipher then attempting to set the key
length to any value other than the fixed value is an error.
EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>.
@ -133,6 +156,11 @@ B<NID_undef>.
EVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed
an B<EVP_CIPHER_CTX> structure.
EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode:
EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE or
EVP_CIPH_OFB_MODE. If the cipher is a stream cipher then
EVP_CIPH_STREAM_CIPHER is returned.
EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based
on the passed cipher. This will typically include any parameters and an
IV. The cipher IV (if any) must be set when this call is made. This call
@ -149,21 +177,24 @@ key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally
EVP_CipherInit() again with all parameters except the key set to NULL. It is
possible for this function to fail if the cipher does not have any ASN1 support
or the parameters cannot be set (for example the RC2 effective key length
does not have an B<EVP_CIPHER> structure).
is not supported.
EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined
and set. Currently only the RC2 effective key length and the number of rounds of
RC5 can be set.
=head1 RETURN VALUES
EVP_EncryptInit(), EVP_EncryptUpdate() and EVP_EncryptFinal() do not return
values.
EVP_EncryptInit(), EVP_EncryptUpdate() and EVP_EncryptFinal() return 1 for success
and 0 for failure.
EVP_DecryptInit() and EVP_DecryptUpdate() do not return values.
EVP_DecryptInit() and EVP_DecryptUpdate() return 1 for success and 0 for failure.
EVP_DecryptFinal() returns 0 if the decrypt failed or 1 for success.
EVP_CipherInit() and EVP_CipherUpdate() do not return values.
EVP_CipherFinal() returns 1 for a decryption failure or 1 for success, if
the operation is encryption then it always returns 1.
EVP_CipherInit() and EVP_CipherUpdate() return 1 for success and 0 for failure.
EVP_CipherFinal() returns 1 for a decryption failure or 1 for success.
EVP_CIPHER_CTX_cleanup() does not return a value.
EVP_CIPHER_CTX_cleanup() returns 1 for success and 0 for failure.
EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
return an B<EVP_CIPHER> structure or NULL on error.
@ -187,6 +218,75 @@ EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure.
EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for
success or zero for failure.
=head1 CIPHER LISTING
All algorithms have a fixed key length unless otherwise stated.
=over 4
=item EVP_enc_null()
Null cipher: does nothing.
=item EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void)
DES in CBC, ECB, CFB and OFB modes respectively.
=item EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), EVP_des_ede_cfb(void)
Two key triple DES in CBC, ECB, CFB and OFB modes respectively.
=item EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void), EVP_des_ede3_cfb(void)
Three key triple DES in CBC, ECB, CFB and OFB modes respectively.
=item EVP_desx_cbc(void)
DESX algorithm in CBC mode.
=item EVP_rc4(void)
RC4 stream cipher. This is a variable key length cipher with default key length 128 bits.
=item EVP_rc4_40(void)
RC4 stream cipher with 40 bit key length. This is obsolete and new code should use EVP_rc4()
and the EVP_CIPHER_CTX_set_key_length() function.
=item EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void), EVP_idea_cbc(void)
IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
=item EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void)
RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
length cipher with an additional parameter called "effective key bits" or "effective key length".
By default both are set to 128 bits.
=item EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void)
RC2 algorithm in CBC mode with a default key length and effective key length of 40 and 64 bits.
These are obsolete and new code should use EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() and
EVP_CIPHER_CTX_ctrl() to set the key length and effective key length.
=item EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void);
Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
length cipher.
=item EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void)
CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
length cipher.
=item EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void)
RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length
cipher with an additional "number of rounds" parameter. By default the key length is set to 128
bits and 12 rounds.
=back
=head1 NOTES
Where possible the B<EVP> interface to symmetric ciphers should be used in
@ -206,14 +306,49 @@ test that the input data or key is correct. A random block has better than
1 in 256 chance of being of the correct format and problems with the
input data earlier on will not produce a final decrypt error.
The functions EVP_EncryptInit(), EVP_EncryptUpdate(), EVP_EncryptFinal(),
EVP_DecryptInit(), EVP_DecryptUpdate(), EVP_CipherInit() and EVP_CipherUpdate()
and EVP_CIPHER_CTX_cleanup() did not return errors in OpenSSL version 0.9.5a or
earlier. Software only versions of encryption algorithms will never return
error codes for these functions, unless there is a programming error (for example
and attempt to set the key before the cipher is set in EVP_EncryptInit() ).
=head1 BUGS
The current B<EVP> cipher interface is not as flexible as it should be. Only
certain "spot" encryption algorithms can be used for ciphers which have various
parameters associated with them (RC2, RC5 for example) this is inadequate.
For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is
a limitation of the current RC5 code rather than the EVP interface.
Several of the functions do not return error codes because the software versions
can never fail. This is not true of hardware versions.
It should be possible to disable PKCS padding: currently it isn't.
EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with
default key lengths. If custom ciphers exceed these values the results are
unpredictable. This is because it has become standard practice to define a
generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes.
The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested
for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode.
=head1 EXAMPLES
Get the number of rounds used in RC5:
int nrounds;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &i);
Get the RC2 effective key length:
int key_bits;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &i);
Set the number of rounds used in RC5:
int nrounds;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, i, NULL);
Set the number of rounds used in RC2:
int nrounds;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, i, NULL);
=head1 SEE ALSO

28
crypto/dist/openssl/doc/crypto/EVP_OpenInit.pod vendored
View File

@ -10,9 +10,9 @@ EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal - EVP envelope decryption
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 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 EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl);
=head1 DESCRIPTION
@ -21,7 +21,7 @@ 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
EVP_OpenInit() initializes a cipher context B<ctx> for decryption
with cipher B<type>. It decrypts the encrypted symmetric key of length
B<ekl> bytes passed in the B<ek> parameter using the private key B<priv>.
The IV is supplied in the B<iv> parameter.
@ -29,20 +29,32 @@ 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.
page.
=head1 NOTES
It is possible to call EVP_OpenInit() twice in the same way as
EVP_DecryptInit(). The first call should have B<priv> set to NULL
and (after setting any cipher parameters) it should be called again
with B<type> set to NULL.
If the cipher passed in the B<type> parameter is a variable length
cipher then the key length will be set to the value of the recovered
key length. If the cipher is a fixed length cipher then the recovered
key length must match the fixed cipher length.
=head1 RETURN VALUES
EVP_OpenInit() returns -1 on error or an non zero integer (actually the
EVP_OpenInit() returns 0 on error or a non zero integer (actually the
recovered secret key size) if successful.
EVP_SealUpdate() does not return a value.
EVP_OpenUpdate() returns 1 for success or 0 for failure.
EVP_SealFinal() returns 0 if the decrypt failed or 1 for success.
EVP_OpenFinal() returns 0 if the decrypt failed or 1 for success.
=head1 SEE ALSO
L<evp(3)|evp(3)>,L<rand(3)|rand(3)>
L<evp(3)|evp(3)>, L<rand(3)|rand(3)>,
L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,
L<EVP_SealInit(3)|EVP_SealInit(3)>

18
crypto/dist/openssl/doc/crypto/EVP_SealInit.pod vendored
View File

@ -10,9 +10,9 @@ EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption
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 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 EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl);
=head1 DESCRIPTION
@ -22,7 +22,7 @@ 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
EVP_SealInit() initializes a cipher context B<ctx> for encryption
with cipher B<type> using a random secret key and IV supplied in
the B<iv> parameter. B<type> is normally supplied by a function such
as EVP_des_cbc(). The secret key is encrypted using one or more public
@ -41,9 +41,10 @@ page.
=head1 RETURN VALUES
EVP_SealInit() returns -1 on error or B<npubk> if successful.
EVP_SealInit() returns 0 on error or B<npubk> if successful.
EVP_SealUpdate() and EVP_SealFinal() do not return values.
EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for
failure.
=head1 NOTES
@ -59,9 +60,14 @@ but symmetric encryption is fast. So symmetric encryption is used for
bulk encryption and the small random symmetric key used is transferred
using public key encryption.
It is possible to call EVP_SealInit() twice in the same way as
EVP_EncryptInit(). The first call should have B<npubk> set to 0
and (after setting any cipher parameters) it should be called again
with B<type> set to NULL.
=head1 SEE ALSO
L<evp(3)|evp(3)>,L<rand(3)|rand(3)>
L<evp(3)|evp(3)>, L<rand(3)|rand(3)>,
L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,
L<EVP_OpenInit(3)|EVP_OpenInit(3)>

6
crypto/dist/openssl/doc/crypto/EVP_SignInit.pod vendored
View File

@ -19,12 +19,12 @@ EVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions
The EVP signature routines are a high level interface to digital
signatures.
EVP_SignInit() initialises a signing context B<ctx> to using digest
EVP_SignInit() initializes a signing context B<ctx> to using digest
B<type>: this will typically be supplied by a function such as
EVP_sha1().
EVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the
signature context B<ctx>. This funtion can be called several times on the
signature context B<ctx>. This function can be called several times on the
same B<ctx> to include additional data.
EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey>
@ -32,7 +32,7 @@ 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
EVP_SignUpdate() can be made, but EVP_SignInit() can be called to initialize
a new signature operation.
EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual

7
crypto/dist/openssl/doc/crypto/EVP_VerifyInit.pod vendored
View File

@ -17,17 +17,17 @@ EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification f
The EVP signature verification routines are a high level interface to digital
signatures.
EVP_VerifyInit() initialises a verification context B<ctx> to using digest
EVP_VerifyInit() initializes a verification context B<ctx> to using digest
B<type>: this will typically be supplied by a function such as EVP_sha1().
EVP_VerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
verification context B<ctx>. This funtion can be called several times on the
verification context B<ctx>. This function can be called several times on the
same B<ctx> to include additional data.
EVP_VerifyFinal() verifies the data in B<ctx> using the public key B<pkey>
and against the B<siglen> bytes at B<sigbuf>. After calling EVP_VerifyFinal()
no additional calls to EVP_VerifyUpdate() can be made, but EVP_VerifyInit()
can be called to initialiase a new verification operation.
can be called to initialize a new verification operation.
=head1 RETURN VALUES
@ -57,6 +57,7 @@ might.
=head1 SEE ALSO
L<evp(3)|evp(3)>,
L<EVP_SignInit(3)|EVP_SignInit(3)>,
L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>,
L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,

46
crypto/dist/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod vendored
View File

@ -2,7 +2,7 @@
=head1 NAME
OPENSSL_VERSION_NUMBER, SSLeay - get OpenSSL version number
OPENSSL_VERSION_NUMBER, SSLeay SSLeay_version - get OpenSSL version number
=head1 SYNOPSIS
@ -11,11 +11,27 @@ OPENSSL_VERSION_NUMBER, SSLeay - get OpenSSL version number
#include <openssl/crypto.h>
long SSLeay(void);
char *SSLeay_version(int t);
=head1 DESCRIPTION
OPENSSL_VERSION_NUMBER is a numeric release version identifier:
MMNNFFPPS: major minor fix patch status
The status nibble has one of the values 0 for development, 1 to e for betas
1 to 14, and f for release.
for example
0x000906000 == 0.9.6 dev
0x000906023 == 0.9.6b beta 3
0x00090605f == 0.9.6e release
Versions prior to 0.9.3 have identifiers E<lt> 0x0930.
Versions between 0.9.3 and 0.9.5 had a version identifier with this
interpretation:
MMNNFFRBB major minor fix final beta/patch
for example
@ -23,13 +39,39 @@ for example
0x000904100 == 0.9.4 release
0x000905000 == 0.9.5 dev
Versions prior to 0.9.3 have identifiers E<lt> 0x0930.
Version 0.9.5a had an interim interpretation that is like the current one,
except the patch level got the highest bit set, to keep continuity. The
number was therefore 0x0090581f.
For backward compatibility, SSLEAY_VERSION_NUMBER is also defined.
SSLeay() returns this number. The return value can be compared to the
macro to make sure that the correct version of the library has been
loaded, especially when using DLLs on Windows systems.
SSLeay_version() returns different strings depending on B<t>:
=over 4
=item SSLEAY_VERSION
The text variant of the version number and the release date. For example,
"OpenSSL 0.9.5a 1 Apr 2000".
=item SSLEAY_CFLAGS
The flags given to the C compiler when compiling OpenSSL are returned in a
string.
=item SSLEAY_PLATFORM
The platform name used when OpenSSL was configured is returned.
=back
If the data request isn't available, a text saying that the information is
not available is returned.
For an unknown B<t>, the text "not available" is returned.
=head1 RETURN VALUE
The version number.

5
crypto/dist/openssl/doc/crypto/OpenSSL_add_all_algorithms.pod vendored
View File

@ -2,7 +2,8 @@
=head1 NAME
OpenSSL_add_all_algorithms() - add algorithms to internal table
OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests -
add algorithms to internal table
=head1 SYNOPSIS
@ -43,7 +44,7 @@ by EVP_sha1(). It just needs to add them if it (or any of the functions it calls
needs to lookup algorithms.
The cipher and digest lookup functions are used in many parts of the library. If
the table is not initialised several functions will misbehave and complain they
the table is not initialized several functions will misbehave and complain they
cannot find algorithms. This includes the PEM, PKCS#12, SSL and S/MIME libraries.
This is a common query in the OpenSSL mailing lists.

37
crypto/dist/openssl/doc/crypto/RAND_egd.pod vendored
View File

@ -9,10 +9,30 @@ RAND_egd - query entropy gathering daemon
#include <openssl/rand.h>
int RAND_egd(const char *path);
int RAND_egd_bytes(const char *path, int bytes);
=head1 DESCRIPTION
RAND_egd() queries the entropy gathering daemon EGD on socket B<path>.
It queries 255 bytes and uses L<RAND_add(3)|RAND_add(3)> to seed the
OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for
RAND_egd_bytes(path, 255);
RAND_egd_bytes() queries the entropy gathering daemon EGD on socket B<path>.
It queries B<bytes> bytes and uses L<RAND_add(3)|RAND_add(3)> to seed the
OpenSSL built-in PRNG.
This function is more flexible than RAND_egd().
When only one secret key must
be generated, it is not necessary to request the full amount 255 bytes from
the EGD socket. This can be advantageous, since the amount of entropy
that can be retrieved from EGD over time is limited.
=head1 NOTES
On systems without /dev/*random devices providing entropy from the kernel,
the EGD entropy gathering daemon can be used to collect entropy. It provides
a socket interface through which entropy can be gathered in chunks up to
255 bytes. Several chunks can be queried during one connection.
EGD is available from http://www.lothar.com/tech/crypto/ (C<perl
Makefile.PL; make; make install> to install). It is run as B<egd>
@ -21,18 +41,27 @@ RAND_egd() is called with that path as an argument, it tries to read
random bytes that EGD has collected. The read is performed in
non-blocking mode.
Alternatively, the EGD-interface compatible daemon PRNGD can be used. It is
available from
http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html .
PRNGD does employ an internal PRNG itself and can therefore never run
out of entropy.
=head1 RETURN VALUE
RAND_egd() returns the number of bytes read from the daemon on
success, and -1 if the connection failed or the daemon did not return
enough data to fully seed the PRNG.
RAND_egd() and RAND_egd_bytes() return the number of bytes read from the
daemon on success, and -1 if the connection failed or the daemon did not
return enough data to fully seed the PRNG.
=head1 SEE ALSO
L<rand(3)|rand(3)>, L<RAND_add(3)|RAND_add(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)>
L<rand(3)|rand(3)>, L<RAND_add(3)|RAND_add(3)>,
L<RAND_cleanup(3)|RAND_cleanup(3)>
=head1 HISTORY
RAND_egd() is available since OpenSSL 0.9.5.
RAND_egd_bytes() is available since OpenSSL 0.9.6.
=cut

2
crypto/dist/openssl/doc/crypto/RAND_load_file.pod vendored
View File

@ -8,7 +8,7 @@ RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file
#include <openssl/rand.h>
const char *RAND_file_name(char *buf, int num);
const char *RAND_file_name(char *buf, size_t num);
int RAND_load_file(const char *filename, long max_bytes);

14
crypto/dist/openssl/doc/crypto/RSA_get_ex_new_index.pod vendored
View File

@ -17,14 +17,12 @@ RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application specifi
void *RSA_get_ex_data(RSA *r, int idx);
int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
int idx, long argl, void *argp);
typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
int idx, long argl, void *argp);
=head1 DESCRIPTION

5
crypto/dist/openssl/doc/crypto/RSA_print.pod vendored
View File

@ -2,8 +2,9 @@
=head1 NAME
RSA_print, RSA_print_fp, DHparams_print, DHparams_print_fp - print
cryptographic parameters
RSA_print, RSA_print_fp, DHparams_print, DHparams_print_fp, DSA_print,
DSA_print_fp, DHparams_print, DHparams_print_fp - print cryptographic
parameters
=head1 SYNOPSIS

2
crypto/dist/openssl/doc/crypto/RSA_public_encrypt.pod vendored
View File

@ -47,7 +47,7 @@ Encrypting user data directly with RSA is insecure.
=back
B<flen> must be less than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5
based padding modes, and less than RSA_size(B<rsa>) - 21 for
based padding modes, and less than RSA_size(B<rsa>) - 41 for
RSA_PKCS1_OAEP_PADDING. The random number generator must be seeded
prior to calling RSA_public_encrypt().

2
crypto/dist/openssl/doc/crypto/RSA_set_method.pod vendored
View File

@ -4,7 +4,7 @@
RSA_set_default_method, RSA_get_default_method, RSA_set_method,
RSA_get_method, RSA_PKCS1_SSLeay, RSA_PKCS1_RSAref,
RSA_PKCS1_null_method, RSA_flags, RSA_new_method - select RSA method
RSA_null_method, RSA_flags, RSA_new_method - select RSA method
=head1 SYNOPSIS

54
crypto/dist/openssl/doc/crypto/bio.pod vendored Normal file
View File

@ -0,0 +1,54 @@
=pod
=head1 NAME
bio - I/O abstraction
=head1 SYNOPSIS
#include <openssl/bio.h>
TBA
=head1 DESCRIPTION
A BIO is an I/O abstraction, it hides many of the underlying I/O
details from an application. If an application uses a BIO for its
I/O it can transparently handle SSL connections, unencrypted network
connections and file I/O.
There are two type of BIO, a source/sink BIO and a filter BIO.
As its name implies a source/sink BIO is a source and/or sink of data,
examples include a socket BIO and a file BIO.
A filter BIO takes data from one BIO and passes it through to
another, or the application. The data may be left unmodified (for
example a message digest BIO) or translated (for example an
encryption BIO). The effect of a filter BIO may change according
to the I/O operation it is performing: for example an encryption
BIO will encrypt data if it is being written to and decrypt data
if it is being read from.
BIOs can be joined together to form a chain (a single BIO is a chain
with one component). A chain normally consist of one source/sink
BIO and one or more filter BIOs. Data read from or written to the
first BIO then traverses the chain to the end (normally a source/sink
BIO).
=head1 SEE ALSO
L<BIO_ctrl(3)|BIO_ctrl(3)>,
L<BIO_f_base64(3)|BIO_f_base64(3)>,
L<BIO_f_cipher(3)|BIO_f_cipher(3)>, L<BIO_f_md(3)|BIO_f_md(3)>,
L<BIO_f_null(3)|BIO_f_null(3)>, L<BIO_f_ssl(3)|BIO_f_ssl(3)>,
L<BIO_find_type(3)|BIO_find_type(3)>, L<BIO_new(3)|BIO_new(3)>,
L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)>,
L<BIO_push(3)|BIO_push(3)>, L<BIO_read(3)|BIO_read(3)>,
L<BIO_s_accept(3)|BIO_s_accept(3)>, L<BIO_s_bio(3)|BIO_s_bio(3)>,
L<BIO_s_connect(3)|BIO_s_connect(3)>, L<BIO_s_fd(3)|BIO_s_fd(3)>,
L<BIO_s_file(3)|BIO_s_file(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>,
L<BIO_s_null(3)|BIO_s_null(3)>, L<BIO_s_socket(3)|BIO_s_socket(3)>,
L<BIO_set_callback(3)|BIO_set_callback(3)>,
L<BIO_should_retry(3)|BIO_should_retry(3)>

39
crypto/dist/openssl/doc/crypto/blowfish.pod vendored
View File

@ -11,9 +11,6 @@ BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption
void BF_set_key(BF_KEY *key, int len, const unsigned char *data);
void BF_encrypt(BF_LONG *data,const BF_KEY *key);
void BF_decrypt(BF_LONG *data,const BF_KEY *key);
void BF_ecb_encrypt(const unsigned char *in, unsigned char *out,
BF_KEY *key, int enc);
void BF_cbc_encrypt(const unsigned char *in, unsigned char *out,
@ -25,10 +22,13 @@ BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption
long length, BF_KEY *schedule, unsigned char *ivec, int *num);
const char *BF_options(void);
void BF_encrypt(BF_LONG *data,const BF_KEY *key);
void BF_decrypt(BF_LONG *data,const BF_KEY *key);
=head1 DESCRIPTION
This library implements the Blowfish cipher, which is invented and described
by Counterpane (see http://www.counterpane.com/blowfish/ ).
by Counterpane (see http://www.counterpane.com/blowfish.html ).
Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data.
It uses a variable size key, but typically, 128 bit (16 byte) keys are
@ -43,11 +43,6 @@ phase.
BF_set_key() sets up the B<BF_KEY> B<key> using the B<len> bytes long key
at B<data>.
BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish
encryption. They encrypt/decrypt the first 64 bits of the vector pointed by
B<data>, using the key B<key>. These functions should not be used unless you
implement 'modes' of Blowfish.
BF_ecb_encrypt() is the basic Blowfish encryption and decryption function.
It encrypts or decrypts the first 64 bits of B<in> using the key B<key>,
putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>)
@ -56,37 +51,45 @@ B<in> and B<out> must be 64 bits in length, no less. If they are larger,
everything after the first 64 bits is ignored.
The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt()
all operate on variable length data. They all take an initialisation vector
all operate on variable length data. They all take an initialization vector
B<ivec> which needs to be passed along into the next call of the same function
for the same message. B<ivec> may be initialised with anything, but the
recipient needs to know what it was initialised with, or it won't be able
for the same message. B<ivec> may be initialized with anything, but the
recipient needs to know what it was initialized with, or it won't be able
to decrypt. Some programs and protocols simplify this, like SSH, where
B<ivec> is simply initialised to zero.
B<ivec> is simply initialized to zero.
BF_cbc_encrypt() operates of data that is a multiple of 8 bytes long, while
BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt an variable
number of bytes (the amount does not have to be an exact multiple of 8). The
purpose of the latter two is to simulate stream ciphers, and therefore, they
need the parameter B<num>, which is a pointer to an integer where the current
offset in B<ivec> is stored between calls. This integer must be initialised
to zero when B<ivec> is initialised.
offset in B<ivec> is stored between calls. This integer must be initialized
to zero when B<ivec> is initialized.
BF_cbc_encrypt() is the Cipher Block Chaining function for Blowfish. It
encrypts or decrypts the 64 bits chunks of B<in> using the key B<schedule>,
putting the result in B<out>. B<enc> decides if encryption (BF_ENCRYPT) or
decryption (BF_DECRYPT) shall be performed. B<ivec> must point at an 8 byte
long initialisation vector.
long initialization vector.
BF_cfb64_encrypt() is the CFB mode for Blowfish with 64 bit feedback.
It encrypts or decrypts the bytes in B<in> using the key B<schedule>,
putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>)
or decryption (B<BF_DECRYPT>) shall be performed. B<ivec> must point at an
8 byte long initialisation vector. B<num> must point at an integer which must
8 byte long initialization vector. B<num> must point at an integer which must
be initially zero.
BF_ofb64_encrypt() is the OFB mode for Blowfish with 64 bit feedback.
It uses the same parameters as BF_cfb64_encrypt(), which must be initialised
It uses the same parameters as BF_cfb64_encrypt(), which must be initialized
the same way.
BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish
encryption. They encrypt/decrypt the first 64 bits of the vector pointed by
B<data>, using the key B<key>. These functions should not be used unless you
implement 'modes' of Blowfish. The alternative is to use BF_ecb_encrypt().
If you still want to use these functions, you should be aware that they take
each 32-bit chunk in host-byte order, which is little-endian on little-endian
platforms and big-endian on big-endian ones.
=head1 RETURN VALUES
None of the functions presented here return any value.

1
crypto/dist/openssl/doc/crypto/bn.pod vendored
View File

@ -60,6 +60,7 @@ bn - multiprecision integer arithmetics
int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
BIGNUM *BN_generate_prime(BIGNUM *ret, int bits,int safe, BIGNUM *add,
BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg);

2
crypto/dist/openssl/doc/crypto/bn_internal.pod vendored
View File

@ -149,7 +149,7 @@ word array B<a>, the B<nb> word array B<b> and the B<na>+B<nb> word
array B<r>. It computes B<a>*B<b> and places the result in B<r>.
bn_mul_low_normal(B<r>, B<a>, B<b>, B<n>) operates on the B<n> word
arrays B<r>, B<a> und B<b>. It computes the B<n> low words of
arrays B<r>, B<a> and B<b>. It computes the B<n> low words of
B<a>*B<b> and places the result in B<r>.
bn_mul_recursive(B<r>, B<a>, B<b>, B<n2>, B<t>) operates on the B<n2>

6
crypto/dist/openssl/doc/crypto/buffer.pod vendored
View File

@ -46,11 +46,11 @@ size.
BUF_strdup() copies a null terminated string into a block of allocated
memory and returns a pointer to the allocated block.
Unlike the standard C library strdup() this function uses Malloc() and so
Unlike the standard C library strdup() this function uses OPENSSL_malloc() and so
should be used in preference to the standard library strdup() because it can
be used for memory leak checking or replacing the malloc() function.
The memory allocated from BUF_strdup() should be freed up using the Free()
The memory allocated from BUF_strdup() should be freed up using the OPENSSL_free()
function.
=head1 RETURN VALUES
@ -68,6 +68,6 @@ L<bio(3)|bio(3)>
=head1 HISTORY
BUF_MEM_new(), BUF_MEM_free() and BUF_MEM_grow() are available in all
versions of SSLeay and OpenSSL. BUF_strdup() was addded in SSLeay 0.8.
versions of SSLeay and OpenSSL. BUF_strdup() was added in SSLeay 0.8.
=cut

5
crypto/dist/openssl/doc/crypto/crypto.pod vendored
View File

@ -40,8 +40,9 @@ L<x509(3)|x509(3)>, L<x509v3(3)|x509v3(3)>
=item AUTHENTICATION CODES, HASH FUNCTIONS
L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>,
L<ripemd(3)|ripemd(3)>, L<sha(3)|sha(3)>
L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, L<md4(3)|md4(3)>,
L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>,
L<sha(3)|sha(3)>
=item AUXILIARY FUNCTIONS

12
crypto/dist/openssl/doc/crypto/des.pod vendored
View File

@ -130,7 +130,7 @@ 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
architecture dependent I<des_key_schedule> via the
des_set_key_checked() or des_set_key_unchecked() function.
des_set_key_checked() will check that the key passed is of odd parity
@ -200,7 +200,7 @@ 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
chaining mode used by Kerberos v4. Its parameters are the same as
des_ncbc_encrypt().
des_cfb_encrypt() encrypt/decrypts using cipher feedback mode. This
@ -241,7 +241,7 @@ 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
standard output, turns echo off and reads in input string from the
terminal. The string is returned in I<buf>, which must have space for
at least I<length> bytes. If I<verify> is set, the user is asked for
the password twice and unless the two copies match, an error is
@ -268,9 +268,9 @@ 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:
The following are DES-based transformations:
des_fcrypt() is a fast version of the unix crypt(3) function. This
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
@ -345,7 +345,7 @@ 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)>
crypt(3), L<des_modes(7)|des_modes(7)>, L<evp(3)|evp(3)>, L<rand(3)|rand(3)>
=head1 HISTORY

2
crypto/dist/openssl/doc/crypto/err.pod vendored
View File

@ -143,7 +143,7 @@ The closing #endif etc will be automatically added by the script.
The generated C error code file B<xxx_err.c> will load the header
files B<stdio.h>, B<openssl/err.h> and B<openssl/xxx.h> so the
header file must load any additional header files containg any
header file must load any additional header files containing any
definitions it uses.
=head1 USING ERROR CODES IN EXTERNAL LIBRARIES

37
crypto/dist/openssl/doc/crypto/evp.pod vendored Normal file
View File

@ -0,0 +1,37 @@
=pod
=head1 NAME
evp - high-level cryptographic functions
=head1 SYNOPSIS
#include <openssl/evp.h>
=head1 DESCRIPTION
The EVP library provides a high-level interface to cryptographic
functions.
B<EVP_Seal>I<...> and B<EVP_Open>I<...> provide public key encryption
and decryption to implement digital "envelopes".
The B<EVP_Sign>I<...> and B<EVP_Verify>I<...> functions implement
digital signatures.
Symmetric encryption is available with the B<EVP_Encrypt>I<...>
functions. The B<EVP_Digest>I<...> functions provide message digests.
Algorithms are loaded with OpenSSL_add_all_algorithms(3).
=head1 SEE ALSO
L<EVP_DigestInit(3)|EVP_DigestInit(3)>,
L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,
L<EVP_OpenInit(3)|EVP_OpenInit(3)>,
L<EVP_SealInit(3)|EVP_SealInit(3)>,
L<EVP_SignInit(3)|EVP_SignInit(3)>,
L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>,
L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>
=cut

3
crypto/dist/openssl/doc/crypto/hmac.pod vendored
View File

@ -2,7 +2,8 @@
=head1 NAME
HMAC, HMAC_Init, HMAC_Update, HMAC_Final - HMAC message authentication code
HMAC, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_cleanup - HMAC message
authentication code
=head1 SYNOPSIS

2
crypto/dist/openssl/doc/crypto/lhash.pod vendored
View File

@ -102,7 +102,7 @@ The following description is based on the SSLeay documentation:
The B<lhash> library implements a hash table described in the
I<Communications of the ACM> in 1991. What makes this hash table
different is that as the table fills, the hash table is increased (or
decreased) in size via Realloc(). When a 'resize' is done, instead of
decreased) in size via OPENSSL_realloc(). When a 'resize' is done, instead of
all hashes being redistributed over twice as many 'buckets', one
bucket is split. So when an 'expand' is done, there is only a minimal
cost to redistribute some values. Subsequent inserts will cause more

44
crypto/dist/openssl/doc/crypto/md5.pod vendored
View File

@ -2,8 +2,8 @@
=head1 NAME
MD2, MD5, MD2_Init, MD2_Update, MD2_Final, MD5_Init, MD5_Update,
MD5_Final - MD2 and MD5 hash functions
MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update,
MD4_Final, MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions
=head1 SYNOPSIS
@ -18,6 +18,17 @@ MD5_Final - MD2 and MD5 hash functions
void MD2_Final(unsigned char *md, MD2_CTX *c);
#include <openssl/md4.h>
unsigned char *MD4(const unsigned char *d, unsigned long n,
unsigned char *md);
void MD4_Init(MD4_CTX *c);
void MD4_Update(MD4_CTX *c, const void *data,
unsigned long len);
void MD4_Final(unsigned char *md, MD4_CTX *c);
#include <openssl/md5.h>
unsigned char *MD5(const unsigned char *d, unsigned long n,
@ -30,12 +41,13 @@ MD5_Final - MD2 and MD5 hash functions
=head1 DESCRIPTION
MD2 and MD5 are cryptographic hash functions with a 128 bit output.
MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output.
MD2() and MD5() compute the MD2 and MD5 message digest of the B<n>
bytes at B<d> and place it in B<md> (which must have space for
MD2_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16 bytes of output). If
B<md> is NULL, the digest is placed in a static array.
MD2(), MD4(), and MD5() compute the MD2, MD4, and MD5 message digest
of the B<n> bytes at B<d> and place it in B<md> (which must have space
for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16
bytes of output). If B<md> is NULL, the digest is placed in a static
array.
The following functions may be used if the message is not completely
stored in memory:
@ -48,8 +60,8 @@ be hashed (B<len> bytes at B<data>).
MD2_Final() places the message digest in B<md>, which must have space
for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MD2_CTX>.
MD5_Init(), MD5_Update() and MD5_Final() are analogous using an
B<MD5_CTX> structure.
MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and
MD5_Final() are analogous using an B<MD4_CTX> and B<MD5_CTX> structure.
Applications should use the higher level functions
L<EVP_DigestInit(3)|EVP_DigestInit(3)>
@ -57,20 +69,21 @@ etc. instead of calling the hash functions directly.
=head1 NOTE
MD2 and MD5 are recommended only for compatibility with existing
MD2, MD4, and MD5 are recommended only for compatibility with existing
applications. In new applications, SHA-1 or RIPEMD-160 should be
preferred.
=head1 RETURN VALUES
MD2() and MD5() return pointers to the hash value.
MD2(), MD4(), and MD5() return pointers to the hash value.
MD2_Init(), MD2_Update() MD2_Final(), MD5_Init(), MD5_Update() and
MD5_Final() do not return values.
MD2_Init(), MD2_Update(), MD2_Final(), MD4_Init(), MD4_Update(),
MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() do not return
values.
=head1 CONFORMING TO
RFC 1319, RFC 1321
RFC 1319, RFC 1320, RFC 1321
=head1 SEE ALSO
@ -82,4 +95,7 @@ MD2(), MD2_Init(), MD2_Update() MD2_Final(), MD5(), MD5_Init(),
MD5_Update() and MD5_Final() are available in all versions of SSLeay
and OpenSSL.
MD4(), MD4_Init(), and MD4_Update() are available in OpenSSL 0.9.6 and
above.
=cut

12
crypto/dist/openssl/doc/crypto/rand.pod vendored
View File

@ -8,17 +8,17 @@ rand - pseudo-random number generator
#include <openssl/rand.h>
int RAND_bytes(unsigned char *buf,int num);
int RAND_pseudo_bytes(unsigned char *buf,int num);
int RAND_bytes(unsigned char *buf, int num);
int RAND_pseudo_bytes(unsigned char *buf, int num);
void RAND_seed(const void *buf,int num);
void RAND_add(const void *buf,int num,int entropy);
void RAND_seed(const void *buf, int num);
void RAND_add(const void *buf, int num, int entropy);
int RAND_status(void);
void RAND_screen(void);
int RAND_load_file(const char *file,long max_bytes);
int RAND_load_file(const char *file, long max_bytes);
int RAND_write_file(const char *file);
const char *RAND_file_name(char *file,int num);
const char *RAND_file_name(char *file, size_t num);
int RAND_egd(const char *path);

2
crypto/dist/openssl/doc/crypto/rsa.pod vendored
View File

@ -96,7 +96,7 @@ SSL, PKCS #1 v2.0
=head1 PATENTS
RSA is covered by a US patent which expires in September 2000.
RSA was covered by a US patent which expired in September 2000.
=head1 SEE ALSO

92
crypto/dist/openssl/doc/crypto/threads.pod vendored
View File

@ -2,7 +2,10 @@
=head1 NAME
CRYPTO_set_locking_callback, CRYPTO_set_id_callback - OpenSSL thread support
CRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks,
CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback,
CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid,
CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support
=head1 SYNOPSIS
@ -15,13 +18,42 @@ CRYPTO_set_locking_callback, CRYPTO_set_id_callback - OpenSSL thread support
int CRYPTO_num_locks(void);
/* struct CRYPTO_dynlock_value needs to be defined by the user */
struct CRYPTO_dynlock_value;
void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value *
(*dyn_create_function)(char *file, int line));
void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function)
(int mode, struct CRYPTO_dynlock_value *l,
const char *file, int line));
void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function)
(struct CRYPTO_dynlock_value *l, const char *file, int line));
int CRYPTO_get_new_dynlockid(void);
void CRYPTO_destroy_dynlockid(int i);
void CRYPTO_lock(int mode, int n, const char *file, int line);
#define CRYPTO_w_lock(type) \
CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
#define CRYPTO_w_unlock(type) \
CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
#define CRYPTO_r_lock(type) \
CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__)
#define CRYPTO_r_unlock(type) \
CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__)
#define CRYPTO_add(addr,amount,type) \
CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__)
=head1 DESCRIPTION
OpenSSL can safely be used in multi-threaded applications provided
that two callback functions are set.
that at least two callback functions are set.
locking_function(int mode, int n, const char *file, int line) is
needed to perform locking on shared data stuctures. Multi-threaded
needed to perform locking on shared data structures. Multi-threaded
applications will crash at random if it is not set.
locking_function() must be able to handle up to CRYPTO_num_locks()
@ -35,9 +67,59 @@ id_function(void) is a function that returns a thread ID. It is not
needed on Windows nor on platforms where getpid() returns a different
ID for each thread (most notably Linux).
Additionally, OpenSSL supports dynamic locks, and sometimes, some parts
of OpenSSL need it for better performance. To enable this, the following
is required:
=over 4
=item *
Three additional callback function, dyn_create_function, dyn_lock_function
and dyn_destroy_function.
=item *
A structure defined with the data that each lock needs to handle.
=back
struct CRYPTO_dynlock_value has to be defined to contain whatever structure
is needed to handle locks.
dyn_create_function(const char *file, int line) is needed to create a
lock. Multi-threaded applications might crash at random if it is not set.
dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line)
is needed to perform locking off dynamic lock numbered n. Multi-threaded
applications might crash at random if it is not set.
dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is
needed to destroy the lock l. Multi-threaded applications might crash at
random if it is not set.
CRYPTO_get_new_dynlockid() is used to create locks. It will call
dyn_create_function for the actual creation.
CRYPTO_destroy_dynlockid() is used to destroy locks. It will call
dyn_destroy_function for the actual destruction.
CRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield
describing what should be done with the lock. n is the number of the
lock as returned from CRYPTO_get_new_dynlockid(). mode can be combined
from the following values. These values are pairwise exclusive, with
undefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE
should not be used together):
CRYPTO_LOCK 0x01
CRYPTO_UNLOCK 0x02
CRYPTO_READ 0x04
CRYPTO_WRITE 0x08
=head1 RETURN VALUES
CRYPTO_num_locks() returns the required number of locks.
CRYPTO_get_new_dynlockid() returns the index to the newly created lock.
The other functions return no values.
=head1 NOTE
@ -52,6 +134,9 @@ You can find out if OpenSSL was configured with thread support:
// no thread support
#endif
Also, dynamic locks are currently not used internally by OpenSSL, but
may do so in the future.
=head1 EXAMPLES
B<crypto/threads/mttest.c> shows examples of the callback functions on
@ -62,6 +147,7 @@ Solaris, Irix and Win32.
CRYPTO_set_locking_callback() and CRYPTO_set_id_callback() are
available in all versions of SSLeay and OpenSSL.
CRYPTO_num_locks() was added in OpenSSL 0.9.4.
All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev.
=head1 SEE ALSO

59
crypto/dist/openssl/doc/openssl.txt vendored
View File

@ -355,6 +355,24 @@ that would not make sense. It does support an additional issuer:copy option
that will copy all the subject alternative name values from the issuer
certificate (if possible).
Example:
issuserAltName = issuer:copy
Authority Info Access.
The authority information access extension gives details about how to access
certain information relating to the CA. Its syntax is accessOID;location
where 'location' has the same syntax as subject alternative name (except
that email:copy is not supported). accessOID can be any valid OID but only
certain values are meaningful for example OCSP and caIssuers. OCSP gives the
location of an OCSP responder: this is used by Netscape PSM and other software.
Example:
authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
CRL distribution points.
This is a multi-valued extension that supports all the literal options of
@ -489,6 +507,47 @@ details about the structures returned. The returned structure should be freed
after use using the relevant free function, BASIC_CONSTRAINTS_free() for
example.
void * X509_get_ext_d2i(X509 *x, int nid, int *crit, int *idx);
void * X509_CRL_get_ext_d2i(X509_CRL *x, int nid, int *crit, int *idx);
void * X509_REVOKED_get_ext_d2i(X509_REVOKED *x, int nid, int *crit, int *idx);
void * X509V3_get_d2i(STACK_OF(X509_EXTENSION) *x, int nid, int *crit, int *idx);
These functions combine the operations of searching for extensions and
parsing them. They search a certificate, a CRL a CRL entry or a stack
of extensions respectively for extension whose NID is 'nid' and return
the parsed result of NULL if an error occurred. For example:
BASIC_CONSTRAINTS *bs;
bs = X509_get_ext_d2i(cert, NID_basic_constraints, NULL, NULL);
This will search for the basicConstraints extension and either return
it value or NULL. NULL can mean either the extension was not found, it
occurred more than once or it could not be parsed.
If 'idx' is NULL then an extension is only parsed if it occurs precisely
once. This is standard behaviour because extensions normally cannot occur
more than once. If however more than one extension of the same type can
occur it can be used to parse successive extensions for example:
int i;
void *ext;
i = -1;
for(;;) {
ext = X509_get_ext_d2i(x, nid, crit, &idx);
if(ext == NULL) break;
/* Do something with ext */
}
If 'crit' is not NULL and the extension was found then the int it points to
is set to 1 for critical extensions and 0 for non critical. Therefore if the
function returns NULL but 'crit' is set to 0 or 1 then the extension was
found but it could not be parsed.
The int pointed to by crit will be set to -1 if the extension was not found
and -2 if the extension occurred more than once (this will only happen if
idx is NULL). In both cases the function will return NULL.
3. Generating extensions.
An extension will typically be generated from a configuration file, or some

112
crypto/dist/openssl/doc/ssl/SSL_CIPHER_get_name.pod vendored Normal file
View File

@ -0,0 +1,112 @@
=pod
=head1 NAME
SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description - get SSL_CIPHER properties
=head1 SYNOPSIS
#include <openssl/ssl.h>
const char *SSL_CIPHER_get_name(SSL_CIPHER *cipher);
int SSL_CIPHER_get_bits(SSL_CIPHER *cipher, int *alg_bits);
char *SSL_CIPHER_get_version(SSL_CIPHER *cipher);
char *SSL_CIPHER_description(SSL_CIPHER *cipher, char *buf, int size);
=head1 DESCRIPTION
SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the
argument is the NULL pointer, a pointer to the constant value "NONE" is
returned.
SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>. If
B<alg_bits> is not NULL, it contains the number of bits processed by the
chosen algorithm. If B<cipher> is NULL, 0 is returned.
SSL_CIPHER_get_version() returns the protocol version for B<cipher>, currently
"SSLv2", "SSLv3", or "TLSv1". If B<cipher> is NULL, "(NONE)" is returned.
SSL_CIPHER_description() returns a textual description of the cipher used
into the buffer B<buf> of length B<len> provided. B<len> must be at least
128 bytes, otherwise a pointer to the the string "Buffer too small" is
returned. If B<buf> is NULL, a buffer of 128 bytes is allocated using
OPENSSL_malloc(). If the allocation fails, a pointer to the string
"OPENSSL_malloc Error" is returned.
=head1 NOTES
The number of bits processed can be different from the secret bits. An
export cipher like e.g. EXP-RC4-MD5 has only 40 secret bits. The algorithm
does use the full 128 bits (which would be returned for B<alg_bits>), of
which however 88bits are fixed. The search space is hence only 40 bits.
The string returned by SSL_CIPHER_description() in case of success consists
of cleartext information separated by one or more blanks in the following
sequence:
=over 4
=item <ciphername>
Textual representation of the cipher name.
=item <protocol version>
Protocol version: B<SSLv2>, B<SSLv3>. The TLSv1 ciphers are flagged with SSLv3.
=item Kx=<key exchange>
Key exchange method: B<RSA> (for export ciphers as B<RSA(512)> or
B<RSA(1024)>), B<DH> (for export ciphers as B<DH(512)> or B<DH(1024)>),
B<DH/RSA>, B<DH/DSS>, B<Fortezza>.
=item Au=<authentication>
Authentication method: B<RSA>, B<DSS>, B<DH>, B<None>. None is the
representation of anonymous ciphers.
=item Enc=<symmetric encryption method>
Encryption method with number of secret bits: B<DES(40)>, B<DES(56)>,
B<3DES(168)>, B<RC4(40)>, B<RC4(56)>, B<RC4(64)>, B<RC4(128)>,
B<RC2(40)>, B<RC2(56)>, B<RC2(128)>, B<IDEA(128)>, B<Fortezza>, B<None>.
=item Mac=<message authentication code>
Message digest: B<MD5>, B<SHA1>.
=item <export flag>
If the cipher is flagged exportable with respect to old US crypto
regulations, the word "B<export>" is printed.
=back
=head1 EXAMPLES
Some examples for the output of SSL_CIPHER_description():
EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1
EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1
RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5
EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
=head1 BUGS
If SSL_CIPHER_description() is called with B<cipher> being NULL, the
library crashes.
If SSL_CIPHER_description() cannot handle a built-in cipher, the according
description of the cipher property is B<unknown>. This case should not
occur.
=head1 RETURN VALUES
See DESCRIPTION
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_get_current_cipher(3)|SSL_get_current_cipher(3)>,
L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, L<ciphers(1)|ciphers(1)>
=cut

38
crypto/dist/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod vendored Normal file
View File

@ -0,0 +1,38 @@
=pod
=head1 NAME
SSL_CTX_add_extra_chain_cert - add certificate to chain
=head1 SYNOPSIS
#include <openssl/ssl.h>
long SSL_CTX_add_extra_chain_cert(SSL_CTX ctx, X509 *x509)
=head1 DESCRIPTION
SSL_CTX_add_extra_chain_cert() adds the certificate B<x509> to the certificate
chain presented together with the certificate. Several certificates
can be added one after the other.
=head1 NOTES
When constructing the certificate chain, the chain will be formed from
these certificates explicitly specified. If no chain is specified,
the library will try to complete the chain from the available CA
certificates in the trusted CA storage, see
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>.
=head1 RETURN VALUES
SSL_CTX_add_extra_chain_cert() returns 1 on success. Check out the
error stack to find out the reason for failure otherwise.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>
=cut

65
crypto/dist/openssl/doc/ssl/SSL_CTX_add_session.pod vendored Normal file
View File

@ -0,0 +1,65 @@
=pod
=head1 NAME
SSL_CTX_add_session, SSL_add_session, SSL_CTX_remove_session, SSL_remove_session - manipulate session cache
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c);
int SSL_add_session(SSL_CTX *ctx, SSL_SESSION *c);
int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c);
int SSL_remove_session(SSL_CTX *ctx, SSL_SESSION *c);
=head1 DESCRIPTION
SSL_CTX_add_session() adds the session B<c> to the context B<ctx>. The
reference count for session B<c> is incremented by 1. If a session with
the same session id already exists, the old session is removed by calling
L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>.
SSL_CTX_remove_session() removes the session B<c> from the context B<ctx>.
L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> is called once for B<c>.
SSL_add_session() and SSL_remove_session() are synonyms for their
SSL_CTX_*() counterparts.
=head1 NOTES
When adding a new session to the internal session cache, it is examined
whether a session with the same session id already exists. In this case
it is assumed that both sessions are identical. If the same session is
stored in a different SSL_SESSION object, The old session is
removed and replaced by the new session. If the session is actually
identical (the SSL_SESSION object is identical), SSL_CTX_add_session()
is a no-op, and the return value is 0.
=head1 RETURN VALUES
The following values are returned by all functions:
=over 4
=item 0
The operation failed. In case of the add operation, it was tried to add
the same (identical) session twice. In case of the remove operation, the
session was not found in the cache.
=item 1
The operation succeeded.
=back
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>
=cut

49
crypto/dist/openssl/doc/ssl/SSL_CTX_flush_sessions.pod vendored Normal file
View File

@ -0,0 +1,49 @@
=pod
=head1 NAME
SSL_CTX_flush_sessions, SSL_flush_sessions - remove expired sessions
=head1 SYNOPSIS
#include <openssl/ssl.h>
void SSL_CTX_flush_sessions(SSL_CTX *ctx, long tm);
void SSL_flush_sessions(SSL_CTX *ctx, long tm);
=head1 DESCRIPTION
SSL_CTX_flush_sessions() causes a run through the session cache of
B<ctx> to remove sessions expired at time B<tm>.
SSL_flush_sessions() is a synonym for SSL_CTX_flush_sessions().
=head1 NOTES
If enabled, the internal session cache will collect all sessions established
up to the specified maximum number (see SSL_CTX_sess_set_cache_size()).
As sessions will not be reused ones they are expired, they should be
removed from the cache to save resources. This can either be done
automatically whenever 255 new sessions were established (see
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>)
or manually by calling SSL_CTX_flush_sessions().
The parameter B<tm> specifies the time which should be used for the
expiration test, in most cases the actual time given by time(0)
will be used.
SSL_CTX_flush_sessions() will only check sessions stored in the internal
cache. When a session is found and removed, the remove_session_cb is however
called to synchronize with the external cache (see
L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>).
=head1 RETURN VALUES
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>,
L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>
=cut

29
crypto/dist/openssl/doc/ssl/SSL_CTX_free.pod vendored Normal file
View File

@ -0,0 +1,29 @@
=pod
=head1 NAME
SSL_CTX_free - free an allocated SSL_CTX object
=head1 SYNOPSIS
#include <openssl/ssl.h>
void SSL_CTX_free(SSL_CTX *ctx);
=head1 DESCRIPTION
SSL_CTX_free() decrements the reference count of B<ctx>, and removes the
SSL_CTX object pointed to by B<ctx> and frees up the allocated memory if the
the reference count has reached 0.
It also calls the free()ing procedures for indirectly affected items, if
applicable: the session cache, the list of ciphers, the list of Client CAs,
the certificates and keys.
=head1 RETURN VALUES
SSL_CTX_free() does not provide diagnostic information.
L<SSL_CTX_new(3)|SSL_CTX_new(3)>, L<ssl(3)|ssl(3)>
=cut

53
crypto/dist/openssl/doc/ssl/SSL_CTX_get_ex_new_index.pod vendored Normal file
View File

@ -0,0 +1,53 @@
=pod
=head1 NAME
SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data - internal application specific data functions
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_get_ex_new_index(long argl, void *argp,
CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func,
CRYPTO_EX_free *free_func);
int SSL_CTX_set_ex_data(SSL_CTX *ctx, int idx, void *arg);
void *SSL_CTX_get_ex_data(SSL_CTX *ctx, int idx);
typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
int idx, long argl, void *argp);
typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
int idx, long argl, void *argp);
=head1 DESCRIPTION
Several OpenSSL structures can have application specific data attached to them.
These functions are used internally by OpenSSL to manipulate application
specific data attached to a specific structure.
SSL_CTX_get_ex_new_index() is used to register a new index for application
specific data.
SSL_CTX_set_ex_data() is used to store application data at B<arg> for B<idx>
into the B<ctx> object.
SSL_CTX_get_ex_data() is used to retrieve the information for B<idx> from
B<ctx>.
A detailed description for the B<*_get_ex_new_index()> functionality
can be found in L<RSA_get_ex_new_index.pod(3)|RSA_get_ex_new_index.pod(3)>.
The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in
L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>,
L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>
=cut

50
crypto/dist/openssl/doc/ssl/SSL_CTX_get_verify_mode.pod vendored Normal file
View File

@ -0,0 +1,50 @@
=pod
=head1 NAME
SSL_CTX_get_verify_mode, SSL_get_verify_mode, SSL_CTX_get_verify_depth, SSL_get_verify_depth, SSL_get_verify_callback, SSL_CTX_get_verify_callback - get currently set verification parameters
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_get_verify_mode(SSL_CTX *ctx);
int SSL_get_verify_mode(SSL *ssl);
int SSL_CTX_get_verify_depth(SSL_CTX *ctx);
int SSL_get_verify_depth(SSL *ssl);
int (*SSL_CTX_get_verify_callback(SSL_CTX *ctx))(int, X509_STORE_CTX *);
int (*SSL_get_verify_callback(SSL *ssl))(int, X509_STORE_CTX *);
=head1 DESCRIPTION
SSL_CTX_get_verify_mode() returns the verification mode currently set in
B<ctx>.
SSL_get_verify_mode() returns the verification mode currently set in
B<ssl>.
SSL_CTX_get_verify_depth() returns the verification depth limit currently set
in B<ctx>. If no limit has been explicitly set, -1 is returned and the
default value will be used.
SSL_get_verify_depth() returns the verification depth limit currently set
in B<ssl>. If no limit has been explicitly set, -1 is returned and the
default value will be used.
SSL_CTX_get_verify_callback() returns a function pointer to the verification
callback currently set in B<ctx>. If no callback was explicitly set, the
NULL pointer is returned and the default callback will be used.
SSL_get_verify_callback() returns a function pointer to the verification
callback currently set in B<ssl>. If no callback was explicitly set, the
NULL pointer is returned and the default callback will be used.
=head1 RETURN VALUES
See DESCRIPTION
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
=cut

124
crypto/dist/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod vendored Normal file
View File

@ -0,0 +1,124 @@
=pod
=head1 NAME
SSL_CTX_load_verify_locations - set default locations for trusted CA
certificates
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
const char *CApath);
=head1 DESCRIPTION
SSL_CTX_load_verify_locations() specifies the locations for B<ctx>, at
which CA certificates for verification purposes are located. The certificates
available via B<CAfile> and B<CApath> are trusted.
=head1 NOTES
If B<CAfile> is not NULL, it points to a file of CA certificates in PEM
format. The file can contain several CA certificates identified by
-----BEGIN CERTIFICATE-----
... (CA certificate in base64 encoding) ...
-----END CERTIFICATE-----
sequences. Before, between, and after the certificates text is allowed
which can be used e.g. for descriptions of the certificates.
The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations()
function.
If on an TLS/SSL server no special setting is performed using *client_CA_list()
functions, the certificates contained in B<CAfile> are listed to the client
as available CAs during the TLS/SSL handshake.
If B<CApath> is not NULL, it points to a directory containing CA certificates
in PEM format. The files each contain one CA certificate. The files are
looked up by the CA subject name hash value, which must hence be available.
If more than one CA certificate with the same name hash value exist, the
extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search
is performed in the ordering of the extension number, regardless of other
properties of the certificates.
Use the B<c_rehash> utility to create the necessary links.
The certificates in B<CApath> are only looked up when required, e.g. when
building the certificate chain or when actually performing the verification
of a peer certificate.
On a server, the certificates in B<CApath> are not listed as available
CA certificates to a client during a TLS/SSL handshake.
When looking up CA certificates, the OpenSSL library will first search the
certificates in B<CAfile>, then those in B<CApath>. Certificate matching
is done based on the subject name, the key identifier (if present), and the
serial number as taken from the certificate to be verified. If these data
do not match, the next certificate will be tried. If a first certificate
matching the parameters is found, the verification process will be performed;
no other certificates for the same parameters will be searched in case of
failure.
When building its own certificate chain, an OpenSSL client/server will
try to fill in missing certificates from B<CAfile>/B<CApath>, if the
certificate chain was not explicitly specified (see
L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>,
L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>.
=head1 WARNINGS
If several CA certificates matching the name, key identifier, and serial
number condition are available, only the first one will be examined. This
may lead to unexpected results if the same CA certificate is available
with different expiration dates. If a "certificate expired" verification
error occurs, no other certificate will be searched. Make sure to not
have expired certificates mixed with valid ones.
=head1 EXAMPLES
Generate a CA certificate file with descriptive text from the CA certificates
ca1.pem ca2.pem ca3.pem:
#!/bin/sh
rm CAfile.pem
for i in ca1.pem ca2.pem ca3.pem ; do
openssl x509 -in $i -text >> CAfile.pem
done
Prepare the directory /some/where/certs containing several CA certificates
for use as B<CApath>:
cd /some/where/certs
c_rehash .
=head1 RETURN VALUES
The following return values can occur:
=over 4
=item 0
The operation failed because B<CAfile> and B<CApath> are NULL or the
processing at one of the locations specified failed. Check the error
stack to find out the reason.
=item 1
The operation succeeded.
=back
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,
L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,
L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
=cut

98
crypto/dist/openssl/doc/ssl/SSL_CTX_new.pod vendored Normal file
View File

@ -0,0 +1,98 @@
=pod
=head1 NAME
SSL_CTX_new - create a new SSL_CTX object as framework for TLS/SSL enabled functions
=head1 SYNOPSIS
#include <openssl/ssl.h>
SSL_CTX *SSL_CTX_new(SSL_METHOD *method);
=head1 DESCRIPTION
SSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish
TLS/SSL enabled connections.
=head1 NOTES
The SSL_CTX object uses B<method> as connection method. The methods exist
in a generic type (for client and server use), a server only type, and a
client only type. B<method> can be of the following types:
=over 4
=item SSLv2_method(void), SSLv2_server_method(void), SSLv2_client_method(void)
A TLS/SSL connection established with these methods will only understand
the SSLv2 protocol. A client will send out SSLv2 client hello messages
and will also indicate that it only understand SSLv2. A server will only
understand SSLv2 client hello messages.
=item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void)
A TLS/SSL connection established with these methods will only understand the
SSLv3 protocol. A client will send out SSLv3 client hello messages
and will indicate that it only understands SSLv3. A server will only understand
SSLv3 client hello messages. This especially means, that it will
not understand SSLv2 client hello messages which are widely used for
compatibility reasons, see SSLv23_*_method().
=item TLSv1_method(void), TLSv1_server_method(void), TLSv1_client_method(void)
A TLS/SSL connection established with these methods will only understand the
TLSv1 protocol. A client will send out TLSv1 client hello messages
and will indicate that it only understands TLSv1. A server will only understand
TLSv1 client hello messages. This especially means, that it will
not understand SSLv2 client hello messages which are widely used for
compatibility reasons, see SSLv23_*_method(). It will also not understand
SSLv3 client hello messages.
=item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void)
A TLS/SSL connection established with these methods will understand the SSLv2,
SSLv3, and TLSv1 protocol. A client will send out SSLv2 client hello messages
and will indicate that it also understands SSLv3 and TLSv1. A server will
understand SSLv2, SSLv3, and TLSv1 client hello messages. This is the best
choice when compatibility is a concern.
=back
If a generic method is used, it is necessary to explicitly set client or
server mode with L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>
or SSL_set_accept_state().
The list of protocols available can later be limited using the SSL_OP_NO_SSLv2,
SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1 options of the B<SSL_CTX_set_options()> or
B<SSL_set_options()> functions. Using these options it is possible to choose
e.g. SSLv23_server_method() and be able to negotiate with all possible
clients, but to only allow newer protocols like SSLv3 or TLSv1.
SSL_CTX_new() initializes the list of ciphers, the session cache setting,
the callbacks, the keys and certificates, and the options to its default
values.
=head1 RETURN VALUES
The following return values can occur:
=over 4
=item NULL
The creation of a new SSL_CTX object failed. Check the error stack to
find out the reason.
=item Pointer to an SSL_CTX object
The return value points to an allocated SSL_CTX object.
=back
=head1 SEE ALSO
L<SSL_CTX_free(3)|SSL_CTX_free(3)>, L<SSL_accept(3)|SSL_accept(3)>,
L<ssl(3)|ssl(3)>, L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>
=cut

76
crypto/dist/openssl/doc/ssl/SSL_CTX_sess_number.pod vendored Normal file
View File

@ -0,0 +1,76 @@
=pod
=head1 NAME
SSL_CTX_sess_number, SSL_CTX_sess_connect, SSL_CTX_sess_connect_good, SSL_CTX_sess_connect_renegotiate, SSL_CTX_sess_accept, SSL_CTX_sess_accept_good, SSL_CTX_sess_accept_renegotiate, SSL_CTX_sess_hits, SSL_CTX_sess_cb_hits, SSL_CTX_sess_misses, SSL_CTX_sess_timeouts, SSL_CTX_sess_cache_full - obtain session cache statistics
=head1 SYNOPSIS
#include <openssl/ssl.h>
long SSL_CTX_sess_number(SSL_CTX *ctx);
long SSL_CTX_sess_connect(SSL_CTX *ctx);
long SSL_CTX_sess_connect_good(SSL_CTX *ctx);
long SSL_CTX_sess_connect_renegotiate(SSL_CTX *ctx);
long SSL_CTX_sess_accept(SSL_CTX *ctx);
long SSL_CTX_sess_accept_good(SSL_CTX *ctx);
long SSL_CTX_sess_accept_renegotiate(SSL_CTX *ctx);
long SSL_CTX_sess_hits(SSL_CTX *ctx);
long SSL_CTX_sess_cb_hits(SSL_CTX *ctx);
long SSL_CTX_sess_misses(SSL_CTX *ctx);
long SSL_CTX_sess_timeouts(SSL_CTX *ctx);
long SSL_CTX_sess_cache_full(SSL_CTX *ctx);
=head1 DESCRIPTION
SSL_CTX_sess_number() returns the current number of sessions in the internal
session cache.
SSL_CTX_sess_connect() returns the number of started SSL/TLS handshakes in
client mode.
SSL_CTX_sess_connect_good() returns the number of successfully established
SSL/TLS sessions in client mode.
SSL_CTX_sess_connect_renegotiate() returns the number of start renegotiations
in client mode.
SSL_CTX_sess_accept() returns the number of started SSL/TLS handshakes in
server mode.
SSL_CTX_sess_accept_good() returns the number of successfully established
SSL/TLS sessions in server mode.
SSL_CTX_sess_accept_renegotiate() returns the number of start renegotiations
in server mode.
SSL_CTX_sess_hits() returns the number of successfully reused sessions.
In client mode a session set with L<SSL_set_session(3)|SSL_set_session(3)>
successfully reused is counted as a hit. In server mode a session successfully
retrieved from internal or external cache is counted as a hit.
SSL_CTX_sess_cb_hits() returns the number of successfully retrieved sessions
from the external session cache in server mode.
SSL_CTX_sess_misses() returns the number of sessions proposed by clients
that were not found in the internal session cache in server mode.
SSL_CTX_sess_timeouts() returns the number of sessions proposed by clients
and either found in the internal or external session cache in server mode,
but that were invalid due to timeout. These sessions are not included in
the SSL_CTX_sess_hits() count.
SSL_CTX_sess_cache_full() returns the number of sessions that were removed
because the maximum session cache size was exceeded.
=head1 RETURN VALUES
The functions return the values indicated in the DESCRIPTION section.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>,
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>
L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>
=cut

51
crypto/dist/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod vendored Normal file
View File

@ -0,0 +1,51 @@
=pod
=head1 NAME
SSL_CTX_sess_set_cache_size, SSL_CTX_sess_get_cache_size - manipulate session cache size
=head1 SYNOPSIS
#include <openssl/ssl.h>
long SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, long t);
long SSL_CTX_sess_get_cache_size(SSL_CTX *ctx);
=head1 DESCRIPTION
SSL_CTX_sess_set_cache_size() sets the size of the internal session cache
of context B<ctx> to B<t>.
SSL_CTX_sess_get_cache_size() returns the currently valid session cache size.
=head1 NOTES
The internal session cache size is SSL_SESSION_CACHE_MAX_SIZE_DEFAULT,
currently 1024*20, so that up to 20000 sessions can be held. This size
can be modified using the SSL_CTX_sess_set_cache_size() call. A special
case is the size 0, which is used for unlimited size.
When the maximum number of sessions is reached, no more new sessions are
added to the cache. New space may be added by calling
L<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)> to remove
expired sessions.
If the size of the session cache is reduced and more sessions are already
in the session cache, old session will be removed at the next time a
session shall be added. This removal is not synchronized with the
expiration of sessions.
=head1 RETURN VALUES
SSL_CTX_sess_set_cache_size() returns the previously valid size.
SSL_CTX_sess_get_cache_size() returns the currently valid size.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>,
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>,
L<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)>
=cut

81
crypto/dist/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod vendored Normal file
View File

@ -0,0 +1,81 @@
=pod
=head1 NAME
SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - provide callback functions for server side external session caching
=head1 SYNOPSIS
#include <openssl/ssl.h>
void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,
int (*new_session_cb)(SSL *, SSL_SESSION *));
void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *));
void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx,
SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *));
int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess);
void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy);
int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess);
void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data,
int len, int *copy);
=head1 DESCRIPTION
SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically
called whenever a new session was negotiated.
SSL_CTX_sess_set_remove_cb() sets the callback function, which is
automatically called whenever a session is removed by the SSL engine,
because it is considered faulty or the session has become obsolete because
of exceeding the timeout value.
SSL_CTX_sess_set_get_cb() sets the callback function which is called,
whenever a SSL/TLS client proposed to resume a session but the session
could not be found in the internal session cache (see
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>).
(SSL/TLS server only.)
SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and
SSL_CTX_sess_get_get_cb() allow to retrieve the function pointers of the
provided callback functions. If a callback function has not been set,
the NULL pointer is returned.
=head1 NOTES
In order to allow external session caching, synchronization with the internal
session cache is realized via callback functions. Inside these callback
functions, session can be saved to disk or put into a database using the
L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> interface.
The new_session_cb() is called, whenever a new session has been negotiated
and session caching is enabled (see
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>).
The new_session_cb() is passed the B<ssl> connection and the ssl session
B<sess>. If the callback returns B<0>, the session will be immediately
removed again.
The remove_session_cb() is called, whenever the SSL engine removes a session
from the internal cache. This happens if the session is removed because
it is expired or when a connection was not shutdown cleanly. The
remove_session_cb() is passed the B<ctx> and the ssl session B<sess>.
It does not provide any feedback.
The get_session_cb() is only called on SSL/TLS servers with the session id
proposed by the client. The get_session_cb() is always called, also when
session caching was disabled. The get_session_cb() is passed the
B<ssl> connection, the session id of length B<length> at the memory location
B<data>. With the parameter B<copy> the callback can require the
SSL engine to increment the reference count of the SSL_SESSION object.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>,
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
L<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)>
=cut

34
crypto/dist/openssl/doc/ssl/SSL_CTX_sessions.pod vendored Normal file
View File

@ -0,0 +1,34 @@
=pod
=head1 NAME
SSL_CTX_sessions - access internal session cache
=head1 SYNOPSIS
#include <openssl/ssl.h>
struct lhash_st *SSL_CTX_sessions(SSL_CTX *ctx);
=head1 DESCRIPTION
SSL_CTX_sessions() returns a pointer to the lhash databases containing the
internal session cache for B<ctx>.
=head1 NOTES
The sessions in the internal session cache are kept in an
L<lhash(3)|lhash(3)> type database. It is possible to directly
access this database e.g. for searching. In parallel, the sessions
form a linked list which is maintained separately from the
L<lhash(3)|lhash(3)> operations, so that the database must not be
modified directly but by using the
L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)> family of functions.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<lhash(3)|lhash(3)>,
L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>,
L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>
=cut

52
crypto/dist/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod vendored Normal file
View File

@ -0,0 +1,52 @@
=pod
=head1 NAME
SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str);
int SSL_set_cipher_list(SSL *ssl, const char *str);
=head1 DESCRIPTION
SSL_CTX_set_cipher_list() sets the list of available ciphers for B<ctx>
using the control string B<str>. The format of the string is described
in L<ciphers(1)|ciphers(1)>. The list of ciphers is inherited by all
B<ssl> objects created from B<ctx>.
SSL_set_cipher_list() sets the list of ciphers only for B<ssl>.
=head1 NOTES
The control string B<str> should be universally usable and not depend
on details of the library configuration (ciphers compiled in). Thus no
syntax checking takes place. Items that are not recognized, because the
corresponding ciphers are not compiled in or because they are mistyped,
are simply ignored. Failure is only flagged if no ciphers could be collected
at all.
It should be noted, that inclusion of a cipher to be used into the list is
a necessary condition. On the client side, the inclusion into the list is
also sufficient. On the server side, additional restrictions apply. All ciphers
have additional requirements. ADH ciphers don't need a certificate, but
DH-parameters must have been set. All other ciphers need a corresponding
certificate and key. A RSA cipher can only be chosen, when a RSA certificate is
available, the respective is valid for DSA ciphers. Ciphers using EDH need
a certificate and key and DH-parameters.
=head1 RETURN VALUES
SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher
could be selected and 0 on complete failure.
=head1 SEE ALSO
L<ssl(3)|ssl(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>,
L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
L<ciphers(1)|ciphers(1)>
=cut

Some files were not shown because too many files have changed in this diff Show More