Skip to content

Commit

Permalink
Revert "Delete the Projects/NSS tree (#8215)"
Browse files Browse the repository at this point in the history
This reverts commit b2effa6.
  • Loading branch information
escattone authored Aug 23, 2021
1 parent e317eb6 commit d972f74
Show file tree
Hide file tree
Showing 365 changed files with 60,933 additions and 0 deletions.

Large diffs are not rendered by default.

35 changes: 35 additions & 0 deletions files/en-us/mozilla/projects/nss/blank_function/index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
---
title: Function_Name
slug: Mozilla/Projects/NSS/Blank_Function
tags:
- NSS
---
<p>
One-line description of what the function does (more than just what it returns).
</p>
<h3 id="Syntax"> Syntax </h3>
<pre>#include &lt;headers.h&gt;
ReturnType Function_Name(

ParamType ParamName,
ParamType ParamName, );
</pre>
<h3 id="Parameters"> Parameters </h3>
<table>
<tbody><tr><td><code>ParamName</code></td> <td>Sample: <i>in</i> pointer to a <a href="/en-US/NSS/CERTCertDBHandle">CERTCertDBHandle</a> representing the certificate database to look in</td></tr> <tr><td><code>ParamName</code></td> <td>Sample: <i>in</i> pointer to an <a href="/en-US/NSS/SECItem">SECItem</a> whose <code>type</code> must be <code>siDERCertBuffer</code> and whose <code>data</code> contains a DER-encoded certificate</td></tr>
</tbody></table>
<h3 id="Description"> Description </h3>
<p>Long description of this function, what it does, and why you would use it. Describe all side-effects on "out" parameters. Avoid describing the return until the next section, for example:
</p><p>This function looks in the NSSCryptoContext and the NSSTrustDomain to find
the certificate that matches the DER-encoded certificate. A match is found
when the issuer and serial number of the DER-encoded certificate are found on
a certificate in the certificate database.
</p>
<h3 id="Returns"> Returns </h3>
<p>Full description of the return value, for example:
</p><p>A pointer to a <a href="/en-US/NSS/CERTCertificate">CERTCertificate</a> representing the certificate in the database that matched the <code>derCert</code>, or <code>NULL</code> if none was found. The certificate is a shallow copy, use <a href="/en-US/NSS/CERT_DestroyCertificate">CERT_DestroyCertificate</a> to decrement the reference count on the certificate instance.
</p>
<h3 id="See_Also"> See Also </h3>
<p>Copy of the MXR link, with the following text
</p><p>Occurrences of <code>Function_Name</code> in the current NSS source code (generated by MXR).
</p>
109 changes: 109 additions & 0 deletions files/en-us/mozilla/projects/nss/building/index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
---
title: Building NSS
slug: Mozilla/Projects/NSS/Building
tags:
- Guide
- NSS
- Security
---
<h2 id="Introduction">Introduction</h2>

<p>This page has detailed information on how to build NSS. Because NSS is a cross-platform library that builds on many different platforms and has many options, it may be complex to build. Please read these instructions carefully before attempting to build.</p>

<h2 id="Build_environment">Build environment</h2>

<p>NSS needs a C and C++ compiler.  It has minimal dependencies, including only standard C and C++ libraries, plus <a href="https://www.zlib.net/">zlib</a>.</p>

<p>For building, you also need <a href="https://www.gnu.org/software/make/">make</a>.  Ideally, also install <a href="https://gyp.gsrc.io/">gyp</a> and <a href="https://ninja-build.org/">ninja</a> and put them on your path.  This is recommended, as the build is faster and more reliable.</p>

<h3 id="Windows">Windows</h3>

<p>NSS compilation on Windows uses the same shared build system as Mozilla Firefox. You must first install the <a href="/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Windows_Prerequisites">Windows Prerequisites</a>, including <strong>MozillaBuild</strong>.</p>

<p>You can also build NSS on the Windows Subsystem for Linux, but the resulting binaries aren't usable by other Windows applications.</p>

<h2 id="Get_the_source">Get the source</h2>

<p>NSS and NSPR use Mercurial for source control like other Mozilla projects. To check out the latest sources for NSS and NSPR--which may not be part of a stable release--use the following commands:</p>

<pre>hg clone https://hg.mozilla.org/projects/nspr
hg clone https://hg.mozilla.org/projects/nss
</pre>

<p>To get the source of a specific release, see <a href="/en-US/docs/Mozilla/Projects/NSS/NSS_Releases">NSS Releases</a>.</p>


<h2 id="Build">Build</h2>

<p>Build NSS using our build script:</p>

<pre>nss/build.sh
</pre>

<p>This builds both NSPR and NSS.</p>

<h2 id="Build_with_make">Build with make</h2>

<p>Alternatively, there is a <code>make</code> target called "nss_build_all", which produces a similar result.  This supports some alternative options, but can be a lot slower.</p>

<pre>make -C nss nss_build_all USE_64=1
</pre>

<p>The make-based build system for NSS uses a variety of variables to control the build. Below are some of the variables, along with possible values they may be set to.</p>

<dl>
<dt>BUILD_OPT</dt>
<dd>
<dl>
<dt>0</dt>
<dd>Build a debug (non-optimized) version of NSS. <em>This is the default.</em></dd>
<dt>1</dt>
<dd>Build an optimized (non-debug) version of NSS.</dd>
</dl>
</dd>
<dt>USE_64</dt>
<dd>
<dl>
<dt>0</dt>
<dd>Build for a 32-bit environment/ABI. <em>This is the default.</em></dd>
<dt>1</dt>
<dd>Build for a 64-bit environment/ABI. <em>This is recommended.</em></dd>
</dl>
</dd>
<dt>USE_ASAN</dt>
<dd>
<dl>
<dt>0</dt>
<dd>Do not create an <a href="http://clang.llvm.org/docs/AddressSanitizer.html">AddressSanitizer</a> build. <em>This is the default.</em></dd>
<dt>1</dt>
<dd>Create an AddressSanitizer build.</dd>
</dl>
</dd>
</dl>

<h2 id="Unit_testing">Unit testing</h2>

<p>NSS contains extensive unit tests.  Scripts to run these are found in the <code>tests</code> directory.  Run the standard suite by:</p>

<pre>HOST=localhost DOMSUF=localdomain USE_64=1 nss/tests/all.sh</pre>

<h3 id="Unit_test_configuration">Unit test configuration</h3>

<p>NSS tests are configured using environment variables.<br>
The scripts will attempt to infer values for <code>HOST</code> and <code>DOMSUF</code>, but can fail. Replace <code>localhost</code> and <code>localdomain</code> with the hostname and domain suffix for your host. You need to be able to connect to <code>$HOST.$DOMSUF</code>.</p>

<p>If you don't have a domain suffix you can add an entry to <code>/etc/hosts</code> (on Windows,<code> c:\Windows\System32\drivers\etc\hosts</code>) as follows:</p>

<pre><code>127.0.0.1 localhost.localdomain</code></pre>

<p>Validate this opening a command shell and typing: <code>ping localhost.localdomain</code>.</p>

<p>Remove the <code>USE_64=1</code> override if using a 32-bit build.</p>

<h3 id="Test_results">Test results</h3>

<p>Running all tests can take a considerable amount of time.</p>

<p>Test output is stored in <code>tests_results/security/$HOST.$NUMBER/</code>.  The file <code>results.html</code> summarizes the results, <code>output.log</code> captures all the test output.</p>

<p>Other subdirectories of <code>nss/tests</code> contain scripts that run a subset of the full suite. Those can be run directly instead of <code>all.sh</code>, which might save some time at the cost of coverage.</p>
32 changes: 32 additions & 0 deletions files/en-us/mozilla/projects/nss/cert_findcertbydercert/index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
title: CERT_FindCertByDERCert
slug: Mozilla/Projects/NSS/CERT_FindCertByDERCert
tags:
- NSS
---
<p>
Find a certificate in the database that matches a DER-encoded certificate.
</p>
<h3 id="Syntax"> Syntax </h3>
<pre>#include &lt;cert.h&gt;
CERTCertificate *CERT_FindCertByDERCert(

CERTCertDBHandle *handle,
SECItem *derCert );
</pre>
<h3 id="Parameters"> Parameters </h3>
<table>
<tbody><tr><td><code>handle </code></td> <td><i>in</i> pointer to a <a href="/en-US/NSS/CERTCertDBHandle">CERTCertDBHandle</a> representing the certificate database to look in</td></tr> <tr><td><code>derCert </code></td> <td><i>in</i> pointer to an <a href="/en-US/NSS/SECItem">SECItem</a> whose <code>type</code> must be <code>siDERCertBuffer</code> and whose <code>data</code> contains a DER-encoded certificate</td></tr>
</tbody></table>
<h3 id="Description"> Description </h3>
<p>This function looks in the ?NSSCryptoContext? and the ?NSSTrustDomain? to find
the certificate that matches the DER-encoded certificate. A match is found
when the issuer and serial number of the DER-encoded certificate are found on
a certificate in the certificate database.
</p>
<h3 id="Returns"> Returns </h3>
<p>A pointer to a <a href="/en-US/NSS/CERTCertificate">CERTCertificate</a> representing the certificate in the database that matched the <code>derCert</code>, or <code>NULL</code> if none was found. The certificate is a shallow copy, use <a href="/en-US/NSS/CERT_DestroyCertificate">CERT_DestroyCertificate</a> to decrement the reference count on the certificate instance.
</p>
<h3 id="See_Also"> See Also </h3>
<p>Occurrences of <a class="external" href="http://lxr.mozilla.org/security/ident?i=CERT_FindCertByDERCert"><code>CERT_FindCertByDERCert</code></a> in the current NSS source code (generated by <a class="external" href="http://lxr.mozilla.org/security/">LXR</a>).
</p>
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
title: CERT_FindCertByIssuerAndSN
slug: Mozilla/Projects/NSS/CERT_FindCertByIssuerAndSN
tags:
- NSS
---
<p>
Find a certificate in the database with the given issuer and serial number.
</p>
<h3 id="Syntax"> Syntax </h3>
<pre>#include &lt;cert.h&gt;
CERTCertificate *CERT_FindCertByIssuerAndSN (

CERTCertDBHandle *handle,
CERTIssuerAndSN *issuerAndSN );
</pre>
<h3 id="Parameters"> Parameters </h3>
<table>
<tbody><tr><td><code>handle</code></td> <td><i>in</i> pointer to a <a href="/en-US/NSS/CERTCertDBHandle">CERTCertDBHandle</a> representing the certificate database to look in</td></tr> <tr><td><code>issuerAndSN</code></td> <td><i>in</i> pointer to a <a href="/en-US/NSS/CERTIssuerAndSN">CERTIssuerAndSN</a> that must be properly formed to contain the issuer name and the serial number (see {{ mediawiki.external('Example') }})</td></tr>
</tbody></table>
<h3 id="Description"> Description </h3>
<p>This function creates a certificate key using the <code>issuerAndSN</code> and it then
uses the key to find the matching certificate in the database.
</p>
<h3 id="Returns"> Returns </h3>
<p>A pointer to a <a href="/en-US/NSS/CERTCertificate">CERTCertificate</a> representing the certificate in the database that matched the issuer and serial number, or <code>NULL</code> if none was found. The certificate is a shallow copy, use <a href="/en-US/NSS/CERT_DestroyCertificate">CERT_DestroyCertificate</a> to decrement the reference count on the certificate instance.
</p>
<h3 id="Example"> Example </h3>
<pre>CERTIssuerAndSN issuerSN;
issuerSN.derIssuer.data = caName-&gt;data;
issuerSN.derIssuer.len = caName-&gt;len;
issuerSN.serialNumber.data = authorityKeyID-&gt;authCertSerialNumber.data;
issuerSN.serialNumber.len = authorityKeyID-&gt;authCertSerialNumber.len;
issuerCert = CERT_FindCertByIssuerAndSN(cert-&gt;dbhandle, &amp;issuerSN);
if ( issuerCert == NULL ) {
PORT_SetError (SEC_ERROR_UNKNOWN_ISSUER);
}
</pre>
<h3 id="See_Also"> See Also </h3>
<p>Occurrences of <a class="external" href="http://lxr.mozilla.org/security/ident?i=CERT_FindCertByIssuerAndSN"><code>CERT_FindCertByIssuerAndSN</code></a> in the current NSS source code (generated by <a class="external" href="http://lxr.mozilla.org/security/">LXR</a>).
</p>
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
---
title: NSS Certificate Download Specification
slug: Mozilla/Projects/NSS/Certificate_Download_Specification
tags:
- NSS
---
<p>This document describes the data formats used by NSS 3.x for installing certificates. This document is currently being revised and has not yet been reviewed for accuracy.</p>

<h2 id="Data_Formats">Data Formats</h2>

<p>NSS can accept certificates in several formats. In all cases the certificates are X509 version 1, 2, or 3.</p>

<h3 id="Binary_Formats">Binary Formats</h3>

<p>NSS's certificate loader will recognize several binary formats. They are:</p>

<ul>
<li><strong>DER encoded certificate:</strong> This is a single binary DER encoded certificate.</li>
<li><strong>PKCS#7 certificate chain:</strong> This is a single <a class="link-ftp" href="ftp://ftp.rfc-editor.org/in-notes/rfc2315.txt">PKCS#7</a> <code>SignedData</code> object. The only significant field in the <code>SignedData</code> object is the <code>certificates</code> field, which may contain multiple certificates to be imported together. The contents of the <code>version</code>, <code>digestAlgorithms</code>, <code>contentInfo</code>, <code>crls</code>, and <code>signerInfos</code> fields are ignored.</li>
<li><strong>Netscape Certificate Sequence:</strong> This is another <a class="link-ftp" href="ftp://ftp.rfc-editor.org/in-notes/rfc2315.txt">PKCS#7</a> object format, and like the <code>SignedData</code> format, it allows multiple certificates to be imported together. This format is simpler than the <a class="link-ftp" href="ftp://ftp.rfc-editor.org/in-notes/rfc2315.txt">PKCS#7</a> <code>SignedData</code> object format. It consists of a <a class="link-ftp" href="ftp://ftp.rfc-editor.org/in-notes/rfc2315.txt">PKCS#7</a> <code>ContentInfo</code> structure, wrapping a sequence of certificates. The <code>contentType</code> field OID must be <code>netscape-cert-sequence</code> (see <a href="/en-US/docs/Mozilla/Projects/NSS/Certificate_Download_Specification#object_identifiers">Object Identifiers</a>). The <code>content</code> field is the following ASN.1 structure:</li>
</ul>

<pre class="eval"> CertificateSequence ::= SEQUENCE OF Certificate
</pre>

<p>See the section below on <a href="/en-US/docs/Mozilla/Projects/NSS/Certificate_Download_Specification#importing_certificate_chains">Certificate Chains</a> for more information about how multiple certificates are handled.</p>

<h3 id="Text_Formats">Text Formats</h3>

<p>Any of the above <a href="/en-US/docs/Mozilla/Projects/NSS/Certificate_Download_Specification#binary_formats">binary formats</a> can also be imported in text form. The text form begins with the following line:</p>

<pre class="eval"> -----BEGIN CERTIFICATE-----
</pre>

<p>Following this line should be the certificate data, which can be in any of the <a href="/en-US/docs/Mozilla/Projects/NSS/Certificate_Download_Specification#binary_formats">binary formats</a> described above. This data must be base64 encoded as described by <a class="external" href="https://datatracker.ietf.org/doc/html/rfc1113">RFC 1113</a>. Following the data should be the following line:</p>

<pre class="eval"> -----END CERTIFICATE-----
</pre>

<p>In a text format download, NSS ignores any text before the first <code>BEGIN CERTIFICATE</code> line, and ignores any text after the first <code>END CERTIFICATE</code> line. Between those two lines, there must be exactly ONE item of any of the supported binary formats described above, and that one item must be base64 encoded. Regardless of which of the supported binary formats is used, the <code>BEGIN</code> and <code>END</code> lines must say <code>CERTIFICATE</code>, and not any other word (such as <code>KEY</code>). The <code>BEGIN</code> and <code>END</code> lines must begin and end with 5 dashes, with no extra leading or trailing white space (excluding the End Of Line characters).</p>

<h2 id="Importing_Certificate_Chains">Importing Certificate Chains</h2>

<p>Several of the formats described above can contain several certificates. When NSS's certificate decoder encounters one of these collections of multiple certificates they are handled in the following way:</p>

<ul>
<li>The first certificate is processed in a context specific manner, depending upon how it is being imported. For Mozilla browsers, this handling will depend upon the mime <code>Content-Type</code> that is used on the object being downloaded. For NSS-based servers it will depend upon the options selected in the server's administration interface.</li>
</ul>

<ul>
<li>Subsequent certificates are all treated the same. If the certificates contain a <code>BasicConstraints</code> certificate extension that indicates they are CA certificates, and do not already exist in the local certificate database, they are added as untrusted CAs. In this way they may be used for certificate chain validation, as long as there is a trusted CA somewhere along the chain.</li>
</ul>

<h3 id="Importing_Certificates_into_Mozilla_browsers">Importing Certificates into Mozilla browsers</h3>

<p>Mozilla browsers import certificates found in HTTP protocol responses. There are several mime content types that are used to indicate to the browser what type of certificate is being imported. These mime types are:</p>

<ul>
<li><strong><code>application/x-x509-user-cert</code></strong> The certificate being downloaded is a user certificate belonging to the user operating the browser. If the private key associated with the certificate does not exist in the user's local key database, then an error dialog is generated and the certificate is not imported. If a certificate chain is being imported then the first certificate in the chain must be the user certificate, and any subsequent certificates will be added as untrusted CA certificates to the local database.</li>
<li><strong><code>application/x-x509-ca-cert</code></strong> The certificate being downloaded represents a Certificate Authority. When it is downloaded the user will be shown a sequence of dialogs that will guide them through the process of accepting the Certificate Authority and deciding if they wish to trust sites certified by the CA. If a certificate chain is being imported then the first certificate in the chain must be the CA certificate, and any subsequent certificates will be added as untrusted CA certificates to the local database.</li>
<li><strong><code>application/x-x509-email-cert</code></strong> The certificate being downloaded is a user certificate belonging to another user for use with S/MIME. If a certificate chain is being imported then the first certificate in the chain must be the user certificate, and any subsequent certificates will be added as untrusted CA certificates to the local database. This is intended to allow people or CAs to post their e-mail certificates on web pages for download by other users who want to send them encrypted mail.</li>
</ul>

<p>Note: the browser checks that the size of the object being downloaded matches the size of the encoded certificates. Therefore it is important to ensure that no extra characters, such as NULLs or LineFeeds are added at the end of the object.</p>

<h3 id="Importing_Certificates_into_NSS-based_servers">Importing Certificates into NSS-based servers</h3>

<p>Consult your server's administration guide for the most accurate information. For some NSS-base servers, the following information is correct.</p>

<p>Server certificates are imported via the server admin interface. Certificates are pasted into a text input field in an HTML form, and then the form is submitted to the admin server. Since the certificates are pasted into text fields, only the <a href="/en-US/docs/Mozilla/Projects/NSS/Certificate_Download_Specification#text_formats">text formats</a> described above are supported for servers. The type of certificate being imported (e.g. server or CA or cert chain) is specified by the server administrator by selections made on the admin pages. If a certificate chain is being imported then the first certificate in the chain must be the server or CA certificate, and any subsequent certificates will be added as untrusted CA certificates to the local database.</p>

<h2 id="Object_Identifiers">Object Identifiers</h2>

<p>The base of all Netscape object ids is:</p>

<pre class="eval"> netscape OBJECT IDENTIFIER ::= { 2 16 840 1 113730 }
</pre>

<p>The hexadecimal byte value of this OID when DER encoded is:</p>

<pre class="eval"> 0x60, 0x86, 0x48, 0x01, 0x86, 0xf8, 0x42
</pre>

<p>The following OIDs are mentioned in this document:</p>

<pre class="eval"> netscape-data-type OBJECT IDENTIFIER :: = { netscape 2 }
netscape-cert-sequence OBJECT IDENTIFIER :: = { netscape-data-type 5 }
</pre>
Loading

0 comments on commit d972f74

Please sign in to comment.