The Ruby client for the official Digicert API.
Add this line to your application's Gemfile:
gem "digicert"And then execute:
bundle installOr install it yourself as:
gem install digicertOnce you have your API key then you can configure it by adding an initializer with the following code
Digicert.configure do |config|
config.api_key = "SECRET_DEV_API_KEY"
# Default response type is `object`, but you can configure it if
# necessary, and all the further response will be return as config
# supported options are `object` and `hash`.
#
# config.response_type = :object
endOr
Digicert.configuration.api_key = "SECRET_DEV_API_KEY"Container is an Operational Division used to model your organizational structure. The features of the container you create are determined by its Container Template.
Use this interface to retrieve a list of existing containers.
Note: This is an undocumented endpoint of the DigiCert Services API.
Digicert::Container.allUse this interface to create new container, and this interface also
expects us to provide parent_container along with the others
attributes as container_id.
Digicert::Container.create(
container_id: 123_456_789,
template_id: 5,
name: "History Department",
description: "History, Civ, Ancient Languages",
user: {
first_name: "Awesome",
last_name: "User",
email: "[email protected]",
username: "[email protected]",
access_roles: [{ id: 1 }],
},
)Information about a specific container can be retrieved through this interface, including its name, description, template, and parent container id.
Digicert::Container.fetch(container_id)Container Templates define a set of features that are available to a container.
Use this interface to retrieve a list of the templates that are available to use to create child containers.
Digicert::ContainerTemplate.all(container_id)Use this interface to retrieve information about a specific container template, including which user access roles are available under this template.
Digicert::ContainerTemplate.fetch(
template_id: template_id, container_id: container_id,
)Use this interface to create a new organization. The organization information will be used by DigiCert for validation and may appear on certificates.
# Create a new organization
# Please pay close attension bellow
# on building the organization_attributes
#
Digicert::Organization.create(organization_attributes)
# Organization attributes hash
#
organization_attributes = {
name: "digicert, inc.",
address: "333 s 520 w",
zip: 84042,
city: "lindon",
state: "utah",
country: "us",
telephone: 8015551212,
container: { id: 17 },
organization_contact: {
first_name: "Some",
last_name: "Guy",
email: "[email protected]",
telephone: 8015551212,
},
# Optional attributes
assumed_name: "DigiCert",
address2: "Suite 500",
}Use this interface to view information about an organization.
Digicert::Organization.fetch(organization_id)Use this interface to retrieve a list of organizations.
Digicert::Organization.allUse this interface to add a domain for an organization in a container. You must specify at least one validation type for the domain.
# Create a new domain in an organization
# Please pay close attension in building the attibutes hash
#
Digicert::Domain.create(domain_attributes)
# Domain attributes hash
#
domain_attributes = {
name: "digicert.com",
organization: { id: 117483 },
validations: [
{
type: "ev",
user: { id: 12 }
},
],
dcv: { method: "email" },
}Use this interface to activate a domain that was previously deactivated.
domain = Digicert::Domain.find(domain_id)
domain.activateUse this interface to deactivate a domain.
domain = Digicert::Domain.find(domain_id)
domain.deactivateUse this interface to view a domain, This interface also allows you to pass an
additional hash to specify if you want to retrieve additional data with the
response.
Digicert::Domain.fetch(domain_id, include_dcv: true)Use this interface to retrieve a list of domains. This interface also supports
an additional filter_params hash, which can be used to filter the list we want
the interface to return.
Digicert::Domain.all(filter_params_hash)Recently DigiCert improved the certificate issuance process to allow for immediate certificate issuance. It does not require us to change anything on our API calls but now the response will be different based on your DigiCert account settings.
If you have everything setup in place and any order is eligible for immediate issuance then the certificate will be included with the response. Please check the certificate download spec for inspiration.
Use this interface to retrieve a list of available products for an account.
Digicert::Product.allUse this interface to retrieve a full set of details for a product.
Digicert::Product.fetch(name_id)This interface will allow us to generate the CSR content on the fly, it will return the content that we can use for order creation.
Digicert::CSRGenerator.generate(
common_name: "example.com",
san_names: ["example.com", "www.example.com"],
rsa_key: File.read("your_rsa_key_file_path"),
organization: Digicert::Organization.all.first,
)Use this interface to create a new order, this expect two arguments one is
name_id for the order and another one is the attributes hash.
order = Digicert::Order.create(
name_id, order_attributes_hash,
)
# Pay close attension building the order attributes
# hash, it requries to format the data in a specific
# format and once that is satisfied only then it will
# perfrom the API operation otherwise it will raise
# invalid argument errors.
#
order_attributes = {
certificate: {
common_name: "digicert.com",
csr: "------ [CSR HERE] ------",
signature_hash: "sha256",
organization_units: ["Developer Operations"],
server_platform: { id: 45 },
profile_option: "some_ssl_profile",
},
organization: { id: 117483 },
validity_years: 3,
custom_expiration_date: "2017-05-18",
comments: "Comments for the the approver",
disable_renewal_notifications: false,
renewal_of_order_id: 314152,
payment_method: "balance",
}The supported value for name_id are ssl_plus, ssl_wildcard, ssl_ev_plus,
client_premium, email_security_plus and digital_signature_plus. Please
check the Digicert documentation for more details on those.
If you want to create a new order by yourself by following each of the specific class then please check out the interfaces specified bellow.
Use this interface to order a SSL Plus Certificate.
Digicert::SSLCertificate::SSLPlus.create(
certificate: {
common_name: "digicert.com",
csr: "------ [CSR HERE] ------",
signature_hash: "sha256",
organization_units: ["Developer Operations"],
server_platform: { id: 45 },
profile_option: "some_ssl_profile",
},
organization: { id: 117483 },
validity_years: 3,
custom_expiration_date: "2017-05-18",
comments: "Comments for the the approver",
disable_renewal_notifications: false,
renewal_of_order_id: 314152,
payment_method: "balance",
)Use this interface to order a SSL Wildcard Certificate.
Digicert::SSLCertificate::SSLWildcard.create(
certificate: {
common_name: "digicert.com",
csr: "------ [CSR HERE] ------",
signature_hash: "sha256",
organization_units: ["Developer Operations"],
server_platform: { id: 45 },
profile_option: "some_ssl_profile",
},
organization: { id: 117483 },
validity_years: 3,
custom_expiration_date: "2017-05-18",
comments: "Comments for the the approver",
disable_renewal_notifications: false,
renewal_of_order_id: 314152,
)Use this interface to order a SSL EV Plus Certificate.
Digicert::SSLCertificate::SSLEVPlus.create(
certificate: {
common_name: "digicert.com",
csr: "------ [CSR HERE] ------",
signature_hash: "sha256",
organization_units: ["Developer Operations"],
server_platform: { id: 45 },
profile_option: "some_ssl_profile",
},
organization: { id: 117483 },
validity_years: 3,
custom_expiration_date: "2017-05-18",
comments: "Comments for the the approver",
disable_renewal_notifications: false,
renewal_of_order_id: 314152,
)Use this interface to order a Client Premium Certificate.
Digicert::ClientCertificate::Premium.create(
certificate: {
common_name: "Full Name",
emails: ["[email protected]", "[email protected]"],
csr: "------ [CSR HERE] ------",
signature_hash: "sha256",
organization_units: ["Developer Operations"],
server_platform: { id: 45 },
profile_option: "some_ssl_profile",
},
organization: { id: 117483 },
validity_years: 3,
custom_expiration_date: "2017-05-18",
comments: "Comments for the the approver",
disable_renewal_notifications: false,
renewal_of_order_id: 314152,
)Use this interface to order a Private Client Premium Certificate.
Digicert::ClientCertificate::PrivatePremium.create(
certificate: {
organization_units: ["Developer Operations"],
csr: "------ [CSR HERE] ------",
emails: ["[email protected]"],
common_name: "Common Name",
signature_hash: "sha256",
},
organization: { id: "12345" },
validity_years: 3,
auto_renew: nil,
container: { id: "654321" },
payment_method: "balance",
)Use this interface to order a Email Security Plus Certificate
Digicert::ClientCertificate::EmailSecurityPlus.create(
certificate: {
common_name: "Full Name",
emails: ["[email protected]", "[email protected]"],
signature_hash: "sha256",
organization_units: ["Developer Operations"],
server_platform: { id: 45 },
profile_option: "some_ssl_profile",
},
organization: { id: 117483 },
validity_years: 3,
auto_renew: 10,
renewal_of_order_id: 314152,
)Use this interface to order a Client Digital Signature Plus
Digicert::Order::DigitalSignaturePlus.create(
certificate: {
common_name: "Full Name",
emails: ["[email protected]", "[email protected]"],
csr: "-----BEGIN CERTIFICATE REQUEST----- ...",
signature_hash: "sha256",
},
organization: { id: 117483 },
validity_years: 3,
auto_renew: 10,
renewal_of_order_id: 314152,
)Use this interface to retrieve a list of certificate requests.
Digicert::CertificateRequest.allUse this interface to retrieve the details for a certificate request.
Digicert::CertificateRequest.fetch(request_id)Use this interface to update the status of a previously submitted certificate request.
Digicert::CertificateRequest.update(
request_id, status: "approved", processor_comment: "Your domain is approved",
)Use this interface to retrieve a certificate order and the response includes all
the order attributes along with a certificate in it.
Digicert::Order.fetch(order_id)Use this interface to retrieve a list of all certificate orders.
Digicert::Order.allThis interface also supports query params like limit, offset, sort and
filters. We can use those to retrieve more precised orders.
Digicert::Order.all(
limit: 20,
offset: 0,
sort: 'date_created',
filters: {
status: "approved",
common_name: "ribosetest.com"
}
)There is also another interface .filter, which is basically an alias around
the .all interface but it passes each of the argument as a filters attributes
Digicert::Order.filter(status: "approved", common_name: "ribosetest.com")
# Similar functionality with all interface
#
Digicert::Order.all(
filters: { status: "approved", common_name: "ribosetest.com" }
)Use this interface to view the status of all emails that require validation on a client certificate order.
Digicert::EmailValidation.all(order_id: order_id)
# If you prefer then there is an alternative alias method
# on the order class, you can invoke that on any of its
# instances. Usages
#
order = Digicert::Order.find(order_id)
order.email_validationsUse this interface to verify control of an email address, using an email address/token pair.
Digicert::EmailValidation.valid?(token: token, email: email)
# => true or falseUse this interface to reissue a certificate order. A reissue replaces the existing certificate with a new one that has different information such as common name, CSR, etc. The simplest interface to reissue an update an existing order is
order = Digicert::Order.find(order_id)
order.reissue
# Alternative and prefereed in most case
Digicert::OrderReissuer.create(order_id: order_id)And if there are some updated information like csr, common_name or etc then
you can use the same interface but pass the :certificate option. Please
remember if any required fields are missing then it will use the data that
already exists for that order.
Digicert::OrderReissuer.create(
order: order_id,
common_name: certificate_common_name,
dns_names: [certificate_dns_name],
csr: certificate_csr,
signature_hash: certificate_signature_hash,
server_platform: { id: certificate_server_platform_id },
)Use this interface to request a duplicate certificate for an order. A duplicate shares the expiration date as the existing certificate and is identical with the exception of the CSR and a possible change in the server platform and signature hash. The common name and sans need to be the same as the original order.
Digicert::OrderDuplicator.create(
order: order_id,
common_name: certificate_common_name,
dns_names: [certificate_dns_name],
csr: certificate_csr,
signature_hash: certificate_signature_hash,
server_platform: { id: certificate_server_platform_id },
)As of now, the Digicert API, does not have an easier way to find a duplicate
certificate, as the certificate duplication returns existing order_id with a
request node which only has an id.
So to find out a duplicate certificate, we need to retrieve the details for that
specific request and from that response retrieve the date_created for the
duplicate certificate and then use that date_created to find out the correct
certificate from the duplications of that specific order.
This requires lots of work, so this following interface will do all of its underlying tasks, and all we need to do is pass the requests id that we will have form the certificate duplication.
# Duplicate an existing certificate order
#
order = Digicert::Order.find(order_id)
duplicate_order = order.duplicate
# Use the request id to find out the certificate
#
request_id = duplicate_order.requests.first.id
Digicert::DuplicateCertificateFinder.find_by(request_id: request_id)Use this interface to view all duplicate certificates for an order.
Digicert::DuplicateCertificate.all(order_id: order_id)
# Alternative interface for duplicate certificates
order = Digicert::Order.find(order_id)
order.duplicate_certificatesUse this interface to update the status of an order. Currently this endpoint only allows updating the status to 'CANCELED'
order = Digicert::Order.find(order_id)
order.cancel(note: "Cancellation note")
# Or use the actual interface for more control
Digicert::OrderCancellation.create(
order_id: order_id, status: "CANCELED", note: "your_note", send_emails: true,
)Use this interface to retrieve the number of orders that have certificates expiring within 90, 60, and 30 days. The number of orders that have already expired certificates within the last 7 days is also returned.
Digicert::ExpiringOrder.all(container_id: container_id)This request will return an SSL Certificate file from an order. By default, it uses the platform specified by the order.
# Fetch the certficate details that includes a http status code
# and the file content in the `#body`, so you can choose if you
# want to write it to your filesystem or directly upload it to
# your host, and the contents it returns is `zip` archieve.
#
certificate = Digicert::CertificateDownloader.fetch(certificate_id, **attributes)
# write to content to somewhere in your filesystem.
#
File.write("path_to_file_system/certificate.zip", certificate.body)
# Alaternative to fetch it through certificate instance
#
certificate = Digicert::Certificate.find(certificate_id)
certificate_content_object = certificate.downloadAdditionally, if you want the gem to handle the file writing then it also
provides another helper interface fetch_to_path, and that will fetch the file
content and write the content to supplied path.
Digicert::CertificateDownloader.fetch_to_path(
certificate_id,
ext: "zip",
path: File.expand_path("./file/download/path"),
**other_attributes_hash_like_platform_or_format,
)
# Alternative through a certificate instance
#
certificate = Digicert::Certificate.find(certificate_id)
certificate.download_to_path(path: "file/path", ext: "zip", format: "zip")This interface will return an SSL Certificate file from an order. The certificate
will be return in the format you specify, but one thing to remember the
certificate will be archived as zip along with the instructions, so you need
to write that as zip archive.
Digicert::CertificateDownloader.fetch_by_format(
certificate_id, format: format,
)
# Alternative using the certificate instance
#
certificate = Digicert::Certificate.find(certificate_id)
certificate_content_object = certificate.download(format: format)This interface will return an SSL Certificate file from an order using the platform specified.
certificate = Digicert::CertificateDownloader.fetch_by_platform(
certificate_id, platform: "apache",
)
# Alternative using the certificate instance
#
certificate = Digicert::Certificate.find(certificate_id)
certificate_content_object = certificate.download(platform: "apache")This interface will fetch a SSL Certificate and extract all of its subsidiary
certificates content and return as a hash with certificate, root_certificate
and intermediate_certificate keys.
Digicert::CertificateDownloader.fetch_content(certificate_id)
# Alternative using certificate instance
#
certificate = Digicert::Certificate.find(certificate_id)
certificate.download_contentThis interface will revoke a previously issued SSL Certificate.
Digicert::Certificate.revoke(certificate_id, comments: "Your comment")We are following Sandi Metz's Rules for this gem, you can read the description of the rules here All new code should follow these rules. If you make changes in a pre-existing file that violates these rules you should fix the violations as part of your contribution.
Clone the repository.
git clone https://github.com/riboseinc/digicertSetup your environment.
bin/setupRun the test suite
bin/rspecThe API Play Box provides an interactive console so we can easily test out the actual API interaction. But before moving forward let's configure the your key.
Setup the client configuration.
cp .sample.pryrc .pryrc
vim .pryrcStart the console.
bin/consoleStart playing with it.
Digicert::Product.allFirst, thank you for contributing! We love pull requests from everyone. By participating in this project, you hereby grant Ribose Inc. the right to grant or transfer an unlimited number of non exclusive licenses or sub-licenses to third parties, under the copyright covering the contribution to use the contribution by all means.
Here are a few technical guidelines to follow:
- Open an issue to discuss a new feature.
- Write tests to support your new feature.
- Make sure the entire test suite passes locally and on CI.
- Open a Pull Request.
- Squash your commits after receiving feedback.
- Party!
This gem is developed, maintained and funded by Ribose Inc.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent