File: create_certs.html

package info (click to toggle)
erlang-doc-html 1%3A10.b.1a-1
links: PTS
area: main
in suites: sarge
size: 22,488 kB
ctags: 9,933
sloc: erlang: 505; ansic: 323; perl: 61; sh: 45; makefile: 39
file content (484 lines) | stat: -rw-r--r-- 15,145 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.2 -->
<HTML>
<HEAD>
  <TITLE>Creating Certificates</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<CENTER>
<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif"></A>
</CENTER>
<A NAME="4"><!-- Empty --></A>
<H2>4 Creating Certificates</H2>

<P>Here we consider the creation of example certificates. 

<A NAME="4.1"><!-- Empty --></A>
<H3>4.1 The openssl Command</H3>

<P>The <CODE>openssl</CODE> command is a utility that comes with the
OpenSSL distribution. It provides a variety of subcommands. Each
subcommand is invoked as
<PRE>
      openssl subcmd &#60;options and arguments&#62;
</PRE>

<P>where <CODE>subcmd</CODE> denotes the subcommand in question.


<P>We shall use the following subcommands to create certificates for
the purpose of testing Erlang/OTP SSL:


<P>
<UL>

<LI>
<STRONG>req</STRONG> to create certificate requests and a
self-signed certificates, 


</LI>


<LI>
<STRONG>ca</STRONG> to create certificates from certificate requests.

</LI>


</UL>

<P>We create the following certificates:


<P>
<UL>

<LI>
the <STRONG>erlangCA</STRONG> root certificate (a self-signed
certificate), 

</LI>


<LI>
the <STRONG>otpCA</STRONG> certificate signed by the <STRONG>erlangCA</STRONG>, 

</LI>


<LI>
a client certificate signed by the <STRONG>otpCA</STRONG>, and

</LI>


<LI>
a server certificate signed by the <STRONG>otpCA</STRONG>.

</LI>


</UL>
<A NAME="4.1.1"><!-- Empty --></A>
<H4>4.1.1 The openssl configuration file</H4>

<P>An <CODE>openssl</CODE> configuration file consist of a number of
        sections, where each section starts with one line containing
        <CODE>[ section_name ]</CODE>, where <CODE>section_name</CODE> is the name
        of the section. The first section of the file is either
        unnamed, or is named <CODE>[ default ]</CODE>. For further details
        see the OpenSSL config(5) manual page.


<P>The required sections for the subcommands we are going to 
        use are as follows:


<P>
<CENTER>
<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=1>
  <CAPTION ALIGN=BOTTOM><EM>openssl subcommands to use</EM></CAPTION>
  <TR>
    <TD ALIGN="LEFT" VALIGN="MIDDLE">
subcommand
    </TD>
    <TD ALIGN="LEFT" VALIGN="MIDDLE">
required/default section
    </TD>
    <TD ALIGN="LEFT" VALIGN="MIDDLE">
override command line option
    </TD>
    <TD ALIGN="LEFT" VALIGN="MIDDLE">
configuration file option
    </TD>

  </TR>
  <TR>
    <TD ALIGN="LEFT" VALIGN="MIDDLE">
req
    </TD>
    <TD ALIGN="LEFT" VALIGN="MIDDLE">
[req]
    </TD>
    <TD ALIGN="LEFT" VALIGN="MIDDLE">
-
    </TD>
    <TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>-config FILE</CODE>
    </TD>

  </TR>
  <TR>
    <TD ALIGN="LEFT" VALIGN="MIDDLE">
ca
    </TD>
    <TD ALIGN="LEFT" VALIGN="MIDDLE">
[ca]
    </TD>
    <TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>-name section</CODE>
    </TD>
    <TD ALIGN="LEFT" VALIGN="MIDDLE">
<CODE>-config FILE</CODE>
    </TD>

  </TR>

</TABLE>
</CENTER>
<A NAME="4.1.2"><!-- Empty --></A>
<H4>4.1.2 Creating the Erlang root CA</H4>

<P>The Erlang root CA is created with the command

<PRE>
        openssl req -new -x509 -config /some/path/req.cnf \
            -keyout /some/path/key.pem -out /some/path/cert.pem
</PRE>

<P>where the option <CODE>-new</CODE> indicates that we want to create
        a new certificate request and the option <CODE>-x509</CODE> implies
        that a self-signed certificate is created.

<A NAME="4.1.3"><!-- Empty --></A>
<H4>4.1.3 Creating the OTP CA</H4>

<P>The OTP CA is created by first creating a certificate request
        with the command

<PRE>
        openssl req -new -config /some/path/req.cnf \
            -keyout /some/path/key.pem -out /some/path/req.pem
</PRE>

<P>and the ask the Erlang CA to sign it:

<PRE>
        openssl ca -batch -notext -config /some/path/req.cnf \
           -extensions ca_cert -in /some/path/req.pem -out /some/path/cert.pem
</PRE>

<P>where the option <CODE>-extensions</CODE> refers to a section in the
        configuration file saying that it should create a CA certificate, 
        and not a plain user certificate. 


<P>The <CODE>client</CODE> and <CODE>server</CODE> certificates are created
        similarly, except that the option <CODE>-extensions</CODE> then has the 
        value <CODE>user_cert</CODE>. 

<A NAME="4.2"><!-- Empty --></A>
<H3>4.2 An Example</H3>

<P>The following module <CODE>create_certs</CODE> is used by the Erlang/OTP
SSL application for generating certificates to be used in tests. The
source code is also found in <CODE>ssl-X.Y.Z/examples/certs/src</CODE>.


<P>The purpose of the <CODE>create_certs:all/1</CODE> function is to make
it possible to provide from the <CODE>erl</CODE> command line, the
full path name of the <CODE>openssl</CODE> command.


<P>Note that the module creates temporary OpenSSL configuration files
for the <CODE>req</CODE> and <CODE>ca</CODE> subcommands. 


<PRE>
%% The purpose of this module is to create example certificates for
%% testing. 
%% Run it as: 
%%
%% erl -noinput -run make_certs all &#34;/path/to/openssl&#34; -s erlang halt
%%

-module(make_certs).
-export([all/0, all/1]).

-record(dn, {commonName, 
             organizationalUnitName = &#34;Erlang OTP&#34;,
             organizationName = &#34;Ericsson AB&#34;,
             localityName = &#34;Stockholm&#34;,
             countryName = &#34;SE&#34;,
             emailAddress = &#34;peter@erix.ericsson.se&#34;}).

all() -&#62;
    all([&#34;openssl&#34;]).

all([OpenSSLCmd]) -&#62;
    Root = filename:dirname(filename:dirname((code:which(?MODULE)))),
    %% io:fwrite(&#34;Root : ~s~n&#34;, [Root]),
    NRoot = filename:join([Root, &#34;etc&#34;]), 
    file:make_dir(NRoot), 
    create_rnd(Root, &#34;etc&#34;),                    % For all requests
    rootCA(NRoot, OpenSSLCmd, &#34;erlangCA&#34;),
    intermediateCA(NRoot, OpenSSLCmd, &#34;otpCA&#34;, &#34;erlangCA&#34;),
    endusers(NRoot, OpenSSLCmd, &#34;otpCA&#34;, [&#34;client&#34;, &#34;server&#34;]),
    collect_certs(NRoot, [&#34;erlangCA&#34;, &#34;otpCA&#34;], [&#34;client&#34;, &#34;server&#34;]),
    remove_rnd(Root, &#34;etc&#34;).

rootCA(Root, OpenSSLCmd, Name) -&#62;
    create_ca_dir(Root, Name, ca_cnf(Name)),
    DN = #dn{commonName = Name},
    create_self_signed_cert(Root, OpenSSLCmd, Name, req_cnf(DN)),
    ok.

intermediateCA(Root, OpenSSLCmd, CA, ParentCA) -&#62;
    CA = &#34;otpCA&#34;, 
    create_ca_dir(Root, CA, ca_cnf(CA)),
    CARoot = filename:join([Root, CA]),
    DN = #dn{commonName = CA},
    CnfFile = filename:join([CARoot, &#34;req.cnf&#34;]),
    file:write_file(CnfFile, req_cnf(DN)),
    KeyFile = filename:join([CARoot, &#34;private&#34;, &#34;key.pem&#34;]), 
    ReqFile =  filename:join([CARoot, &#34;req.pem&#34;]), 
    create_req(Root, OpenSSLCmd, CnfFile, KeyFile, ReqFile),
    CertFile = filename:join([CARoot, &#34;cert.pem&#34;]),
    sign_req(Root, OpenSSLCmd, ParentCA, &#34;ca_cert&#34;, ReqFile, CertFile).

endusers(Root, OpenSSLCmd, CA, Users) -&#62;
    lists:foreach(fun(User) -&#62; enduser(Root, OpenSSLCmd, CA, User) end, Users).

enduser(Root, OpenSSLCmd, CA, User) -&#62; 
    UsrRoot = filename:join([Root, User]),
    file:make_dir(UsrRoot),
    CnfFile = filename:join([UsrRoot, &#34;req.cnf&#34;]),
    DN = #dn{commonName = User},
    file:write_file(CnfFile, req_cnf(DN)),
    KeyFile = filename:join([UsrRoot, &#34;key.pem&#34;]), 
    ReqFile =  filename:join([UsrRoot, &#34;req.pem&#34;]), 
    create_req(Root, OpenSSLCmd, CnfFile, KeyFile, ReqFile),
    CertFile =  filename:join([UsrRoot, &#34;cert.pem&#34;]), 
    sign_req(Root, OpenSSLCmd, CA, &#34;user_cert&#34;, ReqFile, CertFile).

collect_certs(Root, CAs, Users) -&#62;
    Bins = lists:foldr(
             fun(CA, Acc) -&#62; 
                     File = filename:join([Root, CA, &#34;cert.pem&#34;]),
                     {ok, Bin} = file:read_file(File),
                     [Bin, &#34;\n&#34; | Acc]
             end, [], CAs),
    lists:foreach(
      fun(User) -&#62;
              File = filename:join([Root, User, &#34;cacerts.pem&#34;]),
              file:write_file(File, Bins)
      end, Users).

create_self_signed_cert(Root, OpenSSLCmd, CAName, Cnf) -&#62;
    CARoot = filename:join([Root, CAName]),
    CnfFile = filename:join([CARoot, &#34;req.cnf&#34;]),
    file:write_file(CnfFile, Cnf),
    KeyFile = filename:join([CARoot, &#34;private&#34;, &#34;key.pem&#34;]), 
    CertFile = filename:join([CARoot, &#34;cert.pem&#34;]), 
    Cmd = [OpenSSLCmd, &#34; req&#34;
           &#34; -new&#34;
           &#34; -x509&#34;
           &#34; -config &#34;, CnfFile,
           &#34; -keyout &#34;, KeyFile, 
           &#34; -out &#34;, CertFile], 
    Env = [{&#34;ROOTDIR&#34;, Root}],  
    cmd(Cmd, Env).

create_ca_dir(Root, CAName, Cnf) -&#62;
    CARoot = filename:join([Root, CAName]),
    file:make_dir(CARoot),
    create_dirs(CARoot, [&#34;certs&#34;, &#34;crl&#34;, &#34;newcerts&#34;, &#34;private&#34;]),
    create_rnd(Root, filename:join([CAName, &#34;private&#34;])),
    create_files(CARoot, [{&#34;serial&#34;, &#34;01\n&#34;},
                          {&#34;index.txt&#34;, &#34;&#34;},
                          {&#34;ca.cnf&#34;, Cnf}]).

create_req(Root, OpenSSLCmd, CnfFile, KeyFile, ReqFile) -&#62;
    Cmd = [OpenSSLCmd, &#34; req&#34;
           &#34; -new&#34;
           &#34; -config &#34;, CnfFile,
           &#34; -keyout &#34;, KeyFile, 
           &#34; -out &#34;, ReqFile], 
    Env = [{&#34;ROOTDIR&#34;, Root}], 
    cmd(Cmd, Env).

sign_req(Root, OpenSSLCmd, CA, CertType, ReqFile, CertFile) -&#62;
    CACnfFile = filename:join([Root, CA, &#34;ca.cnf&#34;]),
    Cmd = [OpenSSLCmd, &#34; ca&#34;
           &#34; -batch&#34;
           &#34; -notext&#34;
           &#34; -config &#34;, CACnfFile, 
           &#34; -extensions &#34;, CertType,
           &#34; -in &#34;, ReqFile, 
           &#34; -out &#34;, CertFile],
    Env = [{&#34;ROOTDIR&#34;, Root}], 
    cmd(Cmd, Env).
    
%%
%%  Misc
%%
    
create_dirs(Root, Dirs) -&#62;
    lists:foreach(fun(Dir) -&#62;
                          file:make_dir(filename:join([Root, Dir])) end,
                  Dirs).

create_files(Root, NameContents) -&#62;
    lists:foreach(
      fun({Name, Contents}) -&#62;
              file:write_file(filename:join([Root, Name]), Contents) end,
      NameContents).

create_rnd(Root, Dir) -&#62;
    From = filename:join([Root, &#34;rnd&#34;, &#34;RAND&#34;]),
    To = filename:join([Root, Dir, &#34;RAND&#34;]),
    file:copy(From, To).

remove_rnd(Root, Dir) -&#62;
    File = filename:join([Root, Dir, &#34;RAND&#34;]),
    file:delete(File).

cmd(Cmd, Env) -&#62;
    FCmd = lists:flatten(Cmd),
    Port = open_port({spawn, FCmd}, [stream, eof, exit_status, 
                                    {env, Env}]),
    eval_cmd(Port).

eval_cmd(Port) -&#62;
    receive 
        {Port, {data, _}} -&#62;
            eval_cmd(Port);
        {Port, eof} -&#62;
            ok
    end,
    receive
        {Port, {exit_status, Status}} when Status /= 0 -&#62;
            %% io:fwrite(&#34;exit status: ~w~n&#34;, [Status]),
            erlang:halt(Status)
    after 0 -&#62;
            ok
    end.

%%
%% Contents of configuration files 
%%

req_cnf(DN) -&#62;
    [&#34;# Purpose: Configuration for requests (end users and CAs).&#34;
     &#34;\n&#34;
     &#34;ROOTDIR               = $ENV::ROOTDIR\n&#34;
     &#34;\n&#34;

     &#34;[req]\n&#34;
     &#34;input_password        = secret\n&#34;
     &#34;output_password       = secret\n&#34;
     &#34;default_bits  = 1024\n&#34;
     &#34;RANDFILE              = $ROOTDIR/RAND\n&#34;
     &#34;encrypt_key   = no\n&#34;
     &#34;default_md    = sha1\n&#34;
     &#34;#string_mask  = pkix\n&#34;
     &#34;x509_extensions       = ca_ext\n&#34;
     &#34;prompt                = no\n&#34;
     &#34;distinguished_name= name\n&#34;
     &#34;\n&#34;

     &#34;[name]\n&#34;
     &#34;commonName            = &#34;, DN#dn.commonName, &#34;\n&#34;
     &#34;organizationalUnitName        = &#34;, DN#dn.organizationalUnitName, &#34;\n&#34;
     &#34;organizationName              = &#34;, DN#dn.organizationName, &#34;\n&#34; 
     &#34;localityName          = &#34;, DN#dn.localityName, &#34;\n&#34;
     &#34;countryName           = &#34;, DN#dn.countryName, &#34;\n&#34;
     &#34;emailAddress          = &#34;, DN#dn.emailAddress, &#34;\n&#34;
     &#34;\n&#34;

     &#34;[ca_ext]\n&#34;
     &#34;basicConstraints      = critical, CA:true\n&#34;
     &#34;keyUsage              = cRLSign, keyCertSign\n&#34;
     &#34;subjectKeyIdentifier = hash\n&#34;
     &#34;subjectAltName        = email:copy\n&#34;].


ca_cnf(CA) -&#62;
    [&#34;# Purpose: Configuration for CAs.\n&#34;
     &#34;\n&#34;
     &#34;ROOTDIR               = $ENV::ROOTDIR\n&#34;
     &#34;default_ca    = ca\n&#34;
     &#34;\n&#34;

     &#34;[ca]\n&#34;
     &#34;dir           = $ROOTDIR/&#34;, CA, &#34;\n&#34;
     &#34;certs         = $dir/certs\n&#34;
     &#34;crl_dir               = $dir/crl\n&#34;
     &#34;database              = $dir/index.txt\n&#34;
     &#34;new_certs_dir = $dir/newcerts\n&#34;
     &#34;certificate   = $dir/cert.pem\n&#34;
     &#34;serial                = $dir/serial\n&#34;
     &#34;crl           = $dir/crl.pem\n&#34;
     &#34;private_key   = $dir/private/key.pem\n&#34;
     &#34;RANDFILE              = $dir/private/RAND\n&#34;
     &#34;\n&#34;
     &#34;x509_extensions   = user_cert\n&#34;
     &#34;default_days  = 3600\n&#34;
     &#34;default_md    = sha1\n&#34;
     &#34;preserve              = no\n&#34;
     &#34;policy                = policy_match\n&#34;
     &#34;\n&#34;

     &#34;[policy_match]\n&#34;
     &#34;commonName            = supplied\n&#34;
     &#34;organizationalUnitName        = optional\n&#34;
     &#34;organizationName              = match\n&#34;
     &#34;countryName           = match\n&#34;
     &#34;localityName          = match\n&#34;
     &#34;emailAddress          = supplied\n&#34;
     &#34;\n&#34;

     &#34;[user_cert]\n&#34;
     &#34;basicConstraints      = CA:false\n&#34;
     &#34;keyUsage              = nonRepudiation, digitalSignature, keyEncipherment\n&#34;
     &#34;subjectKeyIdentifier = hash\n&#34;
     &#34;authorityKeyIdentifier = keyid,issuer:always\n&#34;
     &#34;subjectAltName        = email:copy\n&#34;
     &#34;issuerAltName = issuer:copy\n&#34;
     &#34;\n&#34;

     &#34;[ca_cert]\n&#34;
     &#34;basicConstraints      = critical,CA:true\n&#34;
     &#34;keyUsage              = cRLSign, keyCertSign\n&#34;
     &#34;subjectKeyIdentifier = hash\n&#34;
     &#34;authorityKeyIdentifier = keyid:always,issuer:always\n&#34;
     &#34;subjectAltName        = email:copy\n&#34;
     &#34;issuerAltName = issuer:copy\n&#34;].



</PRE>
<CENTER>
<HR>
<SMALL>
Copyright &copy; 1991-2004
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>