This HTML5 document contains 16 embedded RDF statements represented using HTML+Microdata notation.

The embedded RDF content will be recognized by any processor of HTML5 Microdata.

Subject Item

n2:create

rdf:type

schema:EntryPoint

schema:httpMethod

GET

schema:contentType

text/xml

n4:isWebServiceOf

n7:this_ODSUserModuleAPI

n4:endPointURL

n6:create

schema:shortDescription

<p>Create a new client certificate and accociate it with the authenticated user. </p>

n4:hasParameter

n5:_organization n5:_email n5:_commonName n5:_country n5:_publicKey n5:_expirationDays n5:_expirationHours

schema:name

EntryPoint - user_certificates_create

schema:description

<p>ODS is a full-featured WebID server and supports authentication via WebID in all situations. Clients can easily create new WebID certificates via this method.</p><p>WebID authentication means that the client sends an X.509 certificate with an embedded profile URL denoting the authenticating person. That URL resolves to an RDF profile document containing the public key from the certificate.</p><p>The simplest way to create a new WebID-enabled X.509 certificate is for the client to use the <computeroutput>keygen</computeroutput> HTML tag to create a new RSA key pair. The public key will be sent to this method. ODS will then prepare the certifcate and return it to the client with mimetype <computeroutput>application/x-x509-user-cert</computeroutput>. The browser will install that certifcate in its key ring. It can then be used in suqsequent authentication actions with ODS or any other WebID enabled system.</p><p><bold>Example:</bold> </p><p>The minimal HTML code to create a new client certificate looks like the following: <programlisting><codeline><highlight class="normal"><sp />{.html}</highlight></codeline> <codeline><highlight class="normal"><sp />&lt;form<sp />action=</highlight><highlight class="stringliteral">"/ods/api/user.certificates.create"</highlight><highlight class="normal">&gt;</highlight></codeline> <codeline><highlight class="normal"><sp /><sp /><sp />&lt;keygen<sp />name=</highlight><highlight class="stringliteral">"publicKey"</highlight><highlight class="normal"><sp />/&gt;</highlight></codeline> <codeline><highlight class="normal"><sp /><sp /><sp />&lt;input<sp />name=</highlight><highlight class="stringliteral">"sid"</highlight><highlight class="normal"><sp />type=</highlight><highlight class="stringliteral">"hidden"</highlight><highlight class="normal"><sp />value=</highlight><highlight class="stringliteral">"SID"</highlight><highlight class="normal"><sp />/&gt;</highlight></codeline> <codeline><highlight class="normal"><sp /><sp /><sp />&lt;input<sp />name=</highlight><highlight class="stringliteral">"realm"</highlight><highlight class="normal"><sp />type=</highlight><highlight class="stringliteral">"hidden"</highlight><highlight class="normal"><sp />value=</highlight><highlight class="stringliteral">"wa"</highlight><highlight class="normal"><sp />/&gt;</highlight></codeline> <codeline><highlight class="normal"><sp /><sp /><sp />&lt;input<sp />type=</highlight><highlight class="stringliteral">"submit"</highlight><highlight class="normal"><sp />value=</highlight><highlight class="stringliteral">"Create<sp />Certificate"</highlight><highlight class="normal">/&gt;</highlight></codeline> <codeline><highlight class="normal"><sp />&lt;/form&gt;</highlight></codeline> </programlisting></p><p>Here the <computeroutput>keygen</computeroutput> tag creates the key pair and makes sure that the public key is sent on form submission. The hidden <computeroutput>input</computeroutput> fields are required for <ref kindref="member" refid="ods_authentication_1ods_authentication_session_id">Authentication via Session Id</ref>. The <computeroutput>realm</computeroutput> is fixed to <computeroutput>wa</computeroutput>, but the session id value <computeroutput>sid</computeroutput> needs to be provided by the client from a previous authentication. How this value is filled in depends on the programming language used to build the client.</p><p>Instead of using <ref kindref="member" refid="ods_authentication_1ods_authentication_session_id">Authentication via Session Id</ref> via two hidden <computeroutput>input</computeroutput> fields clients could also use classical user digest credentials as detailed in <ref kindref="member" refid="ods_authentication_1ods_authentication_password_hash">Password Hash Authentication</ref>.</p><p><parameterlist kind="param"><li> <parameternamelist> <parametername>commonName</parametername> </parameternamelist> <parameterdescription> <p>The optional common name used for the certificate. If omitted one will be built from the ODS user profile name and the ODS domain name. </p></parameterdescription> </li> <li> <parameternamelist> <parametername>country</parametername> </parameternamelist> <parameterdescription> <p>The optional country used in the certificate. If omitted the value will be taken from the ODS user profile. </p></parameterdescription> </li> <li> <parameternamelist> <parametername>organization</parametername> </parameternamelist> <parameterdescription> <p>The optional organization used in the certificate. If omitted the value will be taken from the ODS user profile. </p></parameterdescription> </li> <li> <parameternamelist> <parametername>email</parametername> </parameternamelist> <parameterdescription> <p>The optional email address used in the certificate. If omitted the value will be taken from the ODS user profile. Be aware That the created certificate can only be used to digitally sign emails if the email address matches. </p></parameterdescription> </li> <li> <parameternamelist> <parametername>expirationDays</parametername> </parameternamelist> <parameterdescription> <p>The optional number of days this certificate should be valid. This defaults to 365 days, ie. one year. </p></parameterdescription> </li> <li> <parameternamelist> <parametername>expirationHours</parametername> </parameternamelist> <parameterdescription> <p>The optional number of hours thsi certificate should be valid. This value will be added to the value of <computeroutput>expirationDays</computeroutput> and simply provides a means for a finer-grained expiration control. </p></parameterdescription> </li> <li> <parameternamelist> <parametername>publicKey</parametername> </parameternamelist> <parameterdescription> <p>The mandatory public key in SPKI format.</p></parameterdescription> </li> </ul> <simplesect kind="return"><p>The new X.509 certificate with mimetype <computeroutput>application/x-x509-user-cert</computeroutput> or an error code as defined in <ref kindref="member" refid="ods_response_format_1ods_response_format_result_code">ODS Error Result Codes</ref>. On error an appropriate HTTP error code will be set in addition to a return value as described in <ref kindref="member" refid="ods_response_format_1ods_response_format_result_code">ODS Error Result Codes</ref>.</p></simplesect> <simplesect kind="par"><title>Authentication</title><p>This function requries authentication via one of the supported authentication methods as described in <ref kindref="compound" refid="ods_authentication">ODS Authentication</ref>. </p></simplesect> </p>

schema:url

n6:create