From e951e5352e54b8b6c95008e8fdaf50cf9b24bf32 Mon Sep 17 00:00:00 2001 From: Allan Banaag Date: Thu, 24 Oct 2019 14:09:09 -0700 Subject: [PATCH 1/4] First pass at updating amppkg.example.toml --- amppkg.example.toml | 88 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/amppkg.example.toml b/amppkg.example.toml index 2ac6f8872..0301defb7 100644 --- a/amppkg.example.toml +++ b/amppkg.example.toml @@ -47,6 +47,24 @@ # SHA-256). CertFile = './pems/cert.pem' +# The path to save a new cert retrieved from the CA if the current cert in +# 'CertFile' above is still valid. +# This is optional and is needed only if you have 'autorenewcert' # turned on. +# NewCertFile = './pems/newcert.pem' + +# The path to the Certificate Signing Request (CSR) that is needed to request +# new certificates from the Cert Authority using ACME. +# CSRs are typically created using the openssl command: +# openssl req -new -key /path/to/privkey -out /path/to/cert.csr +# To verify: +# openssl req -text -noout -verify -in cert.csr +# The following docs list examples on how to go about generating CSRs: +# https://www.digicert.com/csr-creation.htm?rid=011592 +# https://www.ssl.com/how-to/manually-generate-a-certificate-signing-request-csr-using-openssl/ +# https://geekflare.com/san-ssl-certificate/ +# This is optional and is needed only if you have 'autorenewcert' # turned on. +# CSRFile = './pems/cert.csr' + # The path to the PEM file containing the private key that corresponds to the # leaf certificate in CertFile. KeyFile = './pems/privkey.pem' @@ -170,3 +188,73 @@ ForwardedRequestHeaders = [] # Domain = "www.corp.amppackageexample.com" # PathRE = "/world/.*" # QueryRE = "" + +# ACME is a protocol that allows for automatic renewal of certificates. Amp packager uses an ACME library +# https://github.com/go-acme/lego to handle certificate renewal. +# +# For the full ACME spec, see: +# https://tools.ietf.org/html/draft-ietf-acme-acme-02 +# https://ietf-wg-acme.github.io/acme/draft-ietf-acme-acme.html +# +# ACMEConfig only needs to be present in the toml file if 'autorenewcert' command line flag was turned on. +# If the flag is on, at least one of ACMEConfig.Production or ACMEConfig.Development should be present. +# Note that a recommended best practice for setting up the cert renewal that minimizes both cost and bombarding +# your Certificate Authority with requests is that for a multi-instance setup of AMP packager, only one instance is +# setup to do automatic cert renewals and the rest of the instances will just be configured to reload the fresh +# certificate from disk when their in-memory copies expire. This also implies that the cert paths configured above +# in 'CertFile' and 'NewCertFile' are located on a shared filesystem accessible by all AMP packager instances. +# [ACMEConfig] + # [ACMEConfig.Production] + # This config will be used if 'autorenewcert' is turned on and 'development' is turned off. + # This is the ACME discovery URL that is used for ACME http requests to the Certificate authority that + # doles out the certificates. + # Currently, the only CA that supports automatic signed exchange cert renewals is Digicert: + # https://docs.digicert.com/certificate-tools/acme-user-guide/acme-directory-urls-signed-http-exchange-certificates/ + # + # DiscoURL = "production-acme.discovery.url" + # + # This is the email address you used to create an account with the Certificate Authority that is registered to + # request signed exchange certificates. + # + # EmailAddress = "user@company.com" + # + # For the remaining configuration items, it's important to understand the different challenges employed as + # part of the ACME protocol. See: + # https://ietf-wg-acme.github.io/acme/draft-ietf-acme-acme.html#identifier-validation-challenges + # https://letsencrypt.org/docs/challenge-types/ + # https://certbot.eff.org/docs/challenges.html?highlight=http + # + # This is the port used by the Amp packager to respond to the HTTP challenge issued as part of ACME protocol. + # Note that if your setup only opens up certain ports, you may need to do a configuration change where you forward + # requests to this port using proxy_pass, for example: + # https://medium.com/@dipeshwagle/add-https-using-lets-encrypt-to-nginx-configured-as-a-reverse-proxy-on-ubuntu-b4455a729176 + # + # HttpChallengePort = 5002 + # + # This is the http server root directory where the ACME http challenge token could be deposited. Note that you may + # need to do some configuration work to get this setup to work where multiple instances of Amp packager is running. + # For example: + # https://community.letsencrypt.org/t/how-to-nginx-configuration-to-enable-acme-challenge-support-on-all-http-virtual-hosts/5622/3 + # + # HttpWebRootDir = '/path/to/www_root_dir' + # + # This is the port used by AMP packager to respond to the TLS challenge issued as part of the ACME protocol. + # + # TlsChallengePort = 5003 + # + # This is the DnsProvider to be used in fulfilling the ACME DNS challenge. Note that you only need the DNS challenge + # setup if you have wildcard certificates. See: https://searchsecurity.techtarget.com/definition/wildcard-certificate + # For the DNS challenge, go-acme/lego, there are certain environment variables that need to be set up which depends on + # the DNS provider that you use to fulfill the DNS challenge. See: + # https://go-acme.github.io/lego/dns/ + # DnsProvider = "gcloud" + # [ACMEConfig.Development] + # This config will ne used if 'autorenewcert' is turned on and 'development' is turned on. + # All the other fields below have the same semantics as the one in ACMEConfig.Production above. + # DiscoURL = "development-acme.discovery.url" + # EmailAddress = "user@company.com" + # HttpChallengePort = 5002 + # HttpWebRootDir = '/path/to/www_root_dir' + # TlsChallengePort = 5003 + # DnsProvider = "gcloud" + From 2732e424cef87cf141a8697f77c1db10cbb85b6e Mon Sep 17 00:00:00 2001 From: Allan Banaag Date: Thu, 24 Oct 2019 14:41:31 -0700 Subject: [PATCH 2/4] Added some more comments regarding challenges. --- amppkg.example.toml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/amppkg.example.toml b/amppkg.example.toml index 0301defb7..a1dfbdcaf 100644 --- a/amppkg.example.toml +++ b/amppkg.example.toml @@ -223,6 +223,8 @@ ForwardedRequestHeaders = [] # https://ietf-wg-acme.github.io/acme/draft-ietf-acme-acme.html#identifier-validation-challenges # https://letsencrypt.org/docs/challenge-types/ # https://certbot.eff.org/docs/challenges.html?highlight=http + # Note that you don't need to have all the challenges configured, it's typically sufficient to have one configured. + # The exception arises when you have to deal with wildcard certificates, see below. # # This is the port used by the Amp packager to respond to the HTTP challenge issued as part of ACME protocol. # Note that if your setup only opens up certain ports, you may need to do a configuration change where you forward From 39e39808222922a71669346d29c82b9b43278b64 Mon Sep 17 00:00:00 2001 From: banaag Date: Fri, 15 Nov 2019 09:18:34 -0800 Subject: [PATCH 3/4] Fix twifkak@ comments. --- amppkg.example.toml | 76 +++++++++++++++++++++++++-------------------- 1 file changed, 43 insertions(+), 33 deletions(-) diff --git a/amppkg.example.toml b/amppkg.example.toml index a1dfbdcaf..b4975fd20 100644 --- a/amppkg.example.toml +++ b/amppkg.example.toml @@ -49,11 +49,13 @@ CertFile = './pems/cert.pem' # The path to save a new cert retrieved from the CA if the current cert in # 'CertFile' above is still valid. -# This is optional and is needed only if you have 'autorenewcert' # turned on. +# This is optional and is needed only if you have 'autorenewcert' turned on. +# For multi-replica setups (multiple AMP Packager instances), only the replica +# that will do the autorenewal of certs needs this config item set. # NewCertFile = './pems/newcert.pem' # The path to the Certificate Signing Request (CSR) that is needed to request -# new certificates from the Cert Authority using ACME. +# new certificates from the Certificate Authority using ACME. # CSRs are typically created using the openssl command: # openssl req -new -key /path/to/privkey -out /path/to/cert.csr # To verify: @@ -62,7 +64,7 @@ CertFile = './pems/cert.pem' # https://www.digicert.com/csr-creation.htm?rid=011592 # https://www.ssl.com/how-to/manually-generate-a-certificate-signing-request-csr-using-openssl/ # https://geekflare.com/san-ssl-certificate/ -# This is optional and is needed only if you have 'autorenewcert' # turned on. +# This is optional and is needed only if you have 'autorenewcert' turned on. # CSRFile = './pems/cert.csr' # The path to the PEM file containing the private key that corresponds to the @@ -189,12 +191,15 @@ ForwardedRequestHeaders = [] # PathRE = "/world/.*" # QueryRE = "" -# ACME is a protocol that allows for automatic renewal of certificates. Amp packager uses an ACME library -# https://github.com/go-acme/lego to handle certificate renewal. +# IMPORTANT NOTE: the support of the ACME protocol and automatic renewal of certificates is currently in the +# EXPERIMENTAL stage. Once we have more experience with people using it out in the wild, we will gradually +# move it to PRODUCTION mode. # -# For the full ACME spec, see: -# https://tools.ietf.org/html/draft-ietf-acme-acme-02 -# https://ietf-wg-acme.github.io/acme/draft-ietf-acme-acme.html +# ACME is a protocol that allows for automatic renewal of certificates. AMP Packager uses an ACME library +# https://github.com/go-acme/lego to handle certificate renewal. Automatic certificate renewal is enabled +# in AMP Packager via the 'autorenewcert' flag. Turning the flag on will enable AMP Packager to automatically +# request certificate renewals whenever it has determined that the current certificate is expired or about to +# expire. # # ACMEConfig only needs to be present in the toml file if 'autorenewcert' command line flag was turned on. # If the flag is on, at least one of ACMEConfig.Production or ACMEConfig.Development should be present. @@ -203,57 +208,62 @@ ForwardedRequestHeaders = [] # setup to do automatic cert renewals and the rest of the instances will just be configured to reload the fresh # certificate from disk when their in-memory copies expire. This also implies that the cert paths configured above # in 'CertFile' and 'NewCertFile' are located on a shared filesystem accessible by all AMP packager instances. +# +# For the full ACME spec, see: +# https://tools.ietf.org/html/draft-ietf-acme-acme-02 +# https://ietf-wg-acme.github.io/acme/draft-ietf-acme-acme.html +# TODO(banaag): consider renaming ACMEConfig to ACME # [ACMEConfig] - # [ACMEConfig.Production] # This config will be used if 'autorenewcert' is turned on and 'development' is turned off. - # This is the ACME discovery URL that is used for ACME http requests to the Certificate authority that + # If the flags above are on but we don't have an entry here, AMP Packager will not start. + # [ACMEConfig.Production] + # This is the ACME discovery URL that is used for ACME http requests to the Certificate Authority that # doles out the certificates. # Currently, the only CA that supports automatic signed exchange cert renewals is Digicert: # https://docs.digicert.com/certificate-tools/acme-user-guide/acme-directory-urls-signed-http-exchange-certificates/ - # - # DiscoURL = "production-acme.discovery.url" - # + + # DiscoURL = "https://production-acme.discovery.url/" + # This is the email address you used to create an account with the Certificate Authority that is registered to # request signed exchange certificates. - # + # EmailAddress = "user@company.com" - # + # For the remaining configuration items, it's important to understand the different challenges employed as # part of the ACME protocol. See: - # https://ietf-wg-acme.github.io/acme/draft-ietf-acme-acme.html#identifier-validation-challenges + # https://ietf-wg-acme.github.io/acme/draft-ietf-acme-acme.html#identifier-validation-challenges # https://letsencrypt.org/docs/challenge-types/ - # https://certbot.eff.org/docs/challenges.html?highlight=http + # https://certbot.eff.org/docs/challenges.html?highlight=http # Note that you don't need to have all the challenges configured, it's typically sufficient to have one configured. # The exception arises when you have to deal with wildcard certificates, see below. - # - # This is the port used by the Amp packager to respond to the HTTP challenge issued as part of ACME protocol. - # Note that if your setup only opens up certain ports, you may need to do a configuration change where you forward - # requests to this port using proxy_pass, for example: - # https://medium.com/@dipeshwagle/add-https-using-lets-encrypt-to-nginx-configured-as-a-reverse-proxy-on-ubuntu-b4455a729176 - # - # HttpChallengePort = 5002 - # + # This is the http server root directory where the ACME http challenge token could be deposited. Note that you may - # need to do some configuration work to get this setup to work where multiple instances of Amp packager is running. + # need to do some configuration work to get this setup to work where multiple instances of AMP Packager is running. # For example: # https://community.letsencrypt.org/t/how-to-nginx-configuration-to-enable-acme-challenge-support-on-all-http-virtual-hosts/5622/3 - # # HttpWebRootDir = '/path/to/www_root_dir' - # + + # This is the port used by the AMP Packager to respond to the HTTP challenge issued as part of ACME protocol. + # Note that if your setup only opens up certain ports, you may need to do a configuration change where you forward + # requests to this port using proxy_pass, for example: + # https://medium.com/@dipeshwagle/add-https-using-lets-encrypt-to-nginx-configured-as-a-reverse-proxy-on-ubuntu-b4455a729176 + # HttpChallengePort = 5002 + # This is the port used by AMP packager to respond to the TLS challenge issued as part of the ACME protocol. - # # TlsChallengePort = 5003 - # + # This is the DnsProvider to be used in fulfilling the ACME DNS challenge. Note that you only need the DNS challenge # setup if you have wildcard certificates. See: https://searchsecurity.techtarget.com/definition/wildcard-certificate # For the DNS challenge, go-acme/lego, there are certain environment variables that need to be set up which depends on # the DNS provider that you use to fulfill the DNS challenge. See: # https://go-acme.github.io/lego/dns/ # DnsProvider = "gcloud" - # [ACMEConfig.Development] - # This config will ne used if 'autorenewcert' is turned on and 'development' is turned on. + # This config will be used if 'autorenewcert' is turned on and 'development' is turned on. + # If the flags above are on but we don't have an entry here, AMP Packager will not start. # All the other fields below have the same semantics as the one in ACMEConfig.Production above. - # DiscoURL = "development-acme.discovery.url" + # For development mode, given that we don't require the SXG extension, one can use Let's Encrypt CA to generate the certs. + # [ACMEConfig.Development] + # DiscoURL = "https://development-acme.discovery.url/" # EmailAddress = "user@company.com" # HttpChallengePort = 5002 # HttpWebRootDir = '/path/to/www_root_dir' From 5fe643e98954ef3670fbc336f3ee4cf1a8eaf9ce Mon Sep 17 00:00:00 2001 From: Devin Mullins Date: Wed, 4 Dec 2019 17:04:23 -0800 Subject: [PATCH 4/4] blank lines --- amppkg.example.toml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/amppkg.example.toml b/amppkg.example.toml index b4975fd20..2431bcc3a 100644 --- a/amppkg.example.toml +++ b/amppkg.example.toml @@ -221,12 +221,10 @@ ForwardedRequestHeaders = [] # doles out the certificates. # Currently, the only CA that supports automatic signed exchange cert renewals is Digicert: # https://docs.digicert.com/certificate-tools/acme-user-guide/acme-directory-urls-signed-http-exchange-certificates/ - # DiscoURL = "https://production-acme.discovery.url/" # This is the email address you used to create an account with the Certificate Authority that is registered to # request signed exchange certificates. - # EmailAddress = "user@company.com" # For the remaining configuration items, it's important to understand the different challenges employed as @@ -258,6 +256,7 @@ ForwardedRequestHeaders = [] # the DNS provider that you use to fulfill the DNS challenge. See: # https://go-acme.github.io/lego/dns/ # DnsProvider = "gcloud" + # This config will be used if 'autorenewcert' is turned on and 'development' is turned on. # If the flags above are on but we don't have an entry here, AMP Packager will not start. # All the other fields below have the same semantics as the one in ACMEConfig.Production above. @@ -269,4 +268,3 @@ ForwardedRequestHeaders = [] # HttpWebRootDir = '/path/to/www_root_dir' # TlsChallengePort = 5003 # DnsProvider = "gcloud" -