[thirdparty/openssl.git] / README


 OpenSSL 1.1.0-dev

 Copyright (c) 1998-2015 The OpenSSL Project
 Copyright (c) 1995-1998 Eric A. Young, Tim J. Hudson
 All rights reserved.

 DESCRIPTION
 -----------

 The OpenSSL Project is a collaborative effort to develop a robust,
 commercial-grade, fully featured, and Open Source toolkit implementing the
 Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1)
 protocols as well as a full-strength general purpose cryptography library.
 The project is managed by a worldwide community of volunteers that use the
 Internet to communicate, plan, and develop the OpenSSL toolkit and its
 related documentation.

 OpenSSL is based on the excellent SSLeay library developed from Eric A. Young
 and Tim J. Hudson.  The OpenSSL toolkit is licensed under a dual-license (the
 OpenSSL license plus the SSLeay license) situation, which basically means
 that you are free to get and use it for commercial and non-commercial
 purposes as long as you fulfill the conditions of both licenses.

 OVERVIEW
 --------

 The OpenSSL toolkit includes:

 libssl.a:
     Implementation of SSLv2, SSLv3, TLSv1 and the required code to support
     both SSLv2, SSLv3 and TLSv1 in the one server and client.

 libcrypto.a:
     General encryption and X.509 v1/v3 stuff needed by SSL/TLS but not
     actually logically part of it. It includes routines for the following:

     Ciphers
        libdes - EAY's libdes DES encryption package which was floating
                 around the net for a few years, and was then relicensed by
                 him as part of SSLeay.  It includes 15 'modes/variations'
                 of DES (1, 2 and 3 key versions of ecb, cbc, cfb and ofb;
                 pcbc and a more general form of cfb and ofb) including desx
                 in cbc mode, a fast crypt(3), and routines to read
                 passwords from the keyboard.
        RC4 encryption,
        RC2 encryption      - 4 different modes, ecb, cbc, cfb and ofb.
        Blowfish encryption - 4 different modes, ecb, cbc, cfb and ofb.
        IDEA encryption     - 4 different modes, ecb, cbc, cfb and ofb.

     Digests
        MD5 and MD2 message digest algorithms, fast implementations,
        SHA (SHA-0) and SHA-1 message digest algorithms,
        MDC2 message digest. A DES based hash that is popular on smart cards.

     Public Key
        RSA encryption/decryption/generation.
            There is no limit on the number of bits.
        DSA encryption/decryption/generation.
            There is no limit on the number of bits.
        Diffie-Hellman key-exchange/key generation.
            There is no limit on the number of bits.

     X.509v3 certificates
        X509 encoding/decoding into/from binary ASN1 and a PEM
             based ASCII-binary encoding which supports encryption with a
             private key.  Program to generate RSA and DSA certificate
             requests and to generate RSA and DSA certificates.

     Systems
        The normal digital envelope routines and base64 encoding.  Higher
        level access to ciphers and digests by name.  New ciphers can be
        loaded at run time.  The BIO io system which is a simple non-blocking
        IO abstraction.  Current methods supported are file descriptors,
        sockets, socket accept, socket connect, memory buffer, buffering, SSL
        client/server, file pointer, encryption, digest, non-blocking testing
        and null.

     Data structures
        A dynamically growing hashing system
        A simple stack.
        A Configuration loader that uses a format similar to MS .ini files.

 openssl:
     A command line tool that can be used for:
        Creation of RSA, DH and DSA key parameters
        Creation of X.509 certificates, CSRs and CRLs
        Calculation of Message Digests
        Encryption and Decryption with Ciphers
        SSL/TLS Client and Server Tests
        Handling of S/MIME signed or encrypted mail

 INSTALLATION
 ------------

 To install this package under a Unix derivative, read the INSTALL file.  For
 a Win32 platform, read the INSTALL.W32 file.  For OpenVMS systems, read
 INSTALL.VMS.

 Read the documentation in the doc/ directory.  It is quite rough, but it
 lists the functions; you will probably have to look at the code to work out
 how to use them. Look at the example programs.

 PROBLEMS
 --------

 For some platforms, there are some known problems that may affect the user
 or application author.  We try to collect those in doc/PROBLEMS, with current
 thoughts on how they should be solved in a future of OpenSSL.

 SUPPORT
 -------

 See the OpenSSL website www.openssl.org for details of how to obtain
 commercial technical support.

 If you have any problems with OpenSSL then please take the following steps
 first:

    - Download the current snapshot from ftp://ftp.openssl.org/snapshot/
      to see if the problem has already been addressed
    - Remove ASM versions of libraries
    - Remove compiler optimisation flags

 If you wish to report a bug then please include the following information in
 any bug report:

    - On Unix systems:
        Self-test report generated by 'make report'
    - On other systems:
        OpenSSL version: output of 'openssl version -a'
        OS Name, Version, Hardware platform
        Compiler Details (name, version)
    - Application Details (name, version)
    - Problem Description (steps that will reproduce the problem, if known)
    - Stack Traceback (if the application dumps core)

 Email the report to:

    rt@openssl.org

 In order to avoid spam, this is a moderated mailing list, and it might
 take a day for the ticket to show up.  (We also scan posts to make sure
 that security disclosures aren't publically posted by mistake.) Mail to
 this address is recorded in the public RT (request tracker) database (see
 https://www.openssl.org/support/rt.html for details) and also forwarded
 the public openssl-dev mailing list.  Confidential mail may be sent to
 openssl-security@openssl.org (PGP key available from the key servers).

 Please do NOT use this for general assistance or support queries.
 Just because something doesn't work the way you expect does not mean it
 is necessarily a bug in OpenSSL.

 You can also make GitHub pull requests. If you do this, please also send
 mail to rt@openssl.org with a link to the PR so that we can more easily
 keep track of it.

 HOW TO CONTRIBUTE TO OpenSSL
 ----------------------------

 See CONTRIBUTING
Commit	Line	Data
d02b48c6	1
9770924f	2	OpenSSL 1.1.0-dev
651d0aff	3
740ceb5b	4	Copyright (c) 1998-2015 The OpenSSL Project
058bf559	5	Copyright (c) 1995-1998 Eric A. Young, Tim J. Hudson
651d0aff RE	6	All rights reserved.
651d0aff RE	7
dfca822f RE	8	DESCRIPTION
	9	-----------
	10
f1c236f8	11	The OpenSSL Project is a collaborative effort to develop a robust,
651d0aff	12	commercial-grade, fully featured, and Open Source toolkit implementing the
1c308226	13	Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1)
24282b87 UM	14	protocols as well as a full-strength general purpose cryptography library.
	15	The project is managed by a worldwide community of volunteers that use the
	16	Internet to communicate, plan, and develop the OpenSSL toolkit and its
99efc0f5	17	related documentation.
651d0aff	18
f1c236f8	19	OpenSSL is based on the excellent SSLeay library developed from Eric A. Young
1c308226 RE	20	and Tim J. Hudson. The OpenSSL toolkit is licensed under a dual-license (the
	21	OpenSSL license plus the SSLeay license) situation, which basically means
	22	that you are free to get and use it for commercial and non-commercial
99efc0f5	23	purposes as long as you fulfill the conditions of both licenses.
651d0aff	24
dfca822f RE	25	OVERVIEW
	26	--------
	27
1c308226	28	The OpenSSL toolkit includes:
651d0aff RE	29
	30	libssl.a:
	31	Implementation of SSLv2, SSLv3, TLSv1 and the required code to support
1c308226	32	both SSLv2, SSLv3 and TLSv1 in the one server and client.
651d0aff RE	33
651d0aff RE	34	libcrypto.a:
1c308226 RE	35	General encryption and X.509 v1/v3 stuff needed by SSL/TLS but not
1c308226 RE	36	actually logically part of it. It includes routines for the following:
651d0aff RE	37
651d0aff RE	38	Ciphers
41a8d516 BM	39	libdes - EAY's libdes DES encryption package which was floating
	40	around the net for a few years, and was then relicensed by
	41	him as part of SSLeay. It includes 15 'modes/variations'
	42	of DES (1, 2 and 3 key versions of ecb, cbc, cfb and ofb;
	43	pcbc and a more general form of cfb and ofb) including desx
	44	in cbc mode, a fast crypt(3), and routines to read
	45	passwords from the keyboard.
651d0aff RE	46	RC4 encryption,
	47	RC2 encryption - 4 different modes, ecb, cbc, cfb and ofb.
	48	Blowfish encryption - 4 different modes, ecb, cbc, cfb and ofb.
	49	IDEA encryption - 4 different modes, ecb, cbc, cfb and ofb.
	50
	51	Digests
	52	MD5 and MD2 message digest algorithms, fast implementations,
	53	SHA (SHA-0) and SHA-1 message digest algorithms,
62de8497	54	MDC2 message digest. A DES based hash that is popular on smart cards.
651d0aff RE	55
651d0aff RE	56	Public Key
99efc0f5	57	RSA encryption/decryption/generation.
651d0aff	58	There is no limit on the number of bits.
99efc0f5	59	DSA encryption/decryption/generation.
651d0aff	60	There is no limit on the number of bits.
b22c7a1c	61	Diffie-Hellman key-exchange/key generation.
651d0aff RE	62	There is no limit on the number of bits.
	63
	64	X.509v3 certificates
	65	X509 encoding/decoding into/from binary ASN1 and a PEM
3b80e3aa	66	based ASCII-binary encoding which supports encryption with a
651d0aff RE	67	private key. Program to generate RSA and DSA certificate
	68	requests and to generate RSA and DSA certificates.
	69
	70	Systems
	71	The normal digital envelope routines and base64 encoding. Higher
	72	level access to ciphers and digests by name. New ciphers can be
	73	loaded at run time. The BIO io system which is a simple non-blocking
	74	IO abstraction. Current methods supported are file descriptors,
	75	sockets, socket accept, socket connect, memory buffer, buffering, SSL
	76	client/server, file pointer, encryption, digest, non-blocking testing
	77	and null.
	78
	79	Data structures
	80	A dynamically growing hashing system
	81	A simple stack.
	82	A Configuration loader that uses a format similar to MS .ini files.
	83
a2c96d88	84	openssl:
d7f0ab5f UM	85	A command line tool that can be used for:
d7f0ab5f UM	86	Creation of RSA, DH and DSA key parameters
a2c96d88	87	Creation of X.509 certificates, CSRs and CRLs
d7f0ab5f UM	88	Calculation of Message Digests
	89	Encryption and Decryption with Ciphers
	90	SSL/TLS Client and Server Tests
	91	Handling of S/MIME signed or encrypted mail
	92
dfca822f RE	93	INSTALLATION
	94	------------
	95
1c308226	96	To install this package under a Unix derivative, read the INSTALL file. For
7d7d2cbc UM	97	a Win32 platform, read the INSTALL.W32 file. For OpenVMS systems, read
7d7d2cbc UM	98	INSTALL.VMS.
651d0aff	99
1c308226	100	Read the documentation in the doc/ directory. It is quite rough, but it
9020b862 RL	101	lists the functions; you will probably have to look at the code to work out
9020b862 RL	102	how to use them. Look at the example programs.
d02b48c6	103
80e1495b RL	104	PROBLEMS
	105	--------
	106
	107	For some platforms, there are some known problems that may affect the user
	108	or application author. We try to collect those in doc/PROBLEMS, with current
	109	thoughts on how they should be solved in a future of OpenSSL.
	110
a2c96d88	111	SUPPORT
dfca822f RE	112	-------
dfca822f RE	113
0e37c909 DSH	114	See the OpenSSL website www.openssl.org for details of how to obtain
	115	commercial technical support.
	116
dfca822f RE	117	If you have any problems with OpenSSL then please take the following steps
	118	first:
	119
d7f0ab5f UM	120	- Download the current snapshot from ftp://ftp.openssl.org/snapshot/
d7f0ab5f UM	121	to see if the problem has already been addressed
dfca822f	122	- Remove ASM versions of libraries
a2c96d88	123	- Remove compiler optimisation flags
dfca822f RE	124
	125	If you wish to report a bug then please include the following information in
	126	any bug report:
	127
d7f0ab5f UM	128	- On Unix systems:
	129	Self-test report generated by 'make report'
	130	- On other systems:
	131	OpenSSL version: output of 'openssl version -a'
	132	OS Name, Version, Hardware platform
	133	Compiler Details (name, version)
	134	- Application Details (name, version)
	135	- Problem Description (steps that will reproduce the problem, if known)
	136	- Stack Traceback (if the application dumps core)
dfca822f	137
468ab1c2	138	Email the report to:
dfca822f	139
932af161	140	rt@openssl.org
dfca822f	141
932af161 RS	142	In order to avoid spam, this is a moderated mailing list, and it might
	143	take a day for the ticket to show up. (We also scan posts to make sure
	144	that security disclosures aren't publically posted by mistake.) Mail to
	145	this address is recorded in the public RT (request tracker) database (see
	146	https://www.openssl.org/support/rt.html for details) and also forwarded
	147	the public openssl-dev mailing list. Confidential mail may be sent to
	148	openssl-security@openssl.org (PGP key available from the key servers).
0e37c909	149
932af161 RS	150	Please do NOT use this for general assistance or support queries.
	151	Just because something doesn't work the way you expect does not mean it
	152	is necessarily a bug in OpenSSL.
	153
	154	You can also make GitHub pull requests. If you do this, please also send
	155	mail to rt@openssl.org with a link to the PR so that we can more easily
	156	keep track of it.
a5ec86d1	157
b282fdae UM	158	HOW TO CONTRIBUTE TO OpenSSL
	159	----------------------------
	160
eb05f173	161	See CONTRIBUTING