Merge branch 'master' of github.com:Netflix/lemur into cname_01
This commit is contained in:
csine-nflx
@ -100,7 +100,7 @@ Specifying the `SQLALCHEMY_MAX_OVERFLOW` to 0 will enforce limit to not create c
|
||||
|
||||
Specifies whether to allow certificates created by Lemur to expire on weekends. Default is True.
|
||||
|
||||
.. data:: LEMUR_WHITELISTED_DOMAINS
|
||||
.. data:: LEMUR_ALLOWED_DOMAINS
|
||||
:noindex:
|
||||
|
||||
List of regular expressions for domain restrictions; if the list is not empty, normal users can only issue
|
||||
@ -155,32 +155,28 @@ Specifying the `SQLALCHEMY_MAX_OVERFLOW` to 0 will enforce limit to not create c
|
||||
|
||||
LEMUR_ENCRYPTION_KEYS = ['1YeftooSbxCiX2zo8m1lXtpvQjy27smZcUUaGmffhMY=', 'LAfQt6yrkLqOK5lwpvQcT4jf2zdeTQJV1uYeh9coT5s=']
|
||||
|
||||
.. data:: PUBLIC_CA_AUTHORITY_NAMES
|
||||
:noindex:
|
||||
A list of public issuers which would be checked against to determine whether limit of max validity of 397 days
|
||||
should be applied to the certificate. Configure public CA authority names in this list to enforce validity check.
|
||||
This is an optional setting. Using this will allow the sanity check as mentioned. The name check is a case-insensitive
|
||||
string comparision.
|
||||
|
||||
.. data:: PUBLIC_CA_MAX_VALIDITY_DAYS
|
||||
:noindex:
|
||||
Use this config to override the limit of 397 days of validity for certificates issued by public issuers configured
|
||||
using PUBLIC_CA_AUTHORITY_NAMES. Below example overrides the default validity of 397 days and sets it to 365 days.
|
||||
Use this config to override the limit of 397 days of validity for certificates issued by CA/Browser compliant authorities.
|
||||
The authorities with cab_compliant option set to true will use this config. The example below overrides the default validity
|
||||
of 397 days and sets it to 365 days.
|
||||
|
||||
::
|
||||
|
||||
PUBLIC_CA_MAX_VALIDITY_DAYS = 365
|
||||
|
||||
|
||||
.. data:: DEFAULT_MAX_VALIDITY_DAYS
|
||||
.. data:: DEFAULT_VALIDITY_DAYS
|
||||
:noindex:
|
||||
Use this config to override the default limit of 1095 days (3 years) of validity. Any CA which is not listed in
|
||||
PUBLIC_CA_AUTHORITY_NAMES will be using this validity to display date range on UI. Below example overrides the
|
||||
default validity of 1095 days and sets it to 365 days.
|
||||
Use this config to override the default validity of 365 days for certificates offered through Lemur UI. Any CA which
|
||||
is not CA/Browser Forum compliant will be using this value as default validity to be displayed on UI. Please
|
||||
note that this config is used for cert issuance only through Lemur UI. The example below overrides the default validity
|
||||
of 365 days and sets it to 1095 days (3 years).
|
||||
|
||||
::
|
||||
|
||||
DEFAULT_MAX_VALIDITY_DAYS = 365
|
||||
DEFAULT_VALIDITY_DAYS = 1095
|
||||
|
||||
|
||||
.. data:: DEBUG_DUMP
|
||||
@ -273,7 +269,7 @@ Certificates marked as inactive will **not** be notified of upcoming expiration.
|
||||
silence the expiration. If a certificate is active and is expiring the above will be notified according to the `LEMUR_DEFAULT_EXPIRATION_NOTIFICATION_INTERVALS` or
|
||||
30, 15, 2 days before expiration if no intervals are set.
|
||||
|
||||
Lemur supports sending certification expiration notifications through SES and SMTP.
|
||||
Lemur supports sending certificate expiration notifications through SES and SMTP.
|
||||
|
||||
|
||||
.. data:: LEMUR_EMAIL_SENDER
|
||||
@ -327,6 +323,54 @@ Lemur supports sending certification expiration notifications through SES and SM
|
||||
LEMUR_SECURITY_TEAM_EMAIL_INTERVALS = [15, 2]
|
||||
|
||||
|
||||
Celery Options
|
||||
---------------
|
||||
To make use of automated tasks within lemur (e.g. syncing source/destinations, or reissuing ACME certificates), you
|
||||
need to configure celery. See :ref:`Periodic Tasks <PeriodicTasks>` for more in depth documentation.
|
||||
|
||||
.. data:: CELERY_RESULT_BACKEND
|
||||
:noindex:
|
||||
|
||||
The url to your redis backend (needs to be in the format `redis://<host>:<port>/<database>`)
|
||||
|
||||
.. data:: CELERY_BROKER_URL
|
||||
:noindex:
|
||||
|
||||
The url to your redis broker (needs to be in the format `redis://<host>:<port>/<database>`)
|
||||
|
||||
.. data:: CELERY_IMPORTS
|
||||
:noindex:
|
||||
|
||||
The module that celery needs to import, in our case thats `lemur.common.celery`
|
||||
|
||||
.. data:: CELERY_TIMEZONE
|
||||
:noindex:
|
||||
|
||||
The timezone for celery to work with
|
||||
|
||||
|
||||
.. data:: CELERYBEAT_SCHEDULE
|
||||
:noindex:
|
||||
|
||||
This defines the schedule, with which the celery beat makes the worker run the specified tasks.
|
||||
|
||||
Since the celery module, relies on the RedisHandler, the following options also need to be set.
|
||||
|
||||
.. data:: REDIS_HOST
|
||||
:noindex:
|
||||
|
||||
Hostname of your redis instance
|
||||
|
||||
.. data:: REDIS_PORT
|
||||
:noindex:
|
||||
|
||||
Port on which redis is running (default: 6379)
|
||||
|
||||
.. data:: REDIS_DB
|
||||
:noindex:
|
||||
|
||||
Which redis database to be used, by default redis offers databases 0-15 (default: 0)
|
||||
|
||||
Authentication Options
|
||||
----------------------
|
||||
Lemur currently supports Basic Authentication, LDAP Authentication, Ping OAuth2, and Google out of the box. Additional flows can be added relatively easily.
|
||||
@ -666,13 +710,20 @@ Active Directory Certificate Services Plugin
|
||||
:noindex:
|
||||
|
||||
Template to be used for certificate issuing. Usually display name w/o spaces
|
||||
|
||||
.. data:: ADCS_TEMPLATE_<upper(authority.name)>
|
||||
:noindex:
|
||||
|
||||
If there is a config variable ADCS_TEMPLATE_<upper(authority.name)> take the value as Cert template else default to ADCS_TEMPLATE to be compatible with former versions. Template to be used for certificate issuing. Usually display name w/o spaces
|
||||
|
||||
.. data:: ADCS_START
|
||||
:noindex:
|
||||
Used in ADCS-Sourceplugin. Minimum id of the first certificate to be returned. ID is increased by one until ADCS_STOP. Missing cert-IDs are ignored
|
||||
|
||||
.. data:: ADCS_STOP
|
||||
:noindex:
|
||||
Used for ADCS-Sourceplugin. Maximum id of the certificates returned.
|
||||
|
||||
|
||||
.. data:: ADCS_ISSUING
|
||||
:noindex:
|
||||
@ -685,6 +736,68 @@ Active Directory Certificate Services Plugin
|
||||
|
||||
Contains the root cert of the CA
|
||||
|
||||
Entrust Plugin
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Enables the creation of Entrust certificates. You need to set the API access up with Entrust support. Check the information in the Entrust Portal as well.
|
||||
Certificates are created as "SERVER_AND_CLIENT_AUTH".
|
||||
Caution: Sometimes the entrust API does not respond in a timely manner. This error is handled and reported by the plugin. Should this happen you just have to hit the create button again after to create a valid certificate.
|
||||
The following parameters have to be set in the configuration files.
|
||||
|
||||
.. data:: ENTRUST_URL
|
||||
:noindex:
|
||||
|
||||
This is the url for the Entrust API. Refer to the API documentation.
|
||||
|
||||
.. data:: ENTRUST_API_CERT
|
||||
:noindex:
|
||||
|
||||
Path to the certificate file in PEM format. This certificate is created in the onboarding process. Refer to the API documentation.
|
||||
|
||||
.. data:: ENTRUST_API_KEY
|
||||
:noindex:
|
||||
|
||||
Path to the key file in RSA format. This certificate is created in the onboarding process. Refer to the API documentation. Caution: the request library cannot handle encrypted keys. The keyfile therefore has to contain the unencrypted key. Please put this in a secure location on the server.
|
||||
|
||||
.. data:: ENTRUST_API_USER
|
||||
:noindex:
|
||||
|
||||
String with the API user. This user is created in the onboarding process. Refer to the API documentation.
|
||||
|
||||
.. data:: ENTRUST_API_PASS
|
||||
:noindex:
|
||||
|
||||
String with the password for the API user. This password is created in the onboarding process. Refer to the API documentation.
|
||||
|
||||
.. data:: ENTRUST_NAME
|
||||
:noindex:
|
||||
|
||||
String with the name that should appear as certificate owner in the Entrust portal. Refer to the API documentation.
|
||||
|
||||
.. data:: ENTRUST_EMAIL
|
||||
:noindex:
|
||||
|
||||
String with the email address that should appear as certificate contact email in the Entrust portal. Refer to the API documentation.
|
||||
|
||||
.. data:: ENTRUST_PHONE
|
||||
:noindex:
|
||||
|
||||
String with the phone number that should appear as certificate contact in the Entrust portal. Refer to the API documentation.
|
||||
|
||||
.. data:: ENTRUST_ISSUING
|
||||
:noindex:
|
||||
|
||||
Contains the issuing cert of the CA
|
||||
|
||||
.. data:: ENTRUST_ROOT
|
||||
:noindex:
|
||||
|
||||
Contains the root cert of the CA
|
||||
|
||||
.. data:: ENTRUST_PRODUCT_<upper(authority.name)>
|
||||
:noindex:
|
||||
|
||||
If there is a config variable ENTRUST_PRODUCT_<upper(authority.name)> take the value as cert product name else default to "STANDARD_SSL". Refer to the API documentation for valid products names.
|
||||
|
||||
Verisign Issuer Plugin
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
@ -1067,6 +1180,23 @@ The following configuration properties are required to use the PowerDNS ACME Plu
|
||||
|
||||
File/Dir path to CA Bundle: Verifies the TLS certificate was issued by a Certificate Authority in the provided CA bundle.
|
||||
|
||||
ACME Plugin
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The following configration properties are optional for the ACME plugin to use. They allow reusing an existing ACME
|
||||
account. See :ref:`Using a pre-existing ACME account <AcmeAccountReuse>` for more details.
|
||||
|
||||
|
||||
.. data:: ACME_PRIVATE_KEY
|
||||
:noindex:
|
||||
|
||||
This is the private key, the account was registered with (in JWK format)
|
||||
|
||||
.. data:: ACME_REGR
|
||||
:noindex:
|
||||
|
||||
This is the registration for the ACME account, the most important part is the uri attribute (in JSON)
|
||||
|
||||
.. _CommandLineInterface:
|
||||
|
||||
Command Line Interface
|
||||
@ -1320,7 +1450,7 @@ Slack
|
||||
Adds support for slack notifications.
|
||||
|
||||
|
||||
AWS
|
||||
AWS (Source)
|
||||
----
|
||||
|
||||
:Authors:
|
||||
@ -1333,7 +1463,7 @@ AWS
|
||||
Uses AWS IAM as a source of certificates to manage. Supports a multi-account deployment.
|
||||
|
||||
|
||||
AWS
|
||||
AWS (Destination)
|
||||
----
|
||||
|
||||
:Authors:
|
||||
@ -1346,6 +1476,19 @@ AWS
|
||||
Uses AWS IAM as a destination for Lemur generated certificates. Support a multi-account deployment.
|
||||
|
||||
|
||||
AWS (SNS Notification)
|
||||
-----
|
||||
|
||||
:Authors:
|
||||
Jasmine Schladen <jschladen@netflix.com>
|
||||
:Type:
|
||||
Notification
|
||||
:Description:
|
||||
Adds support for SNS notifications. SNS notifications (like other notification plugins) are currently only supported
|
||||
for certificate expiration. Configuration requires a region, account number, and SNS topic name; these elements
|
||||
are then combined to build the topic ARN. Lemur must have access to publish messages to the specified SNS topic.
|
||||
|
||||
|
||||
Kubernetes
|
||||
----------
|
||||
|
||||
|
||||
@ -215,18 +215,21 @@ Notification
|
||||
------------
|
||||
|
||||
Lemur includes the ability to create Email notifications by **default**. These notifications
|
||||
currently come in the form of expiration notices. Lemur periodically checks certifications expiration dates and
|
||||
currently come in the form of expiration and rotation notices. Lemur periodically checks certificate expiration dates and
|
||||
determines if a given certificate is eligible for notification. There are currently only two parameters used to
|
||||
determine if a certificate is eligible; validity expiration (date the certificate is no longer valid) and the number
|
||||
of days the current date (UTC) is from that expiration date.
|
||||
|
||||
There are currently two objects that available for notification plugins the first is `NotficationPlugin`. This is the base object for
|
||||
any notification within Lemur. Currently the only support notification type is an certificate expiration notification. If you
|
||||
Expiration notifications can also be configured for Slack or AWS SNS. Rotation notifications are not configurable.
|
||||
Notifications sent to a certificate owner and security team (`LEMUR_SECURITY_TEAM_EMAIL`) can currently only be sent via email.
|
||||
|
||||
There are currently two objects that are available for notification plugins. The first is `NotificationPlugin`, which is the base object for
|
||||
any notification within Lemur. Currently the only supported notification type is a certificate expiration notification. If you
|
||||
are trying to create a new notification type (audit, failed logins, etc.) this would be the object to base your plugin on.
|
||||
You would also then need to build additional code to trigger the new notification type.
|
||||
|
||||
The second is `ExpirationNotificationPlugin`, this object inherits from `NotificationPlugin` object.
|
||||
You will most likely want to base your plugin on, if you want to add new channels for expiration notices (Slack, HipChat, Jira, etc.). It adds default options that are required by
|
||||
The second is `ExpirationNotificationPlugin`, which inherits from the `NotificationPlugin` object.
|
||||
You will most likely want to base your plugin on this object if you want to add new channels for expiration notices (HipChat, Jira, etc.). It adds default options that are required by
|
||||
all expiration notifications (interval, unit). This interface expects for the child to define the following function::
|
||||
|
||||
def send(self, notification_type, message, targets, options, **kwargs):
|
||||
|
||||
@ -49,9 +49,11 @@ The amount of effort you wish to expend ensuring that Lemur has good entropy to
|
||||
|
||||
If you wish to generate more entropy for your system we would suggest you take a look at the following resources:
|
||||
|
||||
- `WES-entropy-client <https://github.com/WhitewoodCrypto/WES-entropy-client>`_
|
||||
- `WES-entropy-client <https://github.com/Virginian/WES-entropy-client>`_
|
||||
- `haveged <http://www.issihosts.com/haveged/>`_
|
||||
|
||||
The original *WES-entropy-client* repository by WhitewoodCrypto was removed, the link now points to a fork of it.
|
||||
|
||||
For additional information about OpenSSL entropy issues:
|
||||
|
||||
- `Managing and Understanding Entropy Usage <https://www.blackhat.com/docs/us-15/materials/us-15-Potter-Understanding-And-Managing-Entropy-Usage.pdf>`_
|
||||
@ -313,6 +315,7 @@ It will start a shell from which you can start/stop/restart the service.
|
||||
|
||||
You can read all errors that might occur from /tmp/lemur.log.
|
||||
|
||||
.. _PeriodicTasks:
|
||||
|
||||
Periodic Tasks
|
||||
==============
|
||||
@ -386,10 +389,17 @@ To enable celery support, you must also have configuration values that tell Cele
|
||||
Here are the Celery configuration variables that should be set::
|
||||
|
||||
CELERY_RESULT_BACKEND = 'redis://your_redis_url:6379'
|
||||
CELERY_BROKER_URL = 'redis://your_redis_url:6379'
|
||||
CELERY_BROKER_URL = 'redis://your_redis_url:6379/0'
|
||||
CELERY_IMPORTS = ('lemur.common.celery')
|
||||
CELERY_TIMEZONE = 'UTC'
|
||||
|
||||
REDIS_HOST="your_redis_url"
|
||||
REDIS_PORT=6379
|
||||
REDIS_DB=0
|
||||
|
||||
Out of the box, every Redis instance supports 16 databases. The default database (`REDIS_DB`) is set to 0, however, you can use any of the databases from 0-15. Via `redis.conf` more databases can be supported.
|
||||
In the `redis://` url, the database number can be added with a slash after the port. (defaults to 0, if omitted)
|
||||
|
||||
Do not forget to import crontab module in your configuration file::
|
||||
|
||||
from celery.task.schedules import crontab
|
||||
@ -501,3 +511,47 @@ The following must be added to the config file to activate the pinning (the pinn
|
||||
KOqkqm57TH2H3eDJAkSnh6/DNFu0Qg==
|
||||
-----END CERTIFICATE-----
|
||||
"""
|
||||
|
||||
|
||||
.. _AcmeAccountReuse:
|
||||
|
||||
LetsEncrypt: Using a pre-existing ACME account
|
||||
-----------------------------------------------
|
||||
|
||||
Let's Encrypt allows reusing an existing ACME account, to create and especially revoke certificates. The current
|
||||
implementation in the acme plugin, only allows for a single account for all ACME authorities, which might be an issue,
|
||||
when you try to use Let's Encrypt together with another certificate authority that uses the ACME protocol.
|
||||
|
||||
To use an existing account, you need to configure the `ACME_PRIVATE_KEY` and `ACME_REGR` variables in the lemur
|
||||
configuration.
|
||||
|
||||
`ACME_PRIVATE_KEY` needs to be in the JWK format::
|
||||
|
||||
{
|
||||
"kty": "RSA",
|
||||
"n": "yr1qBwHizA7ME_iV32bY10ILp.....",
|
||||
"e": "AQAB",
|
||||
"d": "llBlYhil3I.....",
|
||||
"p": "-5LW2Lewogo.........",
|
||||
"q": "zk6dHqHfHksd.........",
|
||||
"dp": "qfe9fFIu3mu.......",
|
||||
"dq": "cXFO-loeOyU.......",
|
||||
"qi": "AfK1sh0_8sLTb..........."
|
||||
}
|
||||
|
||||
|
||||
Using `python-jwt` converting an existing private key in PEM format is quite easy::
|
||||
|
||||
import python_jwt as jwt, jwcrypto.jwk as jwk
|
||||
|
||||
priv_key = jwk.JWK.from_pem(b"""-----BEGIN RSA PRIVATE KEY-----
|
||||
...
|
||||
-----END RSA PRIVATE KEY-----""")
|
||||
|
||||
print(priv_key.export())
|
||||
|
||||
`ACME_REGR` needs to be a valid JSON with a `body` and a `uri` attribute, similar to this::
|
||||
|
||||
{"body": {}, "uri": "https://acme-staging-v02.api.letsencrypt.org/acme/acct/<ACCOUNT_NUMBER>"}
|
||||
|
||||
The URI can be retrieved from the ACME create account endpoint when creating a new account, using the existing key.
|
||||
Reference in New Issue
Block a user