Revision 993997 of <keygen>

<p>{{deprecated_header}}</p>

<p>The HTML <code>&lt;keygen&gt;</code> element exists to facilitate generation of key material, and submission of the public key as part of an <a href="/en-US/docs/Web/Guide/HTML/Forms">HTML form</a>. This mechanism is designed for use with Web-based certificate management systems. It is expected that the <code>&lt;keygen&gt;</code> element will be used in an HTML form along with other information needed to construct a certificate request, and that the result of the process will be a signed certificate.</p>

<div class="note">
<p>There is currently discussion among Web browser makers whether to keep this feature or not. Until a decision is reached, it is better to continue to consider this feature as deprecated and going a way.</p>
</div>

<table class="properties">
 <tbody>
  <tr>
   <th scope="row"><a href="/en-US/docs/HTML/Content_categories" title="HTML/Content_categories">Content categories</a></th>
   <td><a href="/en-US/docs/HTML/Content_categories#Flow_content" title="HTML/Content categories#Flow content">Flow content</a>, <a href="/en-US/docs/HTML/Content_categories#Phrasing_content" title="HTML/Content categories#Phrasing content">phrasing content</a>, interactive content, <a href="/en-US/docs/HTML/Content_categories#Form_listed" title="HTML/Content categories#Form listed">listed</a>, <a href="/en-US/docs/HTML/Content_categories#Form_labelable" title="HTML/Content categories#Form labelable">labelable</a>, <a href="/en-US/docs/HTML/Content_categories#Form_submittable" title="HTML/Content categories#Form submittable">submittable</a>, <a href="/en-US/docs/HTML/Content_categories#Form_resettable" title="HTML/Content categories#Form resettable">resettable</a>&nbsp; <a href="/en-US/docs/HTML/Content_categories#Form-associated_content" title="HTML/Content categories#Form-associated content">form-associated element</a>, palpable content.</td>
  </tr>
  <tr>
   <th scope="row">Permitted content</th>
   <td>None, it is an {{Glossary("empty element")}}.</td>
  </tr>
  <tr>
   <th scope="row">Tag omission</th>
   <td>Must have a start tag and must not have an end tag.</td>
  </tr>
  <tr>
   <th scope="row">Permitted parent elements</th>
   <td>Any element that accepts <a href="/en-US/docs/HTML/Content_categories#Phrasing_content" title="HTML/Content_categories#Phrasing_content">phrasing content</a>.</td>
  </tr>
  <tr>
   <th scope="row">DOM interface</th>
   <td>{{domxref("HTMLKeygenElement")}}</td>
  </tr>
 </tbody>
</table>

<h2 id="Attributes">Attributes</h2>

<p><span style="line-height:21px">This element includes the&nbsp;</span><a href="https://developer.mozilla.org/en-US/docs/HTML/Global_attributes" style="line-height: 21px;" title="HTML/Global attributes">global attributes</a><span style="line-height:21px">.</span></p>

<dl>
 <dt>{{htmlattrdef("autofocus")}}</dt>
 <dd>This Boolean attribute lets you specify that the control should have input focus when the page loads, unless the user overrides it, for example by typing in a different control. Only one form element in a document can have the <code>autofocus</code> attribute, which is a Boolean.</dd>
 <dt>{{htmlattrdef("challenge")}}</dt>
 <dd>A challenge string that is submitted along with the public key. Defaults to an empty string if not specified.</dd>
 <dt>{{htmlattrdef("disabled")}}</dt>
 <dd>This Boolean attribute indicates that the form control is not available for interaction.</dd>
 <dt>{{htmlattrdef("form")}}</dt>
 <dd>The form element that this element is associated with (its <em>form owner</em>). The value of the attribute must be an <code>id</code> of a {{HTMLElement("form")}} element in the same document. If this attribute is not specified, this element must be a descendant of a {{HTMLElement("form")}} element. This attribute enables you to place <code>&lt;keygen&gt; </code>elements anywhere within a document, not just as descendants of their form elements.</dd>
 <dt>{{htmlattrdef("keytype")}}</dt>
 <dd>The type of key generated. The default value is <code>RSA</code>.</dd>
 <dt>{{htmlattrdef("name")}}</dt>
 <dd>The name of the control, which is submitted with the form data.</dd>
</dl>

<p>The element is written as follows:</p>

<pre class="brush: html">
&lt;keygen name="<var>name</var>" challenge="<var>challenge string</var>" keytype="<var>type</var>" keyparams="<var>pqg-params</var>"&gt;</pre>

<p>The <code>keytype</code> parameter is used to specify what type of key is to be generated. Valid values are "<code>RSA</code>", which is the default, "<code>DSA</code>" and "<code>EC</code>". The <code>name</code> and <code>challenge</code> attributes are required in all cases. The <code>keytype</code> attribute is optional for RSA key generation and required for DSA and EC key generation. The <code>keyparams</code> attribute is required for DSA and EC key generation and ignored for RSA key generation. <code>PQG</code> is a synonym for <code>keyparams</code>. That is, you may specify <code>keyparams="pqg-params"</code> or <code>pqg="pqg-params"</code>.</p>

<p>For RSA keys, the <code>keyparams</code> parameter is not used (ignored if present). The user may be given a choice of RSA key strengths. Currently, the user is given a choice between "high" strength (2048 bits) and "medium" strength (1024 bits).</p>

<p>For DSA keys, the <code>keyparams</code> parameter specifies the DSA PQG parameters which are to be used in the keygen process. The value of the <code>pqg</code> parameter is the the BASE64 encoded, DER encoded Dss-Parms as specified in IETF <a class="link-ftp" href="ftp://ftp.rfc-editor.org/in-notes/rfc3279.txt">RFC 3279</a>. The user may be given a choice of DSA key sizes, allowing the user to choose one of the sizes defined in the DSA standard.</p>

<p>For EC keys, the <code>keyparams</code> parameter specifies the name of the elliptic curve on which the key will be generated. It is normally a string from the table in <a class="external" href="https://mxr.mozilla.org/mozilla-central/source/security/manager/ssl/src/nsKeygenHandler.cpp?mark=179-185,187-206,208-227,229-256#177" title="https://mxr.mozilla.org/mozilla-central/source/security/manager/ssl/src/nsKeygenHandler.cpp?mark=179-185,187-206,208-227,229-256#177">nsKeygenHandler.cpp</a>. (Note that only a subset of the curves named there may actually be supported in any particular browser.) If the <code>keyparams</code> parameter string is not a recognized curve name string, then a curve is chosen according to the user's chosen key strength (low, medium, high), using the curve named "<code>secp384r1</code>" for high, and the curve named "<code>secp256r1</code>" for medium keys. (Note: choice of the number of key strengths, default values for each strength, and the UI by which the user is offered a choice, are outside of the scope of this specification.)</p>

<p>The <code>&lt;keygen&gt;</code> element is only valid within an HTML form. It will cause some sort of selection to be presented to the user for selecting key size. The UI for the selection may be a menu, radio buttons, or possibly something else. The browser presents several possible key strengths. Currently, two strengths are offered, high and medium. If the user's browser is configured to support cryptographic hardware (e.g. "smart cards") the user may also be given a choice of where to generate the key, i.e., in a smart card or in software and stored on disk.</p>

<p>When the submit button is pressed, a key pair of the selected size is generated. The private key is encrypted and stored in the local key database.</p>

<pre>
   PublicKeyAndChallenge ::= SEQUENCE {
       spki SubjectPublicKeyInfo,
       challenge IA5STRING
   }
   SignedPublicKeyAndChallenge ::= SEQUENCE {
       publicKeyAndChallenge PublicKeyAndChallenge,
       signatureAlgorithm AlgorithmIdentifier,
       signature BIT STRING
   }</pre>

<p>The public key and challenge string are DER encoded as <code>PublicKeyAndChallenge</code>, and then digitally signed with the private key to produce a <code>SignedPublicKeyAndChallenge</code>. The <code>SignedPublicKeyAndChallenge</code> is {{Glossary("Base64")}} encoded, and the ASCII data is finally submitted to the server as the value of a form name/value pair, where the name is <var>name</var> as specified by the <code>name</code> attribute of the <code>keygen</code> element. If no challenge string is provided, then it will be encoded as an <code>IA5STRING</code> of length zero.</p>

<p>Here is an example form submission as it would be delivered to a CGI program by the HTTP server:</p>

<pre>
   commonname=John+Doe&amp;[email protected]&amp;org=Foobar+Computing+Corp.&amp;
   orgunit=Bureau+of+Bureaucracy&amp;locality=Anytown&amp;state=California&amp;country=US&amp;
   key=MIHFMHEwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAnX0TILJrOMUue%2BPtwBRE6XfV%0AWtKQbsshxk5ZhcUwcwyvcnIq9b82QhJdoACdD34rqfCAIND46fXKQUnb0mvKzQID%0AAQABFhFNb3ppbGxhSXNNeUZyaWVuZDANBgkqhkiG9w0BAQQFAANBAAKv2Eex2n%2FS%0Ar%2F7iJNroWlSzSMtTiQTEB%2BADWHGj9u1xrUrOilq%2Fo2cuQxIfZcNZkYAkWP4DubqW%0Ai0%2F%2FrgBvmco%3D</pre>

<h2 id="Examples">Examples</h2>

<ul>
 <li><a class="link-https" href="https://bugzilla.mozilla.org/attachment.cgi?id=380749" title="https://bugzilla.mozilla.org/attachment.cgi?id=380749">Sample form with RSA KEYGEN element</a></li>
 <li><a class="link-https" href="https://bugzilla.mozilla.org/attachment.cgi?id=380750" title="https://bugzilla.mozilla.org/attachment.cgi?id=380750">Sample form with DSA KEYGEN element and PQG Parameters</a></li>
 <li><a class="link-https" href="https://bugzilla.mozilla.org/attachment.cgi?id=380751" title="https://bugzilla.mozilla.org/attachment.cgi?id=380751">Sample form with DSA KEYGEN element but no PQG Parameters</a></li>
 <li><a class="link-https" href="https://bugzilla.mozilla.org/attachment.cgi?id=380752" title="https://bugzilla.mozilla.org/attachment.cgi?id=380752">Sample form with EC KEYGEN element</a></li>
</ul>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName('HTML WHATWG', 'the-button-element.html#the-keygen-element', '&lt;keygen&gt;')}}</td>
   <td>{{Spec2('HTML WHATWG')}}</td>
   <td>&nbsp;</td>
  </tr>
  <tr>
   <td>{{SpecName('HTML5 W3C', 'forms.html#the-keygen-element', '&lt;keygen&gt;')}}</td>
   <td>{{Spec2('HTML5 W3C')}}</td>
   <td>&nbsp;</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{CompatibilityTable}}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>1.0</td>
   <td>{{CompatGeckoDesktop("1.0")}}</td>
   <td>{{CompatNo}}</td>
   <td>3.0</td>
   <td>1.2</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>2.3</td>
   <td>{{CompatGeckoMobile("1.0")}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatNo}}</td>
  </tr>
 </tbody>
</table>
</div>

<p>&nbsp;</p>

<p>{{HTMLRef}}</p>