keygen element

If you don't know what an element is or how you must use it, I recommend you read the "HTML tags and attributes" tutorial that you can find in the HTML tutorials section.

Description

The keygen element represents a field for generating cryptographic keys. This element is new in HTML5 and has been designed to aid in the generation of keys used in the construction of signed certificates. The functionality of this element is beneficial in web-based certificate management systems.

Basically, with this element authors can provide the mechanisms to generate a key pair (public and private keys) and submit the public key with the form, while the private key is stored in the user's computer. This will most probably lead to a certificate generation (server-side) that the user will be able to download and use to identify himself whenever needed.

This element can be rendered in many ways. Nevertheless, browsers will usually provide controls to configure the key generation, like for example, its length.

When submitted with GET method, this control may take the length of the URL to unsupported values. To stay on the safe side, use the POST method intead.

This element is in the process of being removed from the standard. Using the keygen element at this time is highly discouraged.

Examples

In this example, we'll set a basic form with a keygen control using its default configuration. When the form is submitted, the server-side script will receive the public key only. The private key will be saved in the user's computer.

<form action="../../form-result.php" method="post" target="_blank">
  <p>
    Generate public/private key pair:
    <keygen name="publickey">
    <input type="submit" value="Generate">
  </p>
</form>

Generate public/private key pair:

Attributes

Specific attributes

autofocus

A boolean value instructing the browser to set the focus to this control when the document has finished loading or when the dialog where the control finds itself is shown. If the attribute has the value "autofocus" or the empty string (""), or if it's just present, the control should get the focus as soon as possible, after the page or dialog has been loaded.

Example

<keygen name="pubkey" autofocus>

challenge

A string representing a secret password to be shared between the user and the server. Although this string won't be used in the generation of the certificate, it will be packed and sent to the server upon form submission.

The interpretation of challenge passwords is intended to be specified by certificate issuers. No particular interpretation is required.

Example

<form action="../../form-result.php" method="post" target="_blank">
  <p>
    Generate key pair:
    <keygen name="pubkey" challenge="123456">
    <input type="submit" value="Generate">
  </p>
</form>

Generate key pair:

disabled

A boolean value indicating wether the control is disabled or not. If the attribute takes the value "disabled" or the empty string (""), or if it's just present, the control will be disabled.

Disabled controls are rendered greyed out (if visible), are blocked from user interaction and, more importantly, their values (if any) aren't sent when the form is submitted.

Example

<form action="../../form-result.php" method="post" target="_blank">
  <p>
    Generate keys:
    <keygen name="pubkey" disabled>
    <input type="submit" value="Generate">
  </p>
</form>

Generate keys:

form

The value of the id attribute of the form with which this control is associated to.

This attribute is new in HTML5 and helps defining the pertenence of controls in nested or distant forms.

Example

<p>Keys generation:</p>
<p><keygen name="pubkey" form="form1"></p>
<form id="form1" action="../../form-result.php" method="post" target="_blank">
  <p><input type="submit" value="Generate keys"></p>
</form>

Keys generation:

keytype

The encription algorithm to be used in the generation of keys. Currently, the only possible value (and the default) is rsa, which instructs browsers to use the algorithm developed by RSA Data Security.

Browsers aren't required to support an encryption method at all. Therefore, some browsers have chosen not to support key encription. Authos shouldn't rely on the features of this element until support grows.

Example

<keygen name="pubkey" keytype="rsa">

name

A name for the control. This name will be sent by the user agent to the processing agent, paired with the generated public key. Both values together will conform a name-value pair that will be used to process the form data.

Currently, the value isindex, formerly used in a special way by some browsers and included in the HTML standard, isn't permitted in this attribute.

Example

<form action="../../form-result.php" method="post" target="_blank">
  <p>
    Generate keys:
    <keygen name="public-key">
    <input type="submit" value="Generate">
  </p>
</form>

Generate keys:

Global attributes

For information about global attributes refer to this list of global attributes in HTML5.

Events

Global events

For information about global events refer to this list of global events in HTML5.