HTML5: Edition for Web Authors

4.10.14 The keygen element

Categories:

Flow content.

Phrasing content.

Interactive content.

Listed, labelable, submittable, and resettable form-associated element.

Palpable content.

Contexts in which this element can be used:

Where phrasing content is expected.

Content model:

Empty.

Content attributes:

Global attributes

autofocus

challenge

disabled

form

keytype

name

DOM interface:

interface HTMLKeygenElement : HTMLElement {
           attribute boolean autofocus;
           attribute DOMString challenge;
           attribute boolean disabled;
  readonly attribute HTMLFormElement? form;
           attribute DOMString keytype;
           attribute DOMString name;

  readonly attribute DOMString type;

  readonly attribute boolean willValidate;
  readonly attribute ValidityState validity;
  readonly attribute DOMString validationMessage;
  boolean checkValidity();
  void setCustomValidity(DOMString error);

  readonly attribute NodeList labels;
};

The keygen element represents a key pair generator control. When the control's form is submitted, the private key is stored in the local keystore, and the public key is packaged and sent to the server.

The challenge attribute may be specified. Its value will be packaged with the submitted key.

The keytype attribute is an enumerated attribute. The following table lists the keywords and states for the attribute — the keywords in the left column map to the states listed in the cell in the second column on the same row as the keyword. User agents are not required to support these values, and must only recognize values whose corresponding algorithms they support.

The invalid value default state is the unknown state. The missing value default state is the RSA state, if it is supported, or the unknown state otherwise.

This specification does not specify what key types user agents are to support — it is possible for a user agent to not support any key types at all.

The form attribute is used to explicitly associate the keygen element with its form owner. The name attribute represents the element's name. The disabled attribute is used to make the control non-interactive and to prevent its value from being submitted. The autofocus attribute controls focus.

keygen . type

Returns the string "keygen".

The challenge IDL attribute must reflect the content attribute of the same name.

The keytype IDL attribute must reflect the content attribute of the same name, limited to only known values.

This specification does not specify how the private key generated is to be used. It is expected that after receiving the SignedPublicKeyAndChallenge (SPKAC) structure, the server will generate a client certificate and offer it back to the user for download; this certificate, once downloaded and stored in the key store along with the private key, can then be used to authenticate to services that use TLS and certificate authentication.

<form action="processkey.cgi" method="post" enctype="multipart/form-data">
 <p><keygen name="key"></p>
 <p><input type=submit value="Submit key..."></p>
</form>