certificates Package

models Module

class lemur.certificates.models.Certificate(**kwargs)

Bases: Model

property active
authority
authority_id
bits
body
certificate_associations
chain
check_integrity()

Integrity checks: Does the cert have a valid chain and matching private key?

cn
property country
csr
date_created
deleted
description
destinations
property distinguished_name
dns_provider
dns_provider_id
domains = ObjectAssociationProxyInstance(AssociationProxy('certificate_associations', 'domain'))
endpoints
expired
property extensions
external_id
has_private_key
id
in_rotation_window

Determines if a certificate is available for rotation based on the rotation policy associated. :return:

issuer
ix = Index('ix_certificates_id_desc', <sqlalchemy.sql.elements.UnaryExpression object>, unique=True)
key_type
property location
logs
name
not_after
not_after_ix = Index('ix_certificates_not_after', <sqlalchemy.sql.elements.UnaryExpression object>)
not_before
notification
notifications
notify
property organization
property organizational_unit
owner
property parsed_cert
pending_cert
private_key
property public_key
replaced
replaced_by_pending
replaces
revoked
role
roles
root_authority
root_authority_id
rotation
rotation_policy
rotation_policy_id
san
sensitive_fields = ('private_key',)
serial
signing_algorithm
sources
property state
status
property subject
user
user_id
property validity_range
property validity_remaining
class lemur.certificates.models.CertificateAssociation(domain=None, certificate=None, ports=None)

Bases: Model

certificate
certificate_id
domain
domain_id
ports
lemur.certificates.models.get_or_increase_name(name, serial)
lemur.certificates.models.get_sequence(name)
lemur.certificates.models.update_destinations(target, value, initiator)

Attempt to upload certificate to the new destination

Parameters:
  • target

  • value

  • initiator

Returns:

lemur.certificates.models.update_replacement(target, value, initiator)

When a certificate is marked as ‘replaced’ we should not notify.

Parameters:
  • target

  • value

  • initiator

Returns:

service Module

lemur.certificates.service.allowed_issuance_for_domain(common_name, extensions)
lemur.certificates.service.calculate_reissue_range(start, end)

Determine what the new validity_start and validity_end dates should be. :param start: :param end: :return:

lemur.certificates.service.cleanup_after_revoke(certificate)

Perform the needed cleanup for a revoked certificate. This includes - 1. Notify (if enabled) 2. Disabling notification 3. Disabling auto-rotation 4. Update certificate status to ‘revoked’ 5. Remove from AWS :param certificate: Certificate object to modify and update in DB :return: None

lemur.certificates.service.cleanup_owner_roles_notification(owner_name, kwargs)
lemur.certificates.service.create(**kwargs)

Creates a new certificate.

lemur.certificates.service.create_certificate_roles(**kwargs)
lemur.certificates.service.create_csr(**csr_config)

Given a list of domains create the appropriate csr for those domains

Parameters:

csr_config

lemur.certificates.service.deactivate(certificate)
lemur.certificates.service.delete(cert_id)

Delete’s a certificate.

Parameters:

cert_id

lemur.certificates.service.export(cert, export_plugin)

Exports a certificate to the requested format. This format may be a binary format.

Parameters:
  • export_plugin

  • cert

Returns:

lemur.certificates.service.find_and_persist_domains_where_cert_is_deployed(certificate, excluded_domains, commit, timeout_seconds_per_network_call)

Checks if the specified cert is still deployed. Returns a list of domains to which it’s deployed.

We use the serial number to identify that a certificate is identical. If there were multiple certificates issued for the same domain with identical serial numbers, this could return a false positive.

Note that this checks all configured ports (specified in config LEMUR_PORTS_FOR_DEPLOYED_CERTIFICATE_CHECK) for all the domains in the cert. If the domain is valid but the port is not, we have to wait for the connection to time out, which means this can be quite slow.

Returns:

A dictionary of the form {‘domain1’: [ports], ‘domain2’: [ports]}

lemur.certificates.service.find_duplicates(cert)

Finds certificates that already exist within Lemur. We do this by looking for certificate bodies that are the same. This is the most reliable way to determine if a certificate is already being tracked by Lemur.

Parameters:

cert

Returns:

lemur.certificates.service.get(cert_id)

Retrieves certificate by its ID.

Parameters:

cert_id

Returns:

lemur.certificates.service.get_account_number(arn)

Extract the account number from an arn.

Parameters:

arn – IAM SSL arn

Returns:

account number associated with ARN

lemur.certificates.service.get_all_certs()

Retrieves all certificates within Lemur.

Returns:

lemur.certificates.service.get_all_certs_attached_to_destination_without_autorotate(plugin_name=None)

Retrieves all certificates that are attached to a destination, but that do not have autorotate enabled.

Parameters:

plugin_name – Optional destination plugin name to query. Queries certificates attached to any destination if not provided.

Returns:

list of certificates attached to a destination without autorotate

lemur.certificates.service.get_all_certs_attached_to_endpoint_without_autorotate()

Retrieves all certificates that are attached to an endpoint, but that do not have autorotate enabled.

Returns:

list of certificates attached to an endpoint without autorotate

lemur.certificates.service.get_all_pending_cleaning_expired(source)

Retrieves all certificates that are available for cleaning. These are certificates which are expired and are not attached to any endpoints.

Parameters:

source – the source to search for certificates

Returns:

list of pending certificates

lemur.certificates.service.get_all_pending_cleaning_expiring_in_days(source, days_to_expire)

Retrieves all certificates that are available for cleaning, not attached to endpoint, and within X days from expiration.

Parameters:
  • days_to_expire – defines how many days till the certificate is expired

  • source – the source to search for certificates

Returns:

list of pending certificates

lemur.certificates.service.get_all_pending_cleaning_issued_since_days(source, days_since_issuance)

Retrieves all certificates that are available for cleaning: not attached to endpoint, and X days since issuance.

Parameters:
  • days_since_issuance – defines how many days since the certificate is issued

  • source – the source to search for certificates

Returns:

list of pending certificates

lemur.certificates.service.get_all_pending_reissue()

Retrieves all certificates that need to be rotated.

Must be X days from expiration, uses the certificates rotation policy to determine how many days from expiration the certificate must be for rotation to be pending.

Returns:

lemur.certificates.service.get_all_valid_certificates_with_destination(destination_id)

Return list of certificates :param destination_id: :return:

lemur.certificates.service.get_all_valid_certificates_with_source(source_id)

Return list of certificates :param source_id: :return:

lemur.certificates.service.get_all_valid_certs(authority_plugin_name, paginate=False, page=1, count=1000, created_on_or_before=None)

Retrieves all valid (not expired & not revoked) certificates within Lemur, for the given authority plugin names ignored if no authority_plugin_name provided.

Note that depending on the DB size retrieving all certificates might an expensive operation :param paginate: option to use pagination, for large number of certificates. default to false :param page: the page to turn. default to 1 :param count: number of return certificates per page. default 1000 :param created_on_or_before: optional Arrow date to select only certificates issued on or before the date

Returns:

list of certificates to check for revocation

lemur.certificates.service.get_by_attributes(conditions)

Retrieves certificate(s) by conditions given in a hash of given key=>value pairs. :param serial: :return:

lemur.certificates.service.get_by_name(name)

Retrieves certificate by its Name.

Parameters:

name

Returns:

lemur.certificates.service.get_by_serial(serial)

Retrieves certificate(s) by serial number. :param serial: :return:

lemur.certificates.service.get_certificate_primitives(certificate)

Retrieve key primitive from a certificate such that the certificate could be recreated with new expiration or be used to build upon. :param certificate: :return: dict of certificate primitives, should be enough to effectively re-issue certificate via create.

lemur.certificates.service.get_certificates_for_expiration_metrics(expiry_window)
Parameters:

expiry_window – defines the window for cert filter, ex: 90 will only return certs expiring in the next 90 days.

Returns:

list of certificates

lemur.certificates.service.get_certificates_with_same_cn_with_rotate_on(cn, date_created)

Find certificates with given common name created on date_created that are still valid, not replaced and marked for auto-rotate

Parameters:
  • cn – common name to match

  • date_created – creation date

Returns:

List of certificates matching the criteria

lemur.certificates.service.get_certs_for_expiring_deployed_cert_check(exclude_domains, exclude_owners)
lemur.certificates.service.get_ekus(csr: str)

Given a csr PEM, return the

lemur.certificates.service.get_expiring_deployed_certificates(exclude=None)

Finds all certificates that are eligible for deployed expiring cert notifications. Returns the set of domain/port pairs at which each certificate was identified as in use (deployed).

Sample response:
defaultdict(<class ‘list’>,
{‘testowner2@example.com’: [(Certificate(name=certificate100),

defaultdict(<class ‘list’>, {‘localhost’: [65521, 65522, 65523]}))],

‘testowner3@example.com’: [(Certificate(name=certificate101),

defaultdict(<class ‘list’>, {‘localhost’: [65521, 65522, 65523]}))]})

Returns:

A dictionary with owner as key, and a list of certificates associated with domains/ports.

lemur.certificates.service.get_issued_cert_count_for_authority(authority)

Returns the count of certs issued by the specified authority.

Returns:

lemur.certificates.service.get_name_from_arn(arn)

Extract the certificate name from an arn.

Parameters:

arn – IAM SSL arn

Returns:

name of the certificate as uploaded to AWS

lemur.certificates.service.identify_and_persist_expiring_deployed_certificates(exclude_domains, exclude_owners, commit, timeout_seconds_per_network_call=1)

Finds all certificates expiring soon but are still being used for TLS at any domain with which they are associated. Identified ports will then be persisted on the certificate_associations row for the given cert/domain combo.

Note that this makes actual TLS network calls in order to establish the “deployed” part of this check.

lemur.certificates.service.import_certificate(**kwargs)

Uploads already minted certificates and pulls the required information into Lemur.

This is to be used for certificates that are created outside of Lemur but should still be tracked.

Internally this is used to bootstrap Lemur with external certificates, and used when certificates are ‘discovered’ through various discovery techniques. was still in aws.

Parameters:

kwargs

lemur.certificates.service.is_attached_to_endpoint(certificate_name, endpoint_name)

Find if given certificate is attached to the endpoint. Both, certificate and endpoint, are identified by name. This method talks to elb and finds the real time information. :param certificate_name: :param endpoint_name: :return: True if certificate is attached to the given endpoint, False otherwise

lemur.certificates.service.like_domain_query(term)
lemur.certificates.service.list_recent_valid_certs_issued_by_authority(authority_ids, days_since_issuance)

Find certificates issued by given authorities in last days_since_issuance number of days, that are still valid, not replaced, have auto-rotation ON.

Parameters:
  • authority_ids – list of authority ids

  • days_since_issuance – If not none, include certificates issued in only last days_since_issuance days

Returns:

List of certificates matching the criteria

lemur.certificates.service.mint(**kwargs)

Minting is slightly different for each authority. Support for multiple authorities is handled by individual plugins.

lemur.certificates.service.query_common_name(common_name, args)

Helper function that queries for not expired certificates by common name, owner and san. Pagination is supported.

Parameters:
  • common_name

  • args

Returns:

lemur.certificates.service.query_name(certificate_name, args)

Helper function that queries for a certificate by name

Parameters:

args

Returns:

lemur.certificates.service.reissue_certificate(certificate, notify=None, replace=None, user=None)

Reissue certificate with the same properties of the given certificate. :param certificate: :param notify: :param replace: :param user: :return:

lemur.certificates.service.remove_destination_association(certificate, destination, clean=True)
lemur.certificates.service.remove_from_destination(certificate, destination)

Remove the certificate from given destination if clean() is implemented :param certificate: :param destination: :return:

lemur.certificates.service.remove_source_association(certificate, source)
lemur.certificates.service.render(args)

Helper function that allows use to render our REST Api.

Parameters:

args

Returns:

lemur.certificates.service.revoke(certificate, reason)
lemur.certificates.service.send_certificate_expiration_metrics(expiry_window=None)

Iterate over each certificate and emit a metric for how many days until expiration.

Parameters:

expiry_window – defines the window for cert filter, ex: 90 will only return certs expiring in the next 90 days.

lemur.certificates.service.stats(**kwargs)

Helper that defines some useful statistics about certifications.

Parameters:

kwargs

Returns:

lemur.certificates.service.update(cert_id, **kwargs)

Updates a certificate :param cert_id: :return:

lemur.certificates.service.update_owner(cert, new_cert_data)

Modify owner for certificate. Removes roles and notifications associated with prior owner. :param cert: Certificate object to be updated :param new_cert_data: Dictionary including cert fields to be updated (owner, notifications, roles). These values are set in CertificateEditInputSchema and are generated for the new owner. :return:

lemur.certificates.service.update_switches(cert, notify_flag=None, rotation_flag=None)

Toggle notification and/or rotation values which are boolean :param notify_flag: new notify value :param rotation_flag: new rotation value :param cert: Certificate object to be updated :return:

lemur.certificates.service.upload(**kwargs)

Allows for pre-made certificates to be imported into Lemur.

lemur.certificates.service.validate_no_duplicate_destinations(destinations)

Validates destinations do not overlap accounts for the same plugin (for plugins that don’t allow duplicates).

verify Module

lemur.certificates.verify.crl_verify(cert, cert_path)

Attempts to verify a certificate using CRL.

Parameters:
  • cert

  • cert_path

Returns:

True if certificate is valid, False otherwise

Raises:

Exception – If certificate does not have CRL

lemur.certificates.verify.ocsp_verify(cert, cert_path, issuer_chain_path)

Attempts to verify a certificate via OCSP. OCSP is a more modern version of CRL in that it will query the OCSP URI in order to determine if the certificate has been revoked

Parameters:
  • cert

  • cert_path

  • issuer_chain_path

Return bool:

True if certificate is valid, False otherwise

lemur.certificates.verify.verify(cert_path, issuer_chain_path)

Verify a certificate using OCSP and CRL

Parameters:
  • cert_path

  • issuer_chain_path

Returns:

True if valid, False otherwise

lemur.certificates.verify.verify_string(cert_string, issuer_string)

Verify a certificate given only it’s string value

Parameters:
  • cert_string

  • issuer_string

Returns:

True if valid, False otherwise

views Module

class lemur.certificates.views.CertificateDeactivate

Bases: AuthenticatedResource

endpoint = 'deactivateCertificate'
mediatypes()
methods: t.ClassVar[t.Collection[str] | None] = {'PUT'}

The methods this view is registered for. Uses the same default (["GET", "HEAD", "OPTIONS"]) as route and add_url_rule by default.

put(certificate_id)
PUT /certificates/1/deactivate

deactivate a certificate (integration test only) Example request:

PUT /certificates/1/deactivate HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json;charset=UTF-8

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "id": 1
}
Request Headers:
Status Codes:
class lemur.certificates.views.CertificateExport

Bases: AuthenticatedResource

endpoint = 'exportCertificate'
mediatypes()
methods: t.ClassVar[t.Collection[str] | None] = {'POST'}

The methods this view is registered for. Uses the same default (["GET", "HEAD", "OPTIONS"]) as route and add_url_rule by default.

post(certificate_id, data=None)
POST /certificates/1/export

Export a certificate

Example request:

PUT /certificates/1/export HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json;charset=UTF-8

{
  "export": {
      "plugin": {
          "pluginOptions": [{
              "available": ["Java Key Store (JKS)"],
              "required": true,
              "type": "select",
              "name": "type",
              "helpMessage": "Choose the format you wish to export",
              "value": "Java Key Store (JKS)"
          }, {
              "required": false,
              "type": "str",
              "name": "passphrase",
              "validation": "^(?=.*[A-Za-z])(?=.*\d)(?=.*[$@$!%*#?&])[A-Za-z\d$@$!%*#?&]{8,}$",
              "helpMessage": "If no passphrase is given one will be generated for you, we highly recommend this. Minimum length is 8."
          }, {
              "required": false,
              "type": "str",
              "name": "alias",
              "helpMessage": "Enter the alias you wish to use for the keystore."
          }],
          "version": "unknown",
          "description": "Attempts to generate a JKS keystore or truststore",
          "title": "Java",
          "author": "Kevin Glisson",
          "type": "export",
          "slug": "java-export"
      }
  }
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "data": "base64encodedstring",
  "passphrase": "UAWOHW#&@_%!tnwmxh832025",
  "extension": "jks"
}
Request Headers:
Status Codes:
class lemur.certificates.views.CertificatePrivateKey

Bases: AuthenticatedResource

endpoint = 'privateKeyCertificates'
get(certificate_id)
GET /certificates/1/key

Retrieves the private key for a given certificate

Example request:

GET /certificates/1/key HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
   "key": "-----BEGIN ..."
}
Request Headers:
Status Codes:
mediatypes()
methods: t.ClassVar[t.Collection[str] | None] = {'GET'}

The methods this view is registered for. Uses the same default (["GET", "HEAD", "OPTIONS"]) as route and add_url_rule by default.

class lemur.certificates.views.CertificateRevoke

Bases: AuthenticatedResource

endpoint = 'revokeCertificate'
mediatypes()
methods: t.ClassVar[t.Collection[str] | None] = {'PUT'}

The methods this view is registered for. Uses the same default (["GET", "HEAD", "OPTIONS"]) as route and add_url_rule by default.

put(certificate_id, data=None)
PUT /certificates/1/revoke

Revoke a certificate. One can mention the reason of revocation using crlReason (optional) as per RFC 5280 section 5.3.1 The allowed values for crlReason can also be found in Lemur in constants.py/CRLReason Additional information can be captured using comments (optional).

Example request:

PUT /certificates/1/revoke HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json;charset=UTF-8

{
  "crlReason": "affiliationChanged",
  "comments": "Additional details if any"
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "id": 1
}
Request Headers:
Status Codes:
class lemur.certificates.views.CertificateUpdateOwner

Bases: AuthenticatedResource

endpoint = 'certificateUpdateOwner'
mediatypes()
methods: t.ClassVar[t.Collection[str] | None] = {'POST'}

The methods this view is registered for. Uses the same default (["GET", "HEAD", "OPTIONS"]) as route and add_url_rule by default.

post(certificate_id, data=None)
POST /certificates/1/update/owner

Update certificate owner

Example request:

POST /certificates/1/update/owner HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json;charset=UTF-8

{
   "owner": "joan@example.com"
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "status": null,
  "cn": "*.test.example.net",
  "chain": "",
  "authority": {
      "active": true,
      "owner": "secure@example.com",
      "id": 1,
      "description": "verisign test authority",
      "name": "verisign"
  },
  "owner": "joe@example.com",
  "serial": "82311058732025924142789179368889309156",
  "id": 2288,
  "issuer": "SymantecCorporation",
  "dateCreated": "2016-06-03T06:09:42.133769+00:00",
  "notBefore": "2016-06-03T00:00:00+00:00",
  "notAfter": "2018-01-12T23:59:59+00:00",
  "destinations": [],
  "bits": 2048,
  "body": "-----BEGIN CERTIFICATE-----...",
  "description": null,
  "deleted": null,
  "notify": false,
  "rotation": false,
  "notifications": [{
      "id": 1
  }]
  "signingAlgorithm": "sha256",
  "user": {
      "username": "jane",
      "active": true,
      "email": "jane@example.com",
      "id": 2
  },
  "active": true,
  "domains": [{
      "sensitive": false,
      "id": 1090,
      "name": "*.test.example.net"
  }],
  "replaces": [],
  "name": "WILDCARD.test.example.net-SymantecCorporation-20160603-20180112",
  "roles": [{
      "id": 464,
      "description": "This is a google group based role created by Lemur",
      "name": "joe@example.com"
  }],
  "rotation": true,
  "rotationPolicy": {"name": "default"},
  "san": null
}
Request Headers:
Status Codes:
class lemur.certificates.views.Certificates

Bases: AuthenticatedResource

delete(certificate_id, data=None)
DELETE /certificates/1

Delete a certificate

Example request:

DELETE /certificates/1 HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 204 OK
Request Headers:
Status Codes:
endpoint = 'certificateUpdateSwitches'
get(certificate_id)
GET /certificates/1

One certificate

Example request:

GET /certificates/1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "status": null,
  "cn": "*.test.example.net",
  "chain": "",
  "csr": "-----BEGIN CERTIFICATE REQUEST-----"
  "authority": {
      "active": true,
      "owner": "secure@example.com",
      "id": 1,
      "description": "verisign test authority",
      "name": "verisign"
  },
  "owner": "joe@example.com",
  "serial": "82311058732025924142789179368889309156",
  "id": 2288,
  "issuer": "SymantecCorporation",
  "dateCreated": "2016-06-03T06:09:42.133769+00:00",
  "notBefore": "2016-06-03T00:00:00+00:00",
  "notAfter": "2018-01-12T23:59:59+00:00",
  "destinations": [],
  "bits": 2048,
  "body": "-----BEGIN CERTIFICATE-----...",
  "description": null,
  "deleted": null,
  "notifications": [{
      "id": 1
  }],
  "signingAlgorithm": "sha256",
  "user": {
      "username": "jane",
      "active": true,
      "email": "jane@example.com",
      "id": 2
  },
  "active": true,
  "domains": [{
      "sensitive": false,
      "id": 1090,
      "name": "*.test.example.net"
  }],
  "rotation": true,
  "rotationPolicy": {"name": "default"},
  "replaces": [],
  "replaced": [],
  "name": "WILDCARD.test.example.net-SymantecCorporation-20160603-20180112",
  "roles": [{
      "id": 464,
      "description": "This is a google group based role created by Lemur",
      "name": "joe@example.com"
  }],
  "san": null
}
Request Headers:
Status Codes:
mediatypes()
methods: t.ClassVar[t.Collection[str] | None] = {'DELETE', 'GET', 'POST', 'PUT'}

The methods this view is registered for. Uses the same default (["GET", "HEAD", "OPTIONS"]) as route and add_url_rule by default.

post(certificate_id, data=None)
POST /certificates/1/update/switches

Update certificate boolean switches for notification or rotation

Example request:

POST /certificates/1/update/switches HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json;charset=UTF-8

{
   "notify": false,
   "rotation": false
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "status": null,
  "cn": "*.test.example.net",
  "chain": "",
  "authority": {
      "active": true,
      "owner": "secure@example.com",
      "id": 1,
      "description": "verisign test authority",
      "name": "verisign"
  },
  "owner": "joe@example.com",
  "serial": "82311058732025924142789179368889309156",
  "id": 2288,
  "issuer": "SymantecCorporation",
  "dateCreated": "2016-06-03T06:09:42.133769+00:00",
  "notBefore": "2016-06-03T00:00:00+00:00",
  "notAfter": "2018-01-12T23:59:59+00:00",
  "destinations": [],
  "bits": 2048,
  "body": "-----BEGIN CERTIFICATE-----...",
  "description": null,
  "deleted": null,
  "notify": false,
  "rotation": false,
  "notifications": [{
      "id": 1
  }]
  "signingAlgorithm": "sha256",
  "user": {
      "username": "jane",
      "active": true,
      "email": "jane@example.com",
      "id": 2
  },
  "active": true,
  "domains": [{
      "sensitive": false,
      "id": 1090,
      "name": "*.test.example.net"
  }],
  "replaces": [],
  "name": "WILDCARD.test.example.net-SymantecCorporation-20160603-20180112",
  "roles": [{
      "id": 464,
      "description": "This is a google group based role created by Lemur",
      "name": "joe@example.com"
  }],
  "rotation": true,
  "rotationPolicy": {"name": "default"},
  "san": null
}
Request Headers:
Status Codes:
put(certificate_id, data=None)
PUT /certificates/1

Update a certificate

Example request:

PUT /certificates/1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json;charset=UTF-8

{
   "owner": "jimbob@example.com",
   "active": false
   "notifications": [],
   "destinations": [],
   "replacements": []
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "status": null,
  "cn": "*.test.example.net",
  "chain": "",
  "authority": {
      "active": true,
      "owner": "secure@example.com",
      "id": 1,
      "description": "verisign test authority",
      "name": "verisign"
  },
  "owner": "joe@example.com",
  "serial": "82311058732025924142789179368889309156",
  "id": 2288,
  "issuer": "SymantecCorporation",
  "dateCreated": "2016-06-03T06:09:42.133769+00:00",
  "notBefore": "2016-06-03T00:00:00+00:00",
  "notAfter": "2018-01-12T23:59:59+00:00",
  "destinations": [],
  "bits": 2048,
  "body": "-----BEGIN CERTIFICATE-----...",
  "description": null,
  "deleted": null,
  "notifications": [{
      "id": 1
  }]
  "signingAlgorithm": "sha256",
  "user": {
      "username": "jane",
      "active": true,
      "email": "jane@example.com",
      "id": 2
  },
  "active": true,
  "domains": [{
      "sensitive": false,
      "id": 1090,
      "name": "*.test.example.net"
  }],
  "replaces": [],
  "name": "WILDCARD.test.example.net-SymantecCorporation-20160603-20180112",
  "roles": [{
      "id": 464,
      "description": "This is a google group based role created by Lemur",
      "name": "joe@example.com"
  }],
  "rotation": true,
  "rotationPolicy": {"name": "default"},
  "san": null
}
Request Headers:
Status Codes:
class lemur.certificates.views.CertificatesList

Bases: AuthenticatedResource

Defines the ‘certificates’ endpoint

endpoint = 'certificates'
get()
GET /certificates

The current list of certificates. This API supports additional params like

Pagination, sorting:

/certificates?count=10&page=1&short=true&sortBy=id&sortDir=desc

Filters, mentioned as url param filter=field;value

/certificates?filter=cn;lemur.test.com /certificates?filter=notify;true /certificates?filter=rotation;true /certificates?filter=name;lemur.test.cert /certificates?filter=issuer;Digicert

Request expired certs

/certificates?showExpired=1

Search by Serial Number

Decimal: /certificates?serial=218243997808053074560741989466015229225 Hex: /certificates?serial=0xA43043DAB7F6F8AE115E94854EEB6529 /certificates?serial=a4:30:43:da:b7:f6:f8:ae:11:5e:94:85:4e:eb:65:29

Example request:

GET /certificates?serial=82311058732025924142789179368889309156 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "items": [{
      "status": null,
      "cn": "*.test.example.net",
      "chain": "",
      "csr": "-----BEGIN CERTIFICATE REQUEST-----"
      "authority": {
          "active": true,
          "owner": "secure@example.com",
          "id": 1,
          "description": "verisign test authority",
          "name": "verisign"
      },
      "owner": "joe@example.com",
      "serial": "82311058732025924142789179368889309156",
      "id": 2288,
      "issuer": "SymantecCorporation",
      "dateCreated": "2016-06-03T06:09:42.133769+00:00",
      "notBefore": "2016-06-03T00:00:00+00:00",
      "notAfter": "2018-01-12T23:59:59+00:00",
      "destinations": [],
      "bits": 2048,
      "body": "-----BEGIN CERTIFICATE-----...",
      "description": null,
      "deleted": null,
      "notifications": [{
          "id": 1
      }],
      "signingAlgorithm": "sha256",
      "user": {
          "username": "jane",
          "active": true,
          "email": "jane@example.com",
          "id": 2
      },
      "active": true,
      "domains": [{
          "sensitive": false,
          "id": 1090,
          "name": "*.test.example.net"
      }],
      "replaces": [],
      "replaced": [],
      "name": "WILDCARD.test.example.net-SymantecCorporation-20160603-20180112",
      "roles": [{
          "id": 464,
          "description": "This is a google group based role created by Lemur",
          "name": "joe@example.com"
      }],
      "san": null
  }],
  "total": 1
}
Query Parameters:
  • sortBy – field to sort on

  • sortDir – asc or desc

  • page – int. default is 1

  • filter – key value pair format is k;v

  • count – count number. default is 10

Request Headers:
Status Codes:
mediatypes()
methods: t.ClassVar[t.Collection[str] | None] = {'GET', 'POST'}

The methods this view is registered for. Uses the same default (["GET", "HEAD", "OPTIONS"]) as route and add_url_rule by default.

post(data=None)
POST /certificates

Creates a new certificate

Example request:

POST /certificates HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json;charset=UTF-8

{
    "owner": "secure@example.net",
    "commonName": "test.example.net",
    "country": "US",
    "extensions": {
      "subAltNames": {
        "names": [
          {
            "nameType": "DNSName",
            "value": "*.test.example.net"
          },
          {
            "nameType": "DNSName",
            "value": "www.test.example.net"
          }
        ]
      }
    },
    "replacements": [{
      "id": 1
    }],
    "notify": true,
    "validityEnd": "2026-01-01T08:00:00.000Z",
    "authority": {
      "name": "verisign"
    },
    "organization": "Netflix, Inc.",
    "location": "Los Gatos",
    "state": "California",
    "validityStart": "2016-11-11T04:19:48.000Z",
    "organizationalUnit": "Operations"
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "status": null,
  "cn": "*.test.example.net",
  "chain": "",
  "authority": {
      "active": true,
      "owner": "secure@example.com",
      "id": 1,
      "description": "verisign test authority",
      "name": "verisign"
  },
  "owner": "joe@example.com",
  "serial": "82311058732025924142789179368889309156",
  "id": 2288,
  "issuer": "SymantecCorporation",
  "dateCreated": "2016-06-03T06:09:42.133769+00:00",
  "notBefore": "2016-06-03T00:00:00+00:00",
  "notAfter": "2018-01-12T23:59:59+00:00",
  "destinations": [],
  "bits": 2048,
  "body": "-----BEGIN CERTIFICATE-----...",
  "description": null,
  "deleted": null,
  "notifications": [{
      "id": 1
  }],
  "signingAlgorithm": "sha256",
  "user": {
      "username": "jane",
      "active": true,
      "email": "jane@example.com",
      "id": 2
  },
  "active": true,
  "domains": [{
      "sensitive": false,
      "id": 1090,
      "name": "*.test.example.net"
  }],
  "replaces": [{
      "id": 1
  }],
  "rotation": true,
  "rotationPolicy": {"name": "default"},
  "name": "WILDCARD.test.example.net-SymantecCorporation-20160603-20180112",
  "roles": [{
      "id": 464,
      "description": "This is a google group based role created by Lemur",
      "name": "joe@example.com"
  }],
  "san": null
}
Request Headers:
Status Codes:
class lemur.certificates.views.CertificatesListValid

Bases: AuthenticatedResource

Defines the ‘certificates/valid’ endpoint

endpoint = 'certificatesListValid'
get()
GET /certificates/valid/<query>

The current list of not-expired certificates for a given common name, and owner. The API offers optional pagination. One can send page number(>=1) and desired count per page. The returned data contains total number of certificates which can help in determining the last page. Pagination will not be offered if page or count info is not sent or if it is zero.

Example request:

GET /certificates/valid?filter=cn;*.test.example.net&owner=joe@example.com&page=1&count=20 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response (with single cert to be concise):

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "items": [{
      "status": null,
      "cn": "*.test.example.net",
      "chain": "",
      "csr": "-----BEGIN CERTIFICATE REQUEST-----"
      "authority": {
          "active": true,
          "owner": "secure@example.com",
          "id": 1,
          "description": "verisign test authority",
          "name": "verisign"
      },
      "owner": "joe@example.com",
      "serial": "82311058732025924142789179368889309156",
      "id": 2288,
      "issuer": "SymantecCorporation",
      "dateCreated": "2016-06-03T06:09:42.133769+00:00",
      "notBefore": "2016-06-03T00:00:00+00:00",
      "notAfter": "2018-01-12T23:59:59+00:00",
      "destinations": [],
      "bits": 2048,
      "body": "-----BEGIN CERTIFICATE-----...",
      "description": null,
      "deleted": null,
      "notifications": [{
          "id": 1
      }],
      "signingAlgorithm": "sha256",
      "user": {
          "username": "jane",
          "active": true,
          "email": "jane@example.com",
          "id": 2
      },
      "active": true,
      "domains": [{
          "sensitive": false,
          "id": 1090,
          "name": "*.test.example.net"
      }],
      "replaces": [],
      "replaced": [],
      "name": "WILDCARD.test.example.net-SymantecCorporation-20160603-20180112",
      "roles": [{
          "id": 464,
          "description": "This is a google group based role created by Lemur",
          "name": "joe@example.com"
      }],
      "san": null
  }],
  "total": 1
}
Request Headers:
Status Codes:
mediatypes()
methods: t.ClassVar[t.Collection[str] | None] = {'GET'}

The methods this view is registered for. Uses the same default (["GET", "HEAD", "OPTIONS"]) as route and add_url_rule by default.

class lemur.certificates.views.CertificatesNameQuery

Bases: AuthenticatedResource

Defines the ‘certificates/name’ endpoint

endpoint = 'certificatesNameQuery'
get(certificate_name)
GET /certificates/name/<query>

The current list of certificates

Example request:

GET /certificates/name/WILDCARD.test.example.net-SymantecCorporation-20160603-20180112 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "items": [{
      "status": null,
      "cn": "*.test.example.net",
      "chain": "",
      "csr": "-----BEGIN CERTIFICATE REQUEST-----"
      "authority": {
          "active": true,
          "owner": "secure@example.com",
          "id": 1,
          "description": "verisign test authority",
          "name": "verisign"
      },
      "owner": "joe@example.com",
      "serial": "82311058732025924142789179368889309156",
      "id": 2288,
      "issuer": "SymantecCorporation",
      "dateCreated": "2016-06-03T06:09:42.133769+00:00",
      "notBefore": "2016-06-03T00:00:00+00:00",
      "notAfter": "2018-01-12T23:59:59+00:00",
      "destinations": [],
      "bits": 2048,
      "body": "-----BEGIN CERTIFICATE-----...",
      "description": null,
      "deleted": null,
      "notifications": [{
          "id": 1
      }],
      "signingAlgorithm": "sha256",
      "user": {
          "username": "jane",
          "active": true,
          "email": "jane@example.com",
          "id": 2
      },
      "active": true,
      "domains": [{
          "sensitive": false,
          "id": 1090,
          "name": "*.test.example.net"
      }],
      "replaces": [],
      "replaced": [],
      "name": "WILDCARD.test.example.net-SymantecCorporation-20160603-20180112",
      "roles": [{
          "id": 464,
          "description": "This is a google group based role created by Lemur",
          "name": "joe@example.com"
      }],
      "san": null
  }],
  "total": 1
}
Query Parameters:
  • sortBy – field to sort on

  • sortDir – asc or desc

  • page – int. default is 1

  • filter – key value pair format is k;v

  • count – count number. default is 10

Request Headers:
Status Codes:
mediatypes()
methods: t.ClassVar[t.Collection[str] | None] = {'GET'}

The methods this view is registered for. Uses the same default (["GET", "HEAD", "OPTIONS"]) as route and add_url_rule by default.

class lemur.certificates.views.CertificatesReplacementsList

Bases: AuthenticatedResource

endpoint = 'replacements'
get(certificate_id)
GET /certificates/1/replacements

One certificate

Example request:

GET /certificates/1/replacements HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "items": [{
      "status": null,
      "cn": "*.test.example.net",
      "chain": "",
      "csr": "-----BEGIN CERTIFICATE REQUEST-----",
      "authority": {
          "active": true,
          "owner": "secure@example.com",
          "id": 1,
          "description": "verisign test authority",
          "name": "verisign"
      },
      "owner": "joe@example.com",
      "serial": "82311058732025924142789179368889309156",
      "id": 2288,
      "issuer": "SymantecCorporation",
      "dateCreated": "2016-06-03T06:09:42.133769+00:00",
      "notBefore": "2016-06-03T00:00:00+00:00",
      "notAfter": "2018-01-12T23:59:59+00:00",
      "destinations": [],
      "bits": 2048,
      "body": "-----BEGIN CERTIFICATE-----...",
      "description": null,
      "deleted": null,
      "notifications": [{
          "id": 1
      }]
      "signingAlgorithm": "sha256",
      "user": {
          "username": "jane",
          "active": true,
          "email": "jane@example.com",
          "id": 2
      },
      "active": true,
      "domains": [{
          "sensitive": false,
          "id": 1090,
          "name": "*.test.example.net"
      }],
      "replaces": [],
      "replaced": [],
      "rotation": true,
      "rotationPolicy": {"name": "default"},
      "name": "WILDCARD.test.example.net-SymantecCorporation-20160603-20180112",
      "roles": [{
          "id": 464,
          "description": "This is a google group based role created by Lemur",
          "name": "joe@example.com"
      }],
      "san": null
  }],
  "total": 1
}
Request Headers:
Status Codes:
mediatypes()
methods: t.ClassVar[t.Collection[str] | None] = {'GET'}

The methods this view is registered for. Uses the same default (["GET", "HEAD", "OPTIONS"]) as route and add_url_rule by default.

class lemur.certificates.views.CertificatesStats

Bases: AuthenticatedResource

Defines the ‘certificates’ stats endpoint

endpoint = 'certificateStats'
get()
mediatypes()
methods: t.ClassVar[t.Collection[str] | None] = {'GET'}

The methods this view is registered for. Uses the same default (["GET", "HEAD", "OPTIONS"]) as route and add_url_rule by default.

class lemur.certificates.views.CertificatesUpload

Bases: AuthenticatedResource

Defines the ‘certificates’ upload endpoint

endpoint = 'certificateUpload'
mediatypes()
methods: t.ClassVar[t.Collection[str] | None] = {'POST'}

The methods this view is registered for. Uses the same default (["GET", "HEAD", "OPTIONS"]) as route and add_url_rule by default.

post(data=None)
POST /certificates/upload

Upload a certificate

Example request:

POST /certificates/upload HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json;charset=UTF-8

{
   "owner": "joe@example.com",
   "body": "-----BEGIN CERTIFICATE-----...",
   "chain": "-----BEGIN CERTIFICATE-----...",
   "privateKey": "-----BEGIN RSA PRIVATE KEY-----..."
   "csr": "-----BEGIN CERTIFICATE REQUEST-----..."
   "destinations": [],
   "notifications": [],
   "replacements": [],
   "roles": [],
   "notify": true,
   "name": "cert1"
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "status": null,
  "cn": "*.test.example.net",
  "chain": "",
  "authority": {
      "active": true,
      "owner": "secure@example.com",
      "id": 1,
      "description": "verisign test authority",
      "name": "verisign"
  },
  "owner": "joe@example.com",
  "serial": "82311058732025924142789179368889309156",
  "id": 2288,
  "issuer": "SymantecCorporation",
  "dateCreated": "2016-06-03T06:09:42.133769+00:00",
  "notBefore": "2016-06-03T00:00:00+00:00",
  "notAfter": "2018-01-12T23:59:59+00:00",
  "destinations": [],
  "bits": 2048,
  "body": "-----BEGIN CERTIFICATE-----...",
  "description": null,
  "deleted": null,
  "notifications": [{
      "id": 1
  }],
  "signingAlgorithm": "sha256",
  "user": {
      "username": "jane",
      "active": true,
      "email": "jane@example.com",
      "id": 2
  },
  "active": true,
  "domains": [{
      "sensitive": false,
      "id": 1090,
      "name": "*.test.example.net"
  }],
  "replaces": [],
  "rotation": true,
  "rotationPolicy": {"name": "default"},
  "name": "WILDCARD.test.example.net-SymantecCorporation-20160603-20180112",
  "roles": [{
      "id": 464,
      "description": "This is a google group based role created by Lemur",
      "name": "joe@example.com"
  }],
  "san": null
}
Request Headers:
Status Codes:
class lemur.certificates.views.NotificationCertificatesList

Bases: AuthenticatedResource

Defines the ‘certificates’ endpoint

endpoint = 'notificationCertificates'
get(notification_id)
GET /notifications/1/certificates

The current list of certificates for a given notification

Example request:

GET /notifications/1/certificates HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{
  "items": [{
      "status": null,
      "cn": "*.test.example.net",
      "chain": "",
      "csr": "-----BEGIN CERTIFICATE REQUEST-----"
      "authority": {
          "active": true,
          "owner": "secure@example.com",
          "id": 1,
          "description": "verisign test authority",
          "name": "verisign"
      },
      "owner": "joe@example.com",
      "serial": "82311058732025924142789179368889309156",
      "id": 2288,
      "issuer": "SymantecCorporation",
      "dateCreated": "2016-06-03T06:09:42.133769+00:00",
      "notBefore": "2016-06-03T00:00:00+00:00",
      "notAfter": "2018-01-12T23:59:59+00:00",
      "destinations": [],
      "bits": 2048,
      "body": "-----BEGIN CERTIFICATE-----...",
      "description": null,
      "deleted": null,
      "notifications": [{
          "id": 1
      }],
      "signingAlgorithm": "sha256",
      "user": {
          "username": "jane",
          "active": true,
          "email": "jane@example.com",
          "id": 2
      },
      "active": true,
      "domains": [{
          "sensitive": false,
          "id": 1090,
          "name": "*.test.example.net"
      }],
      "replaces": [],
      "replaced": [],
      "rotation": true,
      "rotationPolicy": {"name": "default"},
      "name": "WILDCARD.test.example.net-SymantecCorporation-20160603-20180112",
      "roles": [{
          "id": 464,
          "description": "This is a google group based role created by Lemur",
          "name": "joe@example.com"
      }],
      "san": null
  }],
  "total": 1
}
Query Parameters:
  • sortBy – field to sort on

  • sortDir – asc or desc

  • page – int default is 1

  • filter – key value pair format is k;v

  • count – count number default is 10

Request Headers:
Status Codes:
mediatypes()
methods: t.ClassVar[t.Collection[str] | None] = {'GET'}

The methods this view is registered for. Uses the same default (["GET", "HEAD", "OPTIONS"]) as route and add_url_rule by default.