Certificate profiles
====================

A certificate profile is the blueprint that determines all technical
aspects of the certificate such as subject pattern, key usages and
other extensions.

Naming
------

The internal name of the profile is the name of the node in the
configuration layer. If you keep the sample structure each profile is in
a single file in the profile directory, so the name of the profile is
the name of the file.

You can add `label` and `description` to the profile, which is used for
display purpose on the WebUI frontend only, it has no effect on the
actual certificate.


Validity
--------

The validity is usually defined by a relative time specification of the
format +YYMMDDhhmmss, (e.g. +0006 for six month, see OpenXPKI::DateTime)::

    validity:
        notafter: +0006

The actual value is determined at the moment the PKI really signs the
request. You can also add a notbefore date, in this case the notafter
date is calculated relative to notbefore::

    validity:
        notbefore: +000001
        notafter: +0006

Above example will create a certificate with a notbefore 24 hours ahead
of the time of issuance and ends 6 months + 1 day later.

It is also possible to give an absolute date as YYYYMMDDhhmmss.

Styles
------

t.b.d

Subject and Process Information
-------------------------------

OpenXPKI can collect meta information based on the selected profile and
has a templating engine to build subject and subject alternative name
sections (SAN) from the input data in many different ways.

The input fields are summarized in three groups: subject, san and info::

    00_basic_style:
        label: I18N_OPENXPKI_UI_PROFILE_BASIC_STYLE_LABEL
        description: I18N_OPENXPKI_UI_PROFILE_BASIC_STYLE_DESC
        ui:
            subject:
                - hostname
                - hostname2
                - port
            info:
                - requestor_gname
                - requestor_name
                - requestor_email
                - requestor_affiliation
                - comment

Each section can hold any number of fields, each field is defined by a
set of options::

    id: hostname
    label: I18N_OPENXPKI_UI_PROFILE_HOSTNAME
    placeholder: fully.qualified.example.com
    tooltip: I18N_OPENXPKI_UI_PROFILE_HOSTNAME_TOOLTIP
    description: I18N_OPENXPKI_UI_PROFILE_HOSTNAME_DESC
    type: freetext
    preset: "[% CN.0.replace(':.*','') %]"
    match: \A [A-Za-z\d\-\.]+ \z
    width: 60

The definition can be placed in the node `template` inside the profile
file or globally in the template directory.

To not break legacy configurations, the placeholder can be set using
"default" as keyword. The tooltip is set to description if missing.


Field Definition
^^^^^^^^^^^^^^^^

id
  the key used when this item is written into the workflow

label
  the label shown next to the input field

description
  description, shown as tooltip

type
  the type of the field, freetext or select

option
  list of options for the select field (used value is equal to the label)

preset
  in case a CSR is uploaded by the user, you can use parts of it to prefill
  the fields. Items from the subject can be referenced by the name of the
  component, items from the subject alternative name section are prefixed
  with the string `SAN_`, e.g. `SAN_DNS`. Note that all keys are uppercased
  and all items are arrays regardless of the number of items found!

  There are several options for preprocessing the items.

  First item of type CN::

     preset: CN.0

  All items of type OU (creates on field per item)::

     preset: OU.X

  Use templating to extract left side of CN up to the first colon::

    preset: "[% CN.0.replace(':.*','') %]"

  Use templating to create a list of items, the pipe symbol is used as seperator::

    preset: "[% FOREACH ou = OU %][% ou %]|[% END %]"

match
  a regex pattern that is applied to the user input for validation

width
  size of the field - not implemented yet, definition might change.

placeholder
  A text which is shown as placeholder in the input field (this value is
  NOT a default value for the field)

renew
  How to handle this field during a certificate renewal request. Can be one of::

     keep: the field is set to the existing value and can not be changed

     preset: the field is set to the existing value but can be changed

     clear: the current value is unset

Subject Rendering
^^^^^^^^^^^^^^^^^

The full distinguished name and the Subject Alternative Name items are
created using template toolkit rules from the information that have been
collected from the input fields in the "subject" step::

    subject:
        dn: CN=[% hostname.lower %][% IF port AND port != 443 %]:[% port %][% END %],DC=Test Deployment,DC=OpenXPKI,DC=org
        san:
            DNS:
             - "[% hostname.lower %]"
             - "[% FOREACH entry = hostname2 %][% entry.lower %] | [% END %]"

The name of the variable it the one given as "id" in the field definition,
all non empty values are available for DN and SAN rendering.

If you have provided an extra SAN section in the input fields definition,
those are merged into the SAN part WITHOUT any parsing "as is".


Extensions
----------

t.b.d.


Key Parameters
^^^^^^^^^^^^^^

OpenXPKI supports serverside key generation as well as PKCS10 upload.
For both cases you can control what algorithms and parameters are allowed,
even on a per profile basis. The default configuration has the key
definition in the default.yaml file.

Basic definition of allowed key and encryption algorithms::

    key:
        # Supported key algorithms (details need to be defined below!)
        alg:
          - rsa
          - ec
          - dsa

        # Supported encryption algorithms (as taken by openssl)
        enc:
          - aes256
          - _3des
          - idea

        # one of escrow, server, client, both
        # escrow is not implemented in workflows, yet!
        generate: both

For RSA and DSA, you need to define the allowed key sizes in bits:

    rsa:
        key_length:
          - 2048
          - 4096
          - _1024

Those values are used for the key generation dialog as well as for the
validation of uploaded PKCS10 files. Values with an underscore are hidden
from the UI.

For ECC, you need to specify the curve names::

    ec:
        curve_name:
          - prime256v1
          - secp384r1
          - secp521r1

The possbile "named" curves are limited by the ones supported by
Crypt::PKCS10 at the moment. For NIST P-192/256 you can use either the
secpXXXr1 or primeXXXv1 alias.
