# certificate

## Description

| Venue                                                                                                                                                                                                        | Equivalent Concept(s)                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| ![aws](https://4172935707-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAzdR4AyersVibQD8Ei%2Fsync%2Fce53bc0d694cecef3590cb4e3ff022fd38782ef9.png?generation=1594320524493716\&alt=media)   | [AWS Certificate Manager](https://docs.aws.amazon.com/acm/latest/userguide/acm-overview.html)                 |
| ![azure](https://4172935707-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAzdR4AyersVibQD8Ei%2Fsync%2F3b6edd60f83599ce9d773512f4d599257c4eeb1d.png?generation=1594320524253263\&alt=media) | [Key Vault Certificates](https://docs.microsoft.com/en-us/azure/key-vault/certificates/certificate-scenarios) |

A certificate is used to enable secure web services with the https protocol.

## Venue-Specific Properties

These fields are subject to change in the future. They allow for venue- specific behavior.

### AWS

ACM stores certificates by their subject name, therefore you should set the name property of the certificate to the "common name" (CN) of the certificate subject.

If you already have a certificate in ACM and you know the ARN for it, you can specify the ARN instead of a name. This technique can be used to solve more complex situations. The ARN can be found in the AWS Management Console, under ACM or Certificate Manager, in the Certificate Details panel. You must use the ARN if you have any of these circumstances:

* You have multiple certificates with the same common name.
* The certificate is in another account.

To specify an ARN, use the following syntax:

```yaml
venue:
  aws:
    arn: arn:aws:acm:...
```

### Azure

Without any additional options, Tuono will choose a reliable Key Vault name for you based on your subscription and resource group. You may choose to provide your own Key Vault name, however note that Key Vault names are globally unique, so if someone else is already using that name, your blueprint will not deploy:

```yaml
venue:
  azure:
    key_vault_name: MyKeyVault
```

## Features

### Algorithm

| Feature | AWS | Azure |
| ------- | --- | ----- |
| EC      |     | ✔️    |
| RSA     | ✔️  | ✔️    |

### Certificate Operation

| Feature | AWS | Azure |
| ------- | --- | ----- |
| Create  |     |       |
| Delete  | ✔️  | ✔️    |
| Import  | ✔️  | ✔️    |

### RSA Key Length

| Feature | AWS | Azure |
| ------- | --- | ----- |
| 1024    |     |       |
| 2048    | ✔️  | ✔️    |
| 3072    |     | ✔️    |
| 4096    |     | ✔️    |

## Required Properties

This object has no required properties, but it likely requires a combination of optional properties to be useful.

## Optional Properties

### body   ([*certificate*](https://tuono.gitbook.io/userguide/reference/schema/..#certificate))

The PEM-encoded certificate body. This only needs to be present if you are inserting a certificate into the venue. Valid content begins with `----- BEGIN CERTIFICATE -----`.

### chain   ([*string*](https://tuono.gitbook.io/userguide/reference/schema/..#string))

The PEM-encoded certificate chain. This only needs to be present if `body` is present and is derived from a non-authoritative chain. Valid content begins with `----- BEGIN CERTIFICATE -----` and many certificates can be provided at the same time by [concatenating](https://en.wikipedia.org/wiki/Concatenation) them.

### private\_key   ([*private\_key*](https://tuono.gitbook.io/userguide/reference/schema/..#private_key))

A private key is used to guarantee authenticity and validity of data during transmission or in storage.

Provide the PEM-encoded private key protecting the certificate. This private key *cannot* have a passphrase. This must be present if `body` is present. A valid key typically begins with `----- BEGIN PRIVATE KEY -----` or something similar.

{% hint style="danger" %}
We strongly recommend you use a secret variable to fill this property.
{% endhint %}

## Common Properties

### count   ([*integer*](https://tuono.gitbook.io/userguide/reference/schema/..#integer))

Indicates how many of this certificate should exist. When count is specified the name of the given resource will have a hyphen and numeric suffix added automatically, unless the count variable is referenced in the blueprint object name.

### depends\_on   ([⏩](https://tuono.gitbook.io/userguide/reference/schema/..#ref) any)

This property can be used to declare a dependency from this certificate to any other object in the blueprint. This is not necessary for dependencies generated normally by the schema.

### folder   ([▶](https://tuono.gitbook.io/userguide/reference/schema/..#ref) [*location.folder*](https://tuono.gitbook.io/userguide/reference/schema/location/folder))

The folder containing this certificate. If this is not specified and there is only one folder defined, that folder is used automatically.

### name   ([*string*](https://tuono.gitbook.io/userguide/reference/schema/..#string))

The name of this certificate. The name can be different than the blueprint object name. When the name property is not present we apply automatic naming strategies to make resources easier to identify in each venue's management console. When the name property is specified we will use it exactly as specified.

### readonly   ([*boolean*](https://tuono.gitbook.io/userguide/reference/schema/..#boolean))

Indicates whether or not this certificate is read-only. If so, we verify only the existence and correctness of this certificate to its specification rather than creating or modifying it.

The default value if not specified is `false`.

### tags   ([*dict*](https://tuono.gitbook.io/userguide/reference/schema/..#dict))

The tags to place on this certificate. Tags are metadata stored in (key = value, ...) form. Consumers are not allowed to use tags that begin with `_tuono` as those are reserved.

## Discovered Properties

These properties are populated and available in the inventory following a successful apply.

### id   ([*string*](https://tuono.gitbook.io/userguide/reference/schema/..#string))

The venue-specific identifier of this certificate.

## Examples

Import a certificate:

```yaml
location:
  folder:
    example-folder:
      region: example-region
  region:
    example-region:
      area: west
      country: USA
security:
  certificate:
    my-imported-cert:
      body: (( cert_body ))
      private_key: (( private_key ))
variables:
  cert_body:
    description: The certificate body in PEM format.
    type: string
  private_key:
    description: The private key (which cannot have a passphrase) in PEM format.
    type: secret
```

Reference a certificate already stored in the venue by domain name:

```yaml
location:
  folder:
    example-folder:
      region: example-region
  region:
    example-region:
      area: west
      country: USA
security:
  certificate:
    my-existing-cert:
      name: www.mycert.com
      readonly: true
      venue:
        azure:
          key_vault_name: MyKeyVault
```
