====== Modules - Certificates: Basics ======

Certificate authority (crt) module was designed to handle various certificate authority implementations via specific drivers. Currently, there is one driver implemented - the CAW driver that handles the communication with CAW certificate authority (bundled in the module).

===== What do you need before you start =====

  * You need to install **CzechIdM 7.7.0**  (and higher).
  * You need to be logged in as **admin**.
  * You need to enable **Certificate**  module.
  * You need to install the **[[.:how_to_install_caw|CAW]]** .

===== How to create an authority on Linux =====

By clicking on the left menu on **Certificates**  and then on **Authorities**  is shown a table with certificate authorities. Click on **Add**  button and a popup window is shown. {{  .:ca_01.png  }}Here you fill:

  * **Code**  - Label of certification authority
  * **Driver**  - We are using caw-driver. (There is only caw driver implemented for now.)
  * **Path to the CAW distribution**  and **Path to the certificate for that authority**  - There is needed a path to CAW distribution and certificate for our new authority.
  * **OU**  - Fill organization unit, it is part of the certificate, it could be a specification of location or department.
  * **Enable approving by workflow process**  - It is an option if generating of certificates has to be approved or not.
  * **Approver roles**  - Specified roles for approving generation of certificates. Users with these roles get tasks to be approved or not.
Then you click on **Save and continue**  button and continue this tutorial with generating **certificate in GUI**  or with **CSR file**.

{{  :undefined:001.png  }}{{  :undefined:002.png  }}

===== How to create an authority on Windows =====

<note important>On Windows, using diacritics in certificate/CSR DNs is currently not supported due to bug [[https://github.com/openssl/openssl/issues/8317|#8317]] in OpenSSL. This affects CRT module with CAW Windows driver. IdM handles this by stripping diacritics from certain strings before passing them to the CAW. On Linux, diacritics works fine.</note> The process of creating an authority on Windows is similar to the one on Linux but you need to have [[https://gitforwindows.org/|Git Bash]] installed. When creating the authority on Windows, we select the win-caw-driver. Then we just need to fill out one extra field:

  * **Path to Git Bash**  - This path leads to the bash.exe file in git\bin.
An example of how we can configure the authority can be seen bellow: {{  .:crt_win_01.png  }}{{  .:crt_win_02.png  }}{{  .:crt_win_03.png  }}

Other than the extra field Path to Git Bash, the process is the same as on Linux.

===== Generate certificate in GUI =====

In the left menu click on **Profile**  and then on **Certificates**. There are 2 tables, in **Certificates**  table are all certificates owned by the user and in the other table, there are requests of these certificates. Click on **Request certificate**.

{{  .:ca_03.png  }}

Fill information in a popup window:

  * **Certificate authority**  - There can be more certificate authorities, so choose authority, which will issue the certificate.
  * **Certificate type**  - For which purpose certificate will be issued. **Signing**  - for example signing some documents, **Authentication**  - to grant access to a resource, network, application, etc. not based on a password, but rather on the certificate.
  * **Generate certificate by**  - It is a specification for whom certificate will be issued. Based on this information will be certificate generated.
  * **Password**  - Downloaded private key will be encrypted with this password. Because this is just tutorial we put a weak password, you should use more powerful one.
And click on **Submit a request**  button.

{{  .:ca_04.png  }}

Now we have the valid certificate and we could download the certificate. **Certificate**  button downloads public key and **Key**  button downloads encrypted public and private key.

{{  .:ca_06.png  }}

For admin, there is another one important section in left menu **Certificates**  and again in **Certificates**. This table shows all certificates. For version < 3.0.3 the key could be downloaded only by the owner of certificate, but from version 3.0.3, there is special permission for downloading key.

<note tip>If the owner doesn't has this new permission, he won't be able to download it.</note>

You need to set permission:

  * CrtCertificate - DOWNLOADKEY
  * CrtAuthority - DOWNLOADKEY

You can use BaseEvaluator so the user can download all keys. Or if you use for example UUID evaluator for CrtAuthority, then user will be able to donwload keys only for certificates from this specific authortiy.

{{  .:ca_07.png  }}

===== Generate certificate by CSR =====

In the left menu click on **Profile**  and then on **Certificates**. There are 2 tables, in **Certificates**  table are all certificates owned by the user and in the other table, there are requests of certificates. Click on **Request certificate**.

{{  .:ca_03.png  }}

Fill information in a popup window:

  * **Certificate authority**  - There can be more certificate authorities, so choose authority, which will issue the certificate.
  * **Certificate type**  - For which purpose certificate will be issued. **Signing**  - for example signing some documents, **Authentication**  - to grant access to a resource, network, application, etc. not based on a password, but rather on the certificate.
  * **Generate certificate by**  - Fill option **Selected CSR file**  and drag CSR file to the marked field right below.
And then click on **Submit a request**  button.

{{  .:ca_09.png  }}

Now we have two certificates and as you can see in the picture below, the private part of certificate generated with CSR file cannot be downloaded. It is because CzechIdM does not have a private part. Users have it with CSR file, so if you lose it you will probably have to generate a new certificate.

{{  .:ca_10.png  }}

==== Upload certificate ====

Certificate generated by third-party authority can be uploaded to CzechIdM (or synchronized from target system). In the left menu **Profile**  and then in **Certificates**  menu, you can upload certificate by clicking on an **Upload certificate**  button.

{{  .:crt_upload.png  }}

And then just drag certificate file to marked box in a popup window.

If we want to allow a user to upload a certificate, we set authorization policies as follows:

  * Permission to read, create and download one's own identity certificates: Certificates (CrtCertificate) | Read, Create | SelfCertificateEvaluator

===== Renew and revoke certificate =====

**For users:**

It is on the same page as generating a certificate. By clicking on **Profile**  in the left menu and then on **Certificates**. And as you can see in the picture below, in column **Action**  there are two buttons. Green one is for **renew**  a certificate, it prolongs the validity of a certificate. The red one revokes a certificate (e.g. certificate was compromised), the certificate will stay in certificates section, but it will not be valid.

{{  .:ca_08.png  }}

**For admin:**

There is agenda in left menu **Certificates**  → **Certificates**  (picture below), where are all certificates and admin can revoke or renew certificates even of other user's.

{{  .:ca_11.png  }}

<note tip>When a certificate expires, it no longer can be renewed. But in **Settings**  and in **Task scheduler**  process can be created, which sends a notification with a warning, when certificates will expire in few days. Or you can find help in [[.:modules_crt_lrt_notification|warning notification]] tutorial.</note>

<note tip>To allow using this agenda, users have to have this permissions:

  * CrtRequest - Read, Create, Update
  * CrtCertificate - Read, Create
  * CrtAuthority - autocomplete

You can create new role, [[.:add_permissions|add this permissions to the role]] and assign this role to users.</note>

Congratulations, if you are reading this, you successfully completed this tutorial.

===== Permissions =====

For CRT exists two special permissions for validating and requesting certificate by CSR request:

  * Validate CRS request,
  * Upload CSR request.

These permission must be set to user before they want upload or validate CSR request. Basic requesting via frontend form works with permission create/update.

===== Configuration =====

Configuration option that allow create password as another user. For example: admin requesting new certificate for user.
<code>

# If value is true admin can set new password, this password will be sent to user in notification.
# If set to false admin will not able set password to request. The password for certificate will be generated by password policy.
idm.pub.crt.configuration.passCreate.enabled=true
#
# Default status for all identity certificates that will be revocated after identity will be disabled.
idm.sec.crt.configuration.identityDisabledRevocationReason=UNSPECIFIED
#
# Default status for all identity certificates that will be revocated after identity will be deleted.
idm.sec.crt.configuration.identityDeletedRevocationReason=UNSPECIFIED

</code>

There is a processor which start provisioning for user when a new certificate is created for them. This processor is disabled by default and can be enabled, find the "certificate-provisioning-processor".

==== Revocation status list ====

  * UNSPECIFIED
  * KEY\_COMPROMISE
  * CA\_COMPROMISE
  * AFFILIATION\_CHANGED
  * SUPERSEDED
  * CESSATION\_OF\_OPERATION
  * CERTIFICATE\_HOLD