First we describe the concept of additional attributes and then we describe the two general types of requests - external prepared PKCS#10 requests and during the interaction generated requests.
Usually the first question is about what does an additional attribute be? Additional attributes where introduced to store extra informations in a request without publishing these informations. Big organizations or trustcenters need a lot of information and only a minimal subset should be public. If you are a postmaster or a webmaster of a university then it is a good idea to put the general emailaddresses into the certificates but it is not really optimal to store the telephonenumber in the certificate. Nevertheless it makes sense for the trustcenter stuff to have the phonenumber in a case of emergency.
After you know what a nice feature these attributes are you want to customize them? No problem. A simple example should help:
Example 4.15. Additional attributes configuration
ADDITIONAL_REQUEST_ATTRIBUTES "requestercn" "email" "department" "telephone" ADDITIONAL_ATTRIBUTES_DISPLAY_VALUE "Name (first and Last name)" "Email" "Department" "Telephone" ADDITIONAL_REQUEST_ATTRIBUTES_STRING_TYPE "LATIN1_LETTERS" "EMAIL" "LATIN1_LETTERS" "LATIN1_LETTERS"
The three options have the following meanings:
Table 4.1. Additional attributes configuration
Parameter | Description |
---|---|
ADDITIONAL_REQUEST_ATTRIBUTES | These are the internal names for the attributes. |
ADDITIONAL_ATTRIBUTES_DISPLAY_VALUE | Here you have to define the displayed names for the attributes. This is useful for example if you have two public interfaces for example an english and a german one. |
ADDITIONAL_REQUEST_ATTRIBUTES_STRING_TYPE |
This helps the software with the errordetection. You can
use the following values:
|
The first certificates which were needed in the open source are were server certificates. The most systems which use such certificates are Apaches, OpenLDAPs, IMAPDs, POPDs, SMTPDs and S-Tunnel. Such systems generate the private key by itself - means the administrator generate a key by hand or via the software but there is no interaction with the trustcenter's software until the administrator created a request with the key or exported a request from the software.
If the administrator has the PKCS#10 request then he must bring the request to the trustcenter and this is the job of command which's configuration we describe here. The option DN_TYPE_PKCS10_REQUIRED_ELEMENTS define the structure of the subject of the PKCS#10 request. The option DN_TYPE_PKCS10_BASE and the values of DN_TYPE_PKCS10_BASE_* define the suffix for the certificates which will be accepted by this interface. The restrictions were implemented to get some kind of useful subjects.
Example 4.16. PKCS#10 configuration
DN_TYPE_PKCS10_REQUIRED_ELEMENTS "CN" "OU" "O" "C" DN_TYPE_PKCS10_BASE "O" "C" DN_TYPE_PKCS10_BASE_1 "OpenCA" DN_TYPE_PKCS10_BASE_2 "it"
If you have no prepared PKCS#10 request then there is a second method in OpenCA. This method is used if the key and request generation happen during the interaction with the client. OpenCA support clientside keygeneration for Microsoft Internet Explorer, Netscape Communicator, Mozilla and Opera. If you have another browser then OpenCA uses it's serverside key and requestgeneration. So let's start with an example:
Example 4.17. Basic CSR configuration
Basic_CSR_Keysizes "512" "768" "1024" "2048" "4096" DN_TYPES "BASIC" DN_TYPE_BASIC_KEYGEN_MODE "SERVER" DN_TYPE_BASIC_KEYGEN_SHEET "@lib_prefix@/servers/@pub_prefix@/sheets/basic_csr_confirm_request.html" DN_TYPE_BASIC_BODY "Y" DN_TYPE_BASIC_BASE "O" "C" DN_TYPE_BASIC_ELEMENTS "emailAddress" "CN" "OU" DN_TYPE_BASIC_NAME "Basic User Request" DN_TYPE_BASIC_BASE_1 "@ca_organization@" DN_TYPE_BASIC_BASE_2 "@ca_country@" DN_TYPE_BASIC_ELEMENT_1 "E-Mail" DN_TYPE_BASIC_ELEMENT_1_MINIMUM_LENGTH 7 DN_TYPE_BASIC_ELEMENT_1_REQUIRED "YES" DN_TYPE_BASIC_ELEMENT_2 "Name" DN_TYPE_BASIC_ELEMENT_2_MINIMUM_LENGTH 3 DN_TYPE_BASIC_ELEMENT_2_REQUIRED "YES" DN_TYPE_BASIC_ELEMENT_3 "Certificate Request Group" DN_TYPE_BASIC_ELEMENT_3_SELECT "Internet" "Partners" "Employees" "Trustcenter" DN_TYPE_BASIC_ELEMENT_3_MINIMUM_LENGTH 8 DN_TYPE_BASIC_ELEMENT_3_REQUIRED "YES"
The first line defines the available keysize. The next variable DN_TYPES defines the available configurations of basic_csr. The command basic_csr is called via a link and the link must contain an option CSR_TYPE which defines the configuration which is used for this CSR. If you don't set this option then basic_csr starts it's browserdetection.
The default type which is supported by OpenCA is BASIC. You can simply add a type and set a correct link in the public gateway. You can find an example on the public gateway by looking at the link “Basic Request”.
The prefix of every definition is now DN_TYPE_BASIC_. The NAME defines the displayed name (e.g. "Request for managers only"). The BODY defines the type of the request. If the value is Y or YES then a key and a request will be stored and if necessary generated. If the value is N or samp then only a header will be generated. This option is used to get the necessary data from a user to initialize a smartcard on the registration authority.
DN_TYPE_BASIC_KEYGEN_MODE specifies the way how to generate a key and request. The supported modes are SERVER, SPKAC and IE. SPKAC is used with Opera, Mozilla and Netscape, IE is used for Microsoft Internet Explorer and SERVER is used for all other situations.
The BASE is the part of the subject which is not editable by the user who requests a certificate. The other BASE_numbers define the values of the elements which are used for the not editable part of the subject.
The ELEMENTS are the part of subject which can be defined by the user. The defined attributes of the subject can be configured more precisely by the options named *_ELEMENT_number*. They have the following meaning:
Table 4.2. Generic basic CSR configuration
Parameter | Description |
---|---|
*_ELEMENT_number | These are the displayed names of the elements. The normal user don't know what is a CN or a commonName. The most users will be confused if they see two fields with the same name (e.g. OU). So you can give the attributes some names which match their semantic. |
*_ELEMENT_number_MINIMUM_LENGTH | This field defines what the minimum length of the value is. If you don't know it then simply use 0. |
*_ELEMENT_number_REQUIRED | Usually the user has to fill all fields but sometimes it is a good idea to have some optional fields. If you have such an optional field then please set the value to something different than “YES”. If a value is entered by the user then the option *_ELEMENT_number_MINIMUM_LENGTH still will be checked. |
*_ELEMENT_number_SELECT | All fields are textfields by default. You can specify *_ELEMENT_number_SELECT followed by a list of values. OpenCA creates a HTML-select from this definition. |
*_ELEMENT_number_XML_FILE | If you need some more options or you have an export from an ERP database then there is an additional method to create HTML-select fields. You can create a XML file which must contain a list. The filename you must specify here. |
*_ELEMENT_number_XML_PATH | If you specified an XML file then you have to specify the XPath to this list too. The XPath for the following example is “basic_csr/basic/element_3/option”: |