← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to lib/ssl/doc/src/pkix_certs.xml

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/ssl/doc/src/pkix_certs.xml
34
34
    <p>Certificates were originally defined by ITU (CCITT) and the latest 
35
35
      definitions are described in <cite id="X.509"></cite>, but those definitions
36
36
      are (as always) not working. 
37
 
      </p>
 
37
    </p>
38
38
    <p>Working certificate definitions for the Internet Community are found
39
 
      in the the PKIX RFCs <cite id="rfc3279"></cite>and <cite id="rfc3280"></cite>. 
 
39
      in the the PKIX RFCs <cite id="rfc3279"></cite> and <cite id="rfc3280"></cite>. 
40
40
      The parsing of certificates in the Erlang/OTP SSL application is
41
41
      based on those RFCS. 
42
 
      </p>
 
42
    </p>
43
43
    <p>Certificates are defined in terms of ASN.1 (<cite id="X.680"></cite>).
44
44
      For an introduction to ASN.1 see <url href="http://asn1.elibel.tm.fr/">ASN.1 Information Site</url>.
45
 
      </p>
 
45
    </p>    
46
46
  </section>
47
47
 
48
48
  <section>
49
49
    <title>PKIX Certificates</title>
50
 
    <p>Here we base the PKIX certificate definitions in RFCs <cite id="rfc3279"></cite>and <cite id="rfc3280"></cite>. We however present the
51
 
      definitions according to <c>SSL-PKIX.asn1</c> module, 
52
 
      which is an amelioration of the <c>PKIX1Explicit88.asn1</c>, 
53
 
      <c>PKIX1Implicit88.asn1</c>, and <c>PKIX1Algorithms88.asn1</c>
54
 
      modules. You find all these modules in the <c>pkix</c> subdirectory
55
 
      of SSL. 
56
 
      </p>
57
 
    <p>The Erlang terms that are returned by the functions
58
 
      <c>ssl:peercert/1/2</c>, <c>ssl_pkix:decode_cert/1/2</c>, and
59
 
      <c>ssl_pkix:decode_cert_file/1/2</c> when the option <c>ssl</c>
60
 
      is used in those functions, correspond the ASN.1 structures
61
 
      described in the sequel. 
62
 
      </p>
63
 
 
64
 
    <section>
65
 
      <title>Certificate and TBSCertificate</title>
66
 
      <code type="none">
67
 
Certificate  ::=  SEQUENCE  {
68
 
     tbsCertificate       TBSCertificate,
69
 
     signatureAlgorithm   SignatureAlgorithm,
70
 
     signature            BIT STRING }
71
 
 
72
 
TBSCertificate  ::=  SEQUENCE  {
73
 
     version         [0]  Version DEFAULT v1,
74
 
     serialNumber         CertificateSerialNumber,
75
 
     signature            SignatureAlgorithm,
76
 
     issuer               Name,
77
 
     validity             Validity,
78
 
     subject              Name,
79
 
     subjectPublicKeyInfo SubjectPublicKeyInfo,
80
 
     issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
81
 
                          -- If present, version MUST be v2 or v3
82
 
     subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
83
 
                          -- If present, version MUST be v2 or v3
84
 
     extensions      [3]  Extensions OPTIONAL
85
 
                          -- If present, version MUST be v3 --  }
86
 
 
87
 
Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
88
 
 
89
 
CertificateSerialNumber  ::=  INTEGER
90
 
 
91
 
Validity ::= SEQUENCE {
92
 
     notBefore      Time,
93
 
     notAfter       Time  }
94
 
 
95
 
Time ::= CHOICE {
96
 
     utcTime        UTCTime,
97
 
     generalTime    GeneralizedTime }
98
 
      </code>
99
 
      <p>The meaning of the fields <c>version</c>, <c>serialNumber</c>,
100
 
        and <c>validity</c> are quite obvious given the type definitions
101
 
        above, so we do not go further into their details. 
102
 
        </p>
103
 
      <p>The <c>signatureAlgorithm</c> field of <c>Certificate</c> and
104
 
        the <c>signature</c> field of <c>TBSCertificate</c> contain
105
 
        the name and parameters of the algorithm used for signing the
106
 
        certificate. The values of these two fields must be equal.
107
 
        </p>
108
 
      <p>The <c>signature</c> field of <c>Certificate</c> contains the
109
 
        value of the signature that the issuer computed by using the 
110
 
        prescribed algorithm.
111
 
        </p>
112
 
      <p>The <c><![CDATA[issuer<c> and <c>subject]]></c> fields can contain many 
113
 
        different types av data, and is therefore considered in a 
114
 
        separate section. The same holds for the <c>extensions</c>
115
 
        field. 
116
 
        The <c>issuerUniqueID</c> and the <c>subjectUniqueID</c> fields 
117
 
        are not considered further.</p>
118
 
    </section>
119
 
 
120
 
    <section>
121
 
      <title>TBSCertificate issuer and subject</title>
122
 
      <p></p>
123
 
      <code type="none"><![CDATA[
124
 
Name ::= CHOICE { -- only one possibility for now --
125
 
      rdnSequence  RDNSequence }
126
 
 
127
 
RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
128
 
 
129
 
DistinguishedName ::=   RDNSequence
130
 
 
131
 
RelativeDistinguishedName  ::=
132
 
                    SET SIZE (1 .. MAX) OF AttributeTypeAndValue
133
 
 
134
 
AttributeTypeAndValue ::=  SEQUENCE {
135
 
        type    ATTRIBUTE-TYPE-AND-VALUE-CLASS.&id
136
 
\011\011({SupportedAttributeTypeAndValues}),
137
 
        value   ATTRIBUTE-TYPE-AND-VALUE-CLASS.&Type
138
 
\011\011({SupportedAttributeTypeAndValues}{@type}) }
139
 
 
140
 
SupportedAttributeTypeAndValues ATTRIBUTE-TYPE-AND-VALUE-CLASS ::= 
141
 
\011{ name | surname | givenName | initials | generationQualifier |
142
 
\011  commonName | localityName | stateOrProvinceName | organizationName |
143
 
\011  organizationalUnitName | title | dnQualifier | countryName |
144
 
\011  serialNumber | pseudonym | domainComponent | emailAddress }      ]]></code>
145
 
    </section>
146
 
 
147
 
    <section>
148
 
      <title>TBSCertificate extensions</title>
149
 
      <p>The <c>extensions</c> field of a <c>TBScertificate</c> is a 
150
 
        sequence of type <c>Extension</c>, defined as follows,</p>
151
 
      <code type="none">
152
 
Extension  ::=  SEQUENCE  {
153
 
     extnID      OBJECT IDENTIFIER,
154
 
     critical    BOOLEAN DEFAULT FALSE,
155
 
     extnValue   ANY }      </code>
156
 
      <p>Each extension has a unique object identifier. An extension
157
 
        with a <c>critical</c> value set to <c>TRUE</c><em>must</em>
158
 
        be recognised by the reader of a certificate, or else the
159
 
        certificate must be rejected.
160
 
        </p>
161
 
      <p>Extensions are divided into two groups: standard extensions
162
 
        and internet certificate extensions. All extensions listed in
163
 
        the table that follows are standard extensions, except for
164
 
        <c>authorityInfoAccess</c> and <c>subjectInfoAccess</c>, which
165
 
        are internet extensions.
166
 
        </p>
167
 
      <p>Depending on the object identifier the <c>extnValue</c> is
168
 
        parsed into an appropriate welldefined structure. 
169
 
        </p>
170
 
      <p>The following table shows the purpose of each extension, but
171
 
        does not specify the structure. To see the structure consult
172
 
        the <c>PKIX1Implicit88.asn1</c> module.
173
 
        </p>
174
 
      <table>
175
 
        <row>
176
 
          <cell align="left" valign="middle">authorityKeyIdentifier</cell>
177
 
          <cell align="left" valign="middle">Used by to identify a certificate signed that has multiple signing keys. </cell>
178
 
        </row>
179
 
        <row>
180
 
          <cell align="left" valign="middle">subjectKeyIdentifier</cell>
181
 
          <cell align="left" valign="middle">Used to identify certificates that contain a public key.  Must appear i CA certificates.</cell>
182
 
        </row>
183
 
        <row>
184
 
          <cell align="left" valign="middle">keyUsage </cell>
185
 
          <cell align="left" valign="middle">Defines the purpose of the certificate. Can be one or several of<c>digitalSignature</c>, <c>nonRepudiation</c>,<c>keyEncipherment</c>, <c>dataEncipherment</c>,<c>keyAgreement</c>, <c>keyCertSign</c>, <c>cRLSign</c>,<c>encipherOnly</c>, <c>decipherOnly</c>.</cell>
186
 
        </row>
187
 
        <row>
188
 
          <cell align="left" valign="middle">privateKeyUsagePeriod </cell>
189
 
          <cell align="left" valign="middle">Allows certificate issuer to provide a private key usage period to be short than the certificate usage period.</cell>
190
 
        </row>
191
 
        <row>
192
 
          <cell align="left" valign="middle">certificatePolicies</cell>
193
 
          <cell align="left" valign="middle">Contains one or more policy information terms indicating the policies under which the certificate has been issued.</cell>
194
 
        </row>
195
 
        <row>
196
 
          <cell align="left" valign="middle">policyMappings</cell>
197
 
          <cell align="left" valign="middle">Used i CA certificates. </cell>
198
 
        </row>
199
 
        <row>
200
 
          <cell align="left" valign="middle">subjectAltName</cell>
201
 
          <cell align="left" valign="middle">Allows additional identities to be bound the the subject. </cell>
202
 
        </row>
203
 
        <row>
204
 
          <cell align="left" valign="middle">issuerAltName</cell>
205
 
          <cell align="left" valign="middle">Allows additional identities to be bound the the issuer.</cell>
206
 
        </row>
207
 
        <row>
208
 
          <cell align="left" valign="middle">subjectDirectoryAttributes</cell>
209
 
          <cell align="left" valign="middle">Conveys identity attributes of the subject.</cell>
210
 
        </row>
211
 
        <row>
212
 
          <cell align="left" valign="middle">basicConstraints</cell>
213
 
          <cell align="left" valign="middle">Tells if the certificate holder is a CA or not.</cell>
214
 
        </row>
215
 
        <row>
216
 
          <cell align="left" valign="middle">nameConstraints</cell>
217
 
          <cell align="left" valign="middle">Used in CA certificates.</cell>
218
 
        </row>
219
 
        <row>
220
 
          <cell align="left" valign="middle">policyConstraints</cell>
221
 
          <cell align="left" valign="middle">Used in CA certificates.</cell>
222
 
        </row>
223
 
        <row>
224
 
          <cell align="left" valign="middle">extKeyUsage</cell>
225
 
          <cell align="left" valign="middle">Indicates for which purposed the public key may be used. </cell>
226
 
        </row>
227
 
        <row>
228
 
          <cell align="left" valign="middle">cRLDistributionPoints</cell>
229
 
          <cell align="left" valign="middle">Indicates how CRL (Certificate Revokation List) information is obtained.</cell>
230
 
        </row>
231
 
        <row>
232
 
          <cell align="left" valign="middle">inhibitAnyPolicy</cell>
233
 
          <cell align="left" valign="middle">Used i CA certificates.</cell>
234
 
        </row>
235
 
        <row>
236
 
          <cell align="left" valign="middle">freshestCRL</cell>
237
 
          <cell align="left" valign="middle">For CRLs.</cell>
238
 
        </row>
239
 
        <row>
240
 
          <cell align="left" valign="middle">authorityInfoAccess</cell>
241
 
          <cell align="left" valign="middle">How to access CA information of the issuer of the certificate.</cell>
242
 
        </row>
243
 
        <row>
244
 
          <cell align="left" valign="middle">subjectInfoAccess</cell>
245
 
          <cell align="left" valign="middle">How to access CA information of the subject of the certificate.</cell>
246
 
        </row>
247
 
        <tcaption>PKIX Extensions</tcaption>
248
 
      </table>
249
 
    </section>
 
50
    <p>Certificate handling is now handled by the <c>public_key</c> application.</p>
 
51
    <p>
 
52
      DER encoded certificates returned by <c>ssl:peercert/1</c> can for example 
 
53
      be decoded by the <c>public_key:pkix_decode_cert/2</c> function. 
 
54
    </p>
250
55
  </section>
251
56
</chapter>
252
57