# HyperOne dns provider interface in lego

## Possible options

### Configuration based on environment variables
Pros:
- most typical (nearly all dns providers in lego library uses env var based configuration)
- AD: "nearly all" which not? what solution they use instad?
- JS: for example google is using auth based on file
- easy to implement (lego library contains ready config parser)

Cons:
- requires user to manually enter all required data
- setting asimetric keys as env vars is problematic (requires escaped characters)

### Configuration using passport file

Pros:
- easy to setup using h1 cli
- using passport file may be the first step to standarize usage of tools related to H1

Cons:
- harder to implement
- atypical considering other dns providers in this library
- requires environment variable anyway

#### Default location
Setting default location for passport file may become a rule, so in future this location may be used by other applications. My suggestion is to use some directory in home dir (for example `~/.h1/`) to store `passport.json` file.

## Environment variable name propositions

* `HYPERONE_PASSPORT_LOCATION`- for custom passport file location (example `/home/differentuser/passport.json`)
* AD: what about default location?
* JS: _custom passport file location_ this var could be used just for custom ones
* AD: proposal? what is your suggestion, should we support the default one?
* there is a section about it above

* AD: did you consider provide all values seperatly?

* JS: this is what most of the providers are doing, however providing asymmetric keys as environment variables is something strange, because it requires escaping some chars
* AD: "most provider doing" how do we know that?
* JS: it can be easily checked in [lego source code](https://github.com/go-acme/lego/tree/master/providers/dns)
* AD: are we supposed to become experts in Lego source code?
* JS: no, thats why i am saying how most of providers are doing it. it can be also checked in [lego documentation](https://go-acme.github.io/lego/dns/)
* AD: what provider do you known which use asymetric key cryptography for API authentication?
* JS: i haven't seen
* AD: Google use asymetric key cryptography
* JS: saying that i haven't seen ones was meant to mean that i haven't seen ones using it "not under the hood"- most of apps doing it are operating either on cli or on files, which "returns" to problem we are trying to avoid.
* AD: Azure can use asymetric key crytography too, so most of hyperscale cloud provider support asymetric key cryptography
* AD: what about ci system which does not support file-based env vars?
* JS: it's not about file-based env vars, because env vars can be set either from any 'built in' way or via env file, just about access to file system to create/copy passport file. despite this there is a workaround, because file can be created in fe. bash script
* AD: Are you designing a solution to introduce workarounds from the beginning?
* JS: 'straightforward' setting environment variables requires nearly same amount code lines, it just does not need it to be saved to file. also, in a lot of management solutions it can be managed as some kind of secret. for example in kubernetes you can create a job which can open cli, login, create credentials file and save it as a secret, which can be mounted to pods
* AD: "kubernetes", I'm glad you're starting to consider the ecosystem
* AD: why `_LOCATION`? if I understand correctly, Lego by default reads the contents of the file indicated in the "X_FILE" variable into the "X" variable ( https://go-acme.github.io/lego/dns/#environment-variables-file )
* i don't want lego to open this file, just to parse it "manually" (https://github.com/kuskoman/lego/blob/hyperone/providers/dns/hyperone/internal/passport.go)
* AD: why?
* `HYPERONE_DNS_ZONE_URI`- for identyfing DNS zone to be used by application (example: `/dns/pl-waw-1/project/5af0bbbcb7802xxxxxxxx/zone/5ef9ea7180xxxxxxxxx`)
* AD: what about subdomains?
* JS: guess there can be another env var for specifying a subdomain if there is a need to (if action has to be taken on subdomain, not on "main") domain
* AD: how other is solving that in lego? maybe we don't need?
* AD: what about ALIAS mode? (https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode) we need support for that on back-end?
* JS: i feel like it's more a kind of alternative way of handling it, i don't think that we need to support it as long as there is a decent api
* AD: what about default?
* JS: specify question
* AD: If the certificate renewal request contains the domain name, and we have a default project in the passport, we could automatically detect the appropriate DNS zone if not for the "location" parameter. See also property `ECS_CLUSTER` in Amazon ECS Container Agent ( https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html ).

## market (section added by @ad-m)

### google

credential source:

* environment variable `GOOGLE_APPLICATION_CREDENTIALS` with path to "passport" file
* metadata service

note:

* no delegation flow

### aws

default credential chain:

AWS.CredentialProviderChain.defaultProviders = [
  function () { return new AWS.EnvironmentCredentials('AWS'); }, // 1
  function () { return new AWS.EnvironmentCredentials('AMAZON'); }, // 2
  function () { return new AWS.SharedIniFileCredentials(); }, // 3
  function () { return new AWS.ECSCredentials(); }, // 4
  function () { return new AWS.ProcessCredentials(); }, // 5
  function () { return new AWS.TokenFileWebIdentityCredentials(); }, // 6
  function () { return new AWS.EC2MetadataCredentials() } // 7
]

it mean:

1. `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`
2. `AMAZON_ACCESS_KEY_ID`, `AMAZON_SECRET_ACCESS_KEY`, `AMAZON_SESSION_TOKEN`
3. `AWS_SHARED_CREDENTIALS_FILE` (default to INI file: `~/.aws/credentials`) + `AWS_PROFILE` (default to: `default`)
4. `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` and `AWS_CONTAINER_CREDENTIALS_FULL_URI` + response like `AssumeRole`
5. as option 3
6. `AWS_WEB_IDENTITY_TOKEN_FILE` and `AWS_ROLE_ARN`
7. metadata service

ad. 3. example INI-file:

[default]
aws_access_key_id = AKID...
aws_secret_access_key = YOUR_SECRET_KEY

ad. 4. example INI-file:

[default]
credential_process = /usr/bin/credential_proc

### azure

1. `EnvironmentCredential` -
* `AZURE_CLIENT_ID` – service principal's app id
* `AZURE_TENANT_ID` – id of the principal's Azure Active Directory tenant
* `AZURE_CLIENT_SECRET` – one of the service principal's client secrets (implies ClientSecretCredential)
* `AZURE_CLIENT_CERTIFICATE_PATH` – one of the service principal's client secrets (implies ClientCertificateCredential)
* https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-certificate-credentials#register-your-certificate-with-azure-ad
* `AZURE_USERNAME` – the username of a user in the tenant (implies UsernamePasswordCredential)
* `AZURE_PASSWORD` – the password of the user specified in AZURE_USERNAME
3. `ManagedIdentityCredential` - metadata service

### other interesting?

## Current state

Legon can works in two mode:

* Among the Lego providers, automatic DNS **zone detection** at the provider is popular, based on the request to create a certificate:
* **Zone indication** of a particular DNS zone is also often supported (in addition to automatic detection).

All Lego provioder configuration is done through environment variables.

CLI (Traefik etc.) parameters only specify the configurations of the request, the selected provider, but not its configurations.

Lego for HyperOne use following endpoints:

resourceURL := fmt.Sprintf("%s/dns/%s/project/%s/zone/%s/recordset", c.APIEndpoint, c.LocationID, c.ProjectID, c.ZoneID)
resourceURL := fmt.Sprintf("%s/dns/%s/project/%s/zone/%s/recordset/%s/record", c.APIEndpoint, c.LocationID, c.ProjectID, c.ZoneID, recordsetID)
resourceURL := fmt.Sprintf("%s/dns/%s/project/%s/zone/%s/recordset", c.APIEndpoint, c.LocationID, c.ProjectID, c.ZoneID)
resourceURL := fmt.Sprintf("%s/dns/%s/project/%s/zone/%s/recordset/%s/record", c.APIEndpoint, c.LocationID, c.ProjectID, c.ZoneID, recordsetID)
resourceURL := fmt.Sprintf("%s/dns/%s/project/%s/zone/%s/recordset/%s/record/%s", c.APIEndpoint, c.LocationID, c.ProjectID, c.ZoneID, recordsetID, recordID)
resourceURL := fmt.Sprintf("%s/dns/%s/project/%s/zone/%s/recordset/%s", c.APIEndpoint, c.LocationID, c.ProjectID, c.ZoneID, recordsetID)
resourceURL := fmt.Sprintf("%s/dns/%s/project/%s/zone", c.APIEndpoint, c.LocationID, c.ProjectID)

Suggested environment variables:

- `HYPERONE_PASSPORT_FILE` (now: `HYPERONE_PASSPORT_LOCATION`) - location of passport file
- CLI use `HYPERONE_PASSPORT_FILE`
- default to: `~/.h1/passport.json` (I like it a much!)
- CLI use path `~/.h1-cli/conf.json`, but in v2 i think we should go out of that
- Azure: `AZURE_CLIENT_CERTIFICATE_PATH`
- AWS: `AWS_SHARED_CREDENTIALS_FILE` (~)
- `HYPERONE_API_URL` - Allows to pass custom API Endpoint to be used in the challenge (default https://api.hyperone.com/v2)
- follow standard of Packer to use

required to discovery zone based on
- `HYPERONE_LOCATION_ID` - Specifies location (region) to be used in API calls. (default pl-waw-1)
- HyperOne comment:
- Required to fetch all zones eg. `/dns/{locationId}/project/*/zone`
- We have not introduced resource identifier for the location eg. `/world/pl-waw-1/`
- We have not introduced resource identifier for collection eg. `/dns/pl-waw-1/project/x/zone/`
- Lego have to fetch available zones in discovery mode
- Azure: not apply, (global available) resource group used
- GCE: not apply, global
- Route53: not apply, global
- `HYPERONE_PROJECT_ID` - Specifies the project where the application looks for DNS zone (if not set fetched from passport file)
- HyperOne comment:
- Lego have to fetch available zones in discovery mode
- Project require parsing to switch namespace `/iam/project/{projectId}` --> `/dns/*/project/{projectId}/zone`
- GCE: `GCE_PROJECT`,
- Azure: `AZURE_RESOURCE_GROUP`, `AZURE_SUBSCRIPTION_ID`, `AZURE_TENANT_ID`

required to manual mode:
- `HYPERONE_ZONE_ID` - Specifies zone where records are being set (if not set fetched from passport file)
- HyperOne comment:
- Resource Identifier fit, not used (yet)
- Use `HYPERONE_ZONE_ID`
- AWS: `AWS_HOSTED_ZONE_ID` (note: Route53 is global, nor use ARN),
- GCP - not supportd
- Azure - not supported

generic and user by other provider:
- `HYPERONE_TTL` - The TTL of the TXT record used for the DNS challenge
- example: `AWS_TTL`, `CLOUDFLARE_TTL`, `GCP_TTL`, `AZURE_TTL`
- `HYPERONE_PROPAGATION_TIMEOUT` - Maximum waiting time for DNS propagation
- example: `AWS_PROPAGATION_TIMEOUT`, `CLOUDFLARE_PROPAGATION_TIMEOUT`, `GCP_PROPAGATION_TIMEOUT`, `AZURE_PROPAGATION_TIMEOUT`
- `HYPERONE_POLLING_INTERVAL` - Time between DNS propagation check
- example: `AWS_POLLING_INTERVAL`, `GCP_POLLING_INTERVAL`, `AZURE_PROPAGATION_TIMEOUT`

other worth notice:

- `CLOUDFLARE_HTTP_TIMEOUT`
- `AZURE_METADATA_ENDPOINT`