Add ASN1 code for netscape certificate sequences.
[openssl.git] / INSTALL
1 Installing OpenSSL on Unix
2 --------------------------
3
4 [For instructions for compiling OpenSSL on Windows systems, see
5 INSTALL.W32].
6
7 To install OpenSSL, you will need:
8
9   * Perl
10   * C compiler
11   * A supported operating system
12
13 Quick Start
14 -----------
15
16 If you want to just get on with it, do:
17
18   sh config                      [if this fails, go to step 1b below]
19   make -f Makefile.ssl links
20   make
21   make rehash
22   make test
23   make install
24
25 This will build and install OpenSSL in the default location, which is
26 /usr/local/ssl. If you want to install it anywhere else, do this
27 after running ./Configure <system>:
28
29   perl util/ssldir.pl /new/install/path
30
31 If anything goes wrong, follow the detailed instructions below. If
32 your operating system is not (yet) supported by OpenSSL, see the
33 section on porting to a new system.
34
35 Installation in Detail
36 ----------------------
37
38  1a. Configure OpenSSL for your operation system automatically
39
40      Run
41
42        sh config
43
44      This guesses at your operating system (and compiler, if
45      necessary) and configures OpenSSL based on this guess. Check the
46      first line of output to see if it guessed correctly. If it did
47      not get it correct or you want to use a different compiler then
48      go to step 1b. Otherwise go to step 2.
49
50  1b. Configure OpenSSL for your operating system manually
51
52      OpenSSL knows about a range of different operating system, hardware
53      and compiler combinations. To see the ones it knows about, run
54
55        ./Configure
56
57      Pick a suitable name from the list that matches your system. For
58      most operating systems there is a choice between using "cc" or
59      "gcc".
60
61      When you have identified your system (and if necessary compiler)
62      use this name as the argument to ./Configure. For example, a
63      "linux-elf" user would run:
64
65        ./Configure linux-elf
66
67      If your system is not available, you will have to edit the Configure
68      program and add the correct configuration for your system.
69
70      Configure configures various files by converting an existing .org
71      file into the real file. If you edit any files, remember that if
72      a corresponding .org file exists them the next time you run
73      ./Configure your changes will be lost when the file gets
74      re-created from the .org file. The files that are created from
75      .org files are:
76
77        Makefile.ssl
78        crypto/des/des.h
79        crypto/des/des_locl.h
80        crypto/md2/md2.h
81        crypto/rc4/rc4.h
82        crypto/rc4/rc4_enc.c
83        crypto/rc2/rc2.h
84        crypto/bf/bf_locl.h
85        crypto/idea/idea.h
86        crypto/bn/bn.h
87
88   2. Set the install directory
89
90      If the install directory will be the default of /usr/local/ssl,
91      skip to the next stage. Otherwise, run
92
93        perl util/ssldir.pl /new/install/path
94
95      This configures the installation location into the "install"
96      target of the top-level Makefile, and also updates some defines
97      in an include file so that the default certificate directory is
98      under the proper installation directory. It also updates a few
99      utility files used in the build process.
100
101   3. Build OpenSSL
102
103      Now run
104
105        make
106
107      This will build the OpenSSL libraries (libcrypto.a and libssl.a)
108      and the OpenSSL binary ("openssl"). The libraries will be built
109      in the top-level directory, and the binary will be in the "apps"
110      directory.
111
112   4. After a successful build, the libraries should be tested. Run
113
114        make rehash
115        make test
116
117      (The first line makes the test certificates in the "certs"
118      directory accessable via an hash name, which is required for some
119      of the tests).
120
121   5. If everything tests ok, install OpenSSL with
122
123        make install
124
125      This will create the installation directory (if it does not
126      exist) and then create the following subdirectories:
127
128        bin            Contains the openssl binary and a few other utility
129                       programs. It also contains symbolic links so
130                       that openssl commands can be accessed directly
131                       (e.g. so that "s_client" can be used instead of
132                       "openssl s_client").
133        certs          Initially empty, this is the default location
134                       for certificate files.
135        include        Contains the header files needed if you want to
136                       compile programs with libcrypto or libssl.
137        lib            Contains the library files themselves and the
138                       OpenSSL configuration file "openssl.cnf".
139        private        Initially empty, this is the default location
140                       for private key files.
141
142 ----------------------------------------------------------------------
143
144 Additional Compilation Notes
145 ----------------------------
146
147 These notes come from SSLeay 0.9.1 and cover some more advanced
148 facilities (such as building a single makefile for use on Windows
149 systems).
150
151
152 # Installation of SSLeay.
153 # It depends on perl for a few bits but those steps can be skipped and
154 # the top level makefile edited by hand
155
156 # When bringing the SSLeay distribution back from the evil intel world
157 # of Windows NT, do the following to make it nice again under unix :-)
158 # You don't normally need to run this.
159 sh util/fixNT.sh        # This only works for NT now - eay - 21-Jun-1996
160
161 # If you have perl, and it is not in /usr/local/bin, you can run
162 perl util/perlpath.pl /new/path
163 # and this will fix the paths in all the scripts.  DO NOT put
164 # /new/path/perl, just /new/path. The build
165 # environment always run scripts as 'perl perlscript.pl' but some of the
166 # 'applications' are easier to usr with the path fixed.
167
168 # Edit crypto/cryptlib.h, tools/c_rehash, and Makefile.ssl
169 # to set the install locations if you don't like
170 # the default location of /usr/local/ssl
171 # Do this by running
172 perl util/ssldir.pl /new/ssl/home
173 # if you have perl, or by hand if not.
174
175 # If things have been stuffed up with the sym links, run
176 make -f Makefile.ssl links
177 # This will re-populate lib/include with symlinks and for each
178 # directory, link Makefile to Makefile.ssl
179
180 # Setup the machine dependent stuff for the top level makefile
181 # and some select .h files
182 # If you don't have perl, this will bomb, in which case just edit the
183 # top level Makefile.ssl
184 ./Configure 'system type'
185
186 # The 'Configure' command contains default configuration parameters
187 # for lots of machines.  Configure edits 5 lines in the top level Makefile
188 # It modifies the following values in the following files
189 Makefile.ssl            CC CFLAG EX_LIBS BN_MULW
190 crypto/des/des.h        DES_LONG
191 crypto/des/des_locl.h   DES_PTR
192 crypto/md2/md2.h        MD2_INT
193 crypto/rc4/rc4.h        RC4_INT
194 crypto/rc4/rc4_enc.c    RC4_INDEX
195 crypto/rc2/rc2.h        RC2_INT
196 crypto/bf/bf_locl.h     BF_INT
197 crypto/idea/idea.h      IDEA_INT
198 crypto/bn/bn.h          BN_LLONG (and defines one of SIXTY_FOUR_BIT,
199                                   SIXTY_FOUR_BIT_LONG, THIRTY_TWO_BIT,
200                                   SIXTEEN_BIT or EIGHT_BIT)
201 Please remember that all these files are actually copies of the file with
202 a .org extention.  So if you change crypto/des/des.h, the next time
203 you run Configure, it will be runover by a 'configured' version of
204 crypto/des/des.org.  So to make the changer the default, change the .org
205 files.  The reason these files have to be edited is because most of
206 these modifications change the size of fundamental data types.
207 While in theory this stuff is optional, it often makes a big
208 difference in performance and when using assember, it is importaint
209 for the 'Bignum bits' match those required by the assember code.
210 A warning for people using gcc with sparc cpu's.  Gcc needs the -mv8
211 flag to use the hardware multiply instruction which was not present in
212 earlier versions of the sparc CPU.  I define it by default.  If you
213 have an old sparc, and it crashes, try rebuilding with this flag
214 removed.  I am leaving this flag on by default because it makes
215 things run 4 times faster :-)
216
217 # clean out all the old stuff
218 make clean
219
220 # Do a make depend only if you have the makedepend command installed
221 # This is not needed but it does make things nice when developing.
222 make depend
223
224 # make should build everything
225 make
226
227 # fix up the demo certificate hash directory if it has been stuffed up.
228 make rehash
229
230 # test everything
231 make test
232
233 # install the lot
234 make install
235
236 # It is worth noting that all the applications are built into the one
237 # program, ssleay, which is then has links from the other programs
238 # names to it.
239 # The applicatons can be built by themselves, just don't define the
240 # 'MONOLITH' flag.  So to build the 'enc' program stand alone,
241 gcc -O2 -Iinclude apps/enc.c apps/apps.c libcrypto.a
242
243 # Other useful make options are
244 make makefile.one
245 # which generate a 'makefile.one' file which will build the complete
246 # SSLeay distribution with temp. files in './tmp' and 'installable' files
247 # in './out'
248
249 # Have a look at running
250 perl util/mk1mf.pl help
251 # this can be used to generate a single makefile and is about the only
252 # way to generate makefiles for windows.
253
254 # There is actually a final way of building SSLeay.
255 gcc -O2 -c -Icrypto -Iinclude crypto/crypto.c
256 gcc -O2 -c -Issl -Iinclude ssl/ssl.c
257 # and you now have the 2 libraries as single object files :-).
258 # If you want to use the assember code for your particular platform
259 # (DEC alpha/x86 are the main ones, the other assember is just the
260 # output from gcc) you will need to link the assember with the above generated
261 # object file and also do the above compile as
262 gcc -O2 -DBN_ASM -c -Icrypto -Iinclude crypto/crypto.c
263
264 This last option is probably the best way to go when porting to another
265 platform or building shared libraries.  It is not good for development so
266 I don't normally use it.
267
268 To build shared libararies under unix, have a look in shlib, basically 
269 you are on your own, but it is quite easy and all you have to do
270 is compile 2 (or 3) files.
271
272 For mult-threading, have a read of doc/threads.doc.  Again it is quite
273 easy and normally only requires some extra callbacks to be defined
274 by the application.
275 The examples for solaris and windows NT/95 are in the mt directory.
276
277 have fun
278
279 eric 25-Jun-1997
280
281 IRIX 5.x will build as a 32 bit system with mips1 assember.
282 IRIX 6.x will build as a 64 bit system with mips3 assember.  It conforms
283 to n32 standards. In theory you can compile the 64 bit assember under
284 IRIX 5.x but you will have to have the correct system software installed.