Skip to main content

certificates

Creates, updates, deletes, gets or lists a certificates resource.

Overview​

Namecertificates
TypeResource
Idaws.iot.certificates

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
ca_certificate_idstringThe certificate ID of the CA certificate used to sign this certificate. (pattern: <code>(0x)?[a-fA-F0-9]+</code>)
certificate_arnstringThe ARN of the certificate.
certificate_idstringThe ID of the certificate. (pattern: <code>(0x)?[a-fA-F0-9]+</code>)
certificate_modestringThe mode of the certificate. DEFAULT: A certificate in DEFAULT mode is either generated by Amazon Web Services IoT Core or registered with an issuer certificate authority (CA) in DEFAULT mode. Devices with certificates in DEFAULT mode aren't required to send the Server Name Indication (SNI) extension when connecting to Amazon Web Services IoT Core. However, to use features such as custom domains and VPC endpoints, we recommend that you use the SNI extension when connecting to Amazon Web Services IoT Core. SNI_ONLY: A certificate in SNI_ONLY mode is registered without an issuer CA. Devices with certificates in SNI_ONLY mode must send the SNI extension when connecting to Amazon Web Services IoT Core. For more information about the value for SNI extension, see Transport security in IoT. (DEFAULT, SNI_ONLY)
certificate_pemstringThe certificate data, in PEM format. (pattern: <code>[\s\S]*</code>)
creation_datestring (date-time)The date and time the certificate was created.
customer_versionintegerThe customer version of the certificate.
generation_idstringThe generation ID of the certificate.
last_modified_datestring (date-time)The date and time the certificate was last modified.
owned_bystringThe ID of the Amazon Web Services account that owns the certificate. (pattern: <code>[0-9]+</code>)
previous_owned_bystringThe ID of the Amazon Web Services account of the previous owner of the certificate. (pattern: <code>[0-9]+</code>)
statusstringThe status of the certificate. (ACTIVE, INACTIVE, REVOKED, PENDING_TRANSFER, REGISTER_INACTIVE, PENDING_ACTIVATION)
transfer_dataobjectThe transfer data.
validityobjectWhen the certificate is valid.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_certificateselectcertificate_id, regionGets information about the specified certificate. Requires permission to access the DescribeCertificate action.
list_certificatesselectregionpageSize, marker, isAscendingOrderLists the certificates registered in your Amazon Web Services account. The results are paginated with a default page size of 25. You can use the returned marker to retrieve additional results. Requires permission to access the ListCertificates action.
create_certificate_from_csrinsertregion, certificateSigningRequestsetAsActiveCreates an X.509 certificate using the specified certificate signing request. Requires permission to access the CreateCertificateFromCsr action. The CSR must include a public key that is either an RSA key with a length of at least 2048 bits or an ECC key from NIST P-256, NIST P-384, or NIST P-521 curves. For supported certificates, consult Certificate signing algorithms supported by IoT. Reusing the same certificate signing request (CSR) results in a distinct certificate. You can create multiple certificates in a batch by creating a directory, copying multiple .csr files into that directory, and then specifying that directory on the command line. The following commands show how to create a batch of certificates given a batch of CSRs. In the following commands, we assume that a set of CSRs are located inside of the directory my-csr-directory: On Linux and OS X, the command is: $ ls my-csr-directory/ | xargs -I {} aws iot create-certificate-from-csr --certificate-signing-request file:​//my-csr-directory/{} This command lists all of the CSRs in my-csr-directory and pipes each CSR file name to the aws iot create-certificate-from-csr Amazon Web Services CLI command to create a certificate for the corresponding CSR. You can also run the aws iot create-certificate-from-csr part of the command in parallel to speed up the certificate creation process: $ ls my-csr-directory/ | xargs -P 10 -I {} aws iot create-certificate-from-csr --certificate-signing-request file:​//my-csr-directory/{} On Windows PowerShell, the command to create certificates for all CSRs in my-csr-directory is: > ls -Name my-csr-directory | %{aws iot create-certificate-from-csr --certificate-signing-request file:​//my-csr-directory/$_} On a Windows command prompt, the command to create certificates for all CSRs in my-csr-directory is: > forfiles /p my-csr-directory /c "cmd /c aws iot create-certificate-from-csr --certificate-signing-request file:​//@path"
register_certificateinsertregion, certificatePemsetAsActiveRegisters a device certificate with IoT in the same certificate mode as the signing CA. If you have more than one CA certificate that has the same subject field, you must specify the CA certificate that was used to sign the device certificate being registered. Requires permission to access the RegisterCertificate action.
create_keys_and_certificateinsertregionsetAsActiveCreates a 2048-bit RSA key pair and issues an X.509 certificate using the issued public key. You can also call CreateKeysAndCertificate over MQTT from a device, for more information, see Provisioning MQTT API. Note This is the only time IoT issues the private key for this certificate, so it is important to keep it in a secure location. Requires permission to access the CreateKeysAndCertificate action.
update_certificateupdatecertificate_id, newStatus, regionUpdates the status of the specified certificate. This operation is idempotent. Requires permission to access the UpdateCertificate action. Certificates must be in the ACTIVE state to authenticate devices that use a certificate to connect to IoT. Within a few minutes of updating a certificate from the ACTIVE state to any other state, IoT disconnects all devices that used that certificate to connect. Devices cannot use a certificate that is not in the ACTIVE state to reconnect.
delete_certificatedeletecertificate_id, regionforceDeleteDeletes the specified certificate. A certificate cannot be deleted if it has a policy or IoT thing attached to it or if its status is set to ACTIVE. To delete a certificate, first use the DetachPolicy action to detach all policies. Next, use the UpdateCertificate action to set the certificate to the INACTIVE status. Requires permission to access the DeleteCertificate action.
accept_certificate_transferexeccertificate_id, regionsetAsActiveAccepts a pending certificate transfer. The default state of the certificate is INACTIVE. To check for pending certificate transfers, call ListCertificates to enumerate your certificates. Requires permission to access the AcceptCertificateTransfer action.
cancel_certificate_transferexeccertificate_id, regionCancels a pending transfer for the specified certificate. Note Only the transfer source account can use this operation to cancel a transfer. (Transfer destinations can use RejectCertificateTransfer instead.) After transfer, IoT returns the certificate to the source account in the INACTIVE state. After the destination account has accepted the transfer, the transfer cannot be cancelled. After a certificate transfer is cancelled, the status of the certificate changes from PENDING_TRANSFER to INACTIVE. Requires permission to access the CancelCertificateTransfer action.
register_certificate_without_caexecregion, certificatePemRegister a certificate that does not have a certificate authority (CA). For supported certificates, consult Certificate signing algorithms supported by IoT.
reject_certificate_transferexeccertificate_id, regionRejects a pending certificate transfer. After IoT rejects a certificate transfer, the certificate status changes from PENDING_TRANSFER to INACTIVE. To check for pending certificate transfers, call ListCertificates to enumerate your certificates. This operation can only be called by the transfer destination. After it is called, the certificate will be returned to the source's account in the INACTIVE state. Requires permission to access the RejectCertificateTransfer action.
transfer_certificateexeccertificate_id, targetAwsAccount, regionTransfers the specified certificate to the specified Amazon Web Services account. Requires permission to access the TransferCertificate action. You can cancel the transfer until it is accepted by the recipient. No notification is sent to the transfer destination's account. The caller is responsible for notifying the transfer target. The certificate being transferred must not be in the ACTIVE state. You can use the UpdateCertificate action to deactivate it. The certificate must not have any policies attached to it. You can use the DetachPolicy action to detach them. Customer managed key behavior: When you use a customer managed key to encrypt your data and then transfer the certificate to a customer in a different account using the TransferCertificate operation, the certificates will no longer be encrypted by their customer managed key configuration. During the transfer process, certificates are encrypted using Amazon Web Services IoT Core owned keys. While a certificate is in the PENDING_TRANSFER state, it's always protected by Amazon Web Services IoT Core owned keys, regardless of the customer managed key configuration of either the source or destination account. Once the transfer is completed through AcceptCertificateTransfer, RejectCertificateTransfer, or CancelCertificateTransfer, the certificate will be protected by the customer managed key configuration of the account that owns the certificate after the transfer operation: If the transfer is accepted: The certificate is encrypted by the target account's customer managed key configuration. If the transfer is rejected or cancelled: The certificate is protected by the source account's customer managed key configuration.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
certificate_idstringThe ID of the certificate. (The last part of the certificate ARN contains the certificate ID.)
newStatusstringThe new status. Note: Setting the status to PENDING_TRANSFER or PENDING_ACTIVATION will result in an exception being thrown. PENDING_TRANSFER and PENDING_ACTIVATION are statuses used internally by IoT. They are not intended for developer use. Note: The status value REGISTER_INACTIVE is deprecated and should not be used.
regionstringAWS region (default: us-east-1)
targetAwsAccountstringThe Amazon Web Services account.
forceDeletebooleanForces the deletion of a certificate if it is inactive and is not attached to an IoT thing.
isAscendingOrderbooleanSpecifies the order for results. If True, the results are returned in ascending order, based on the creation date.
markerstringThe marker for the next set of results.
pageSizeintegerThe result page size.
setAsActivebooleanSpecifies whether the certificate is active.

SELECT examples​

Gets information about the specified certificate. Requires permission to access the DescribeCertificate action.

SELECT
ca_certificate_id,
certificate_arn,
certificate_id,
certificate_mode,
certificate_pem,
creation_date,
customer_version,
generation_id,
last_modified_date,
owned_by,
previous_owned_by,
status,
transfer_data,
validity
FROM aws.iot.certificates
WHERE certificate_id = '{{ certificate_id }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates an X.509 certificate using the specified certificate signing request. Requires permission to access the CreateCertificateFromCsr action. The CSR must include a public key that is either an RSA key with a length of at least 2048 bits or an ECC key from NIST P-256, NIST P-384, or NIST P-521 curves. For supported certificates, consult Certificate signing algorithms supported by IoT. Reusing the same certificate signing request (CSR) results in a distinct certificate. You can create multiple certificates in a batch by creating a directory, copying multiple .csr files into that directory, and then specifying that directory on the command line. The following commands show how to create a batch of certificates given a batch of CSRs. In the following commands, we assume that a set of CSRs are located inside of the directory my-csr-directory: On Linux and OS X, the command is: $ ls my-csr-directory/ | xargs -I {} aws iot create-certificate-from-csr --certificate-signing-request file://my-csr-directory/{} This command lists all of the CSRs in my-csr-directory and pipes each CSR file name to the aws iot create-certificate-from-csr Amazon Web Services CLI command to create a certificate for the corresponding CSR. You can also run the aws iot create-certificate-from-csr part of the command in parallel to speed up the certificate creation process: $ ls my-csr-directory/ | xargs -P 10 -I {} aws iot create-certificate-from-csr --certificate-signing-request file://my-csr-directory/{} On Windows PowerShell, the command to create certificates for all CSRs in my-csr-directory is: > ls -Name my-csr-directory | %{aws iot create-certificate-from-csr --certificate-signing-request file://my-csr-directory/$_} On a Windows command prompt, the command to create certificates for all CSRs in my-csr-directory is: > forfiles /p my-csr-directory /c "cmd /c aws iot create-certificate-from-csr --certificate-signing-request file://@path"

INSERT INTO aws.iot.certificates (
certificateSigningRequest,
region,
setAsActive
)
SELECT 
'{{ certificateSigningRequest }}' /* required */,
'{{ region }}',
'{{ setAsActive }}'
RETURNING
certificate_arn,
certificate_id,
certificate_pem
;

UPDATE examples​

Updates the status of the specified certificate. This operation is idempotent. Requires permission to access the UpdateCertificate action. Certificates must be in the ACTIVE state to authenticate devices that use a certificate to connect to IoT. Within a few minutes of updating a certificate from the ACTIVE state to any other state, IoT disconnects all devices that used that certificate to connect. Devices cannot use a certificate that is not in the ACTIVE state to reconnect.

UPDATE aws.iot.certificates
SET 
-- No updatable properties
WHERE 
certificate_id = '{{ certificate_id }}' --required
AND newStatus = '{{ newStatus }}' --required
AND region = '{{ region }}' --required;

DELETE examples​

Deletes the specified certificate. A certificate cannot be deleted if it has a policy or IoT thing attached to it or if its status is set to ACTIVE. To delete a certificate, first use the DetachPolicy action to detach all policies. Next, use the UpdateCertificate action to set the certificate to the INACTIVE status. Requires permission to access the DeleteCertificate action.

DELETE FROM aws.iot.certificates
WHERE certificate_id = '{{ certificate_id }}' --required
AND region = '{{ region }}' --required
AND forceDelete = '{{ forceDelete }}'
;

Lifecycle Methods​

Accepts a pending certificate transfer. The default state of the certificate is INACTIVE. To check for pending certificate transfers, call ListCertificates to enumerate your certificates. Requires permission to access the AcceptCertificateTransfer action.

EXEC aws.iot.certificates.accept_certificate_transfer 
@certificate_id='{{ certificate_id }}' --required, 
@region='{{ region }}' --required, 
@setAsActive={{ setAsActive }}
;
Last updated on