Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

executable file 40 lines (39 sloc) 9.649 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
<head>
<title>XMPP ICA: Certificate Issuance HOWTO</title>
<!--#include virtual="/includes/head.txt" -->
<h2>XMPP ICA: Certificate Issuance HOWTO</h2>
<p>The <a href='/ca/'>XMPP Intermediate Certification Authority (ICA)</a> issues free domain certificates to administrators of XMPP-based services, where the root CA is <a href='http://www.startssl.com/'>StartCom</a>. The certificate issuance process is described on this page (the same process applies to certificate renewal if you still have the CSR, as mentioned below). If you have any questions throughout this process, feel free to contact <a href='https://stpeter.im/index.php/contact/'>Peter Saint-Andre</a> via email or (for faster service) IM.</p>
<ol start='1'>
  <li>
    <p>Before proceeding, please make sure that:</p>
    <ol style='list-style: lower-alpha'>
      <li>
        <p>You have access to the one of the following email addresses:</p>
        <ul>
          <li><p>Hostmaster, postmaster, or webmaster @ your domain (see <a href='http://tools.ietf.org/html/rfc2142'>RFC 2142</a>).</p></li>
          <li><p>The registrant, administrative, or technical email address listed in <a href='whois.shtml'>Whois</a> for your domain (see <a href='http://tools.ietf.org/html/rfc3912'>RFC 3192</a>).</p></li>
        </ul>
      </li>
      <li><p>Your domain registrar offers a native <a href='whois.shtml'>Whois</a> service (not just a web-based interface to Whois). <em>NOTE: If your domain registrar uses an "unofficial" Whois server (such that the domain can be checked only via the "-h" flag in the whois command), please let us know by sending email to "certmaster at xmpp.org" after completing your certificate request; we can issue a certificate for your domain, but it must be checked manually.</em></p></li>
      <li><p>Your domain is registered with a recognized domain registrar, not a <a href='dynamic-dns.shtml'>Dynamic DNS</a> service.</p></li>
    </ol>
  </li>
  <li><p>Visit the <a href='launch.shtml'>Certificate Launch Page</a>, provide the requested information (which is sent to StartCom on submission), and click the Submit button.</p></li>
  <li><p>A new browser window or tab will open, sending you to <a href='https://xmpp.startcom.org/'>https://xmpp.startcom.org/</a> -- the web interface for users of the intermediate certification authority (ICA). <em>(NOTE: You cannot access that website from anywhere else but the Certificate Launch Page, so don't try to type it into your browser!)</em></p></li>
  <li><p>The ICA website provides a 'wizard' that will walk you through the certificate request process. Detailed instructions are provided below.</p></li>
  <li><p>On the first page of the wizard, you will be asked to choose between "Server Certificate (With CSR generation)" and "Server Certificate (Without CSR generation)". If you want StartCom to create the Certificate Signing Request (CSR) for you (this is easier but gives you less control), then choose "with CSR generation". If you want to create your own Certificate Signing Request (CSR) using a tool such as <a href='http://www.openssl.org/'>OpenSSL</a> or your XMPP server software, or if you wish to re-use the CSR associated with a previously-issued certificate, choose "without CSR generation". Make your choice and then click "Continue".</p></li>
  <li><p>On the second page, your personal information should be pre-populated from the Certificate Launch page. Please provide a complete first name and last name (not just initials), a working email address, your postal address (including street, postal or ZIP code, city, and country), and a working phone number (this can be a business number) with country code and, if necessary, internal extension. <em>(NOTE: The organization name, city, and state/region must contain only ASCII characters as required by the X.509 specification.)</em> Check the details and then click "Continue".</p></li>
  <li><p>If you chose "with CSR generation" you will be asked to provide a password for your private key (so that you can decrypt it later in the process). Make sure that you remember the password! Enter the password and then click "Continue". The wizard will load a new page that shows your private key. Make sure that you copy the key because you will need it later in the process! It is best to copy the key to an ASCII file (e.g., "domain.key") on the machine that hosts your XMPP server and possibly back it up in a secure location. Once you have copied the key, click "Continue". The wizard will load a new page that requests your certificate details as described below.</p></li>
  <li><p>If you chose "without CSR generation" you will be asked to provide the Certificate Signing Request that you created (or that you have saved from a previously-issued certificate). Please make sure that you provide complete and accurate information in your CSR, as explained in the next paragraphs.</p></li>
  <li><p>Whether you chose "with" or "without" CSR generation, you need to provide complete and accurate information about the domain for which you are requesting a certificate. If you chose "with CSR generation" you will now type this information into the StartCom interface. Please select the appropriate country, the state or province, the city ("place"), and the name of the organization. The name of the organization defaults to the domain name you provided earlier in the process, but you can change it here to be the name of your company, school, etc. Please see the next paragraph for the proper formatting of the DNS domain name.</p></li>
  <li><p>For the domain, provide the DNS hostname of the XMPP server. For example, if your organization is called "example.com" but your XMPP server is hosted at "im.example.com", type "im" in the first box at the StartCom interface, type "example" in the second box, and select "com" from the dropdown list at the end of the "Domain: xmpp:" line. If you need a cetificate for a "fourth-level" domain such as im.foo.example.com", type "im.foo" in the first box, "example" in the second box, and select "com" from the dropdown list. You can also request a wildcard certificate such as *.example.com (type "*" in the first box, type "example" in the second box, and select "com" from the dropdown list). A wildcard domain enables you to use the same certificate for multiple components (e.g., "groupchat.example.com" as well as "im.example.com"), however <strong>please do not use a wildcard certificate for website domains</strong> such as "www.example.com" because this is in violation of StartCom's <a href='https://www.startssl.com/?app=26'>certification policies</a>. <em>(NOTE: if your top-level domain is not available in the dropdown list, please send email to &lt;<a href='mailto:certmaster@xmpp.org'>mailto:certmaster@xmpp.org</a>&gt;.)</em></p></li>
  <li><p>If you chose "with CSR generation" then you will enter the foregoing information in the wizard pages (if you chose "without CSR generation" then you will provide the foregoing information in the CSR that you create). After you click "Continue" in the "with CSR generation" flow, the wizard will load a new page that shows the CSR that StartCom has created for you. Make sure that you save this CSR (you can use it to renew your certificate in the future) just as you saved the private key earlier in the process (i.e., save it to an ASCII file such as "domain.csr").</p></li>
  <li><p>Now you will need to select an authorized email address. This is the address to which a special verification code will be sent. This email address MUST be either hostmaster, postmaster, or webmaster @ yourdomain.tld <em>or</em> one of the email addresses listed in the <a href='whois.shtml'>whois</a> record for your domain (i.e., the registered email address of the administrative contact, tech contact, or billing contact).</p></li>
  <li><p>Check the email account you specified for a message containing the verification code. The email message will come from the address "certmaster at xmpp.org" as auto-generated by startcom.org (which is authorized to send email on behalf of the "certmaster at xmpp.org" address, as you can validate by checking the <a href='http://www.openspf.org/'>Sender Policy Framework</a> (SPF) information for xmpp.org). If you do not receive the email message within a few minutes, it is possible that you are blocking email from xmpp.org or startcom.org, that the message is caught in your spam filters, that your mail server responds too slowly, that you don't have the proper email addresses or aliases set up, or that you have "greylisting" set up for your domain (for greylisting, simply wait for the greylisting period to end, e.g. 300 seconds, then complete another certificate request). The verification code expires in 15 minutes, so don't request a certificate and then go to lunch. :)</p></li>
  <li><p>Copy the verification code you have received via email and enter it into the wizard page, then click "Continue". The wizard will load a new page that shows the certificate that has been generated by StartCom. As with the private key and the CSR, copy the certificate to an ASCII file (e.g., "domain.crt").</p></li>
  <li><p>Congratulations, you have received your free (*) certificate! Now proceed to the <a href='installation.shtml'>Certificate Installation HOWTO</a> and follow the instructions there.</p></li>
</ol>
<!--#include virtual="/includes/caboiler.txt" -->
<!--#include virtual="/includes/foot.txt" -->
Something went wrong with that request. Please try again.