class Aws::ACMPCA::Client
An API client for ACMPCA
. To construct a client, you need to configure a `:region` and `:credentials`.
client = Aws::ACMPCA::Client.new( region: region_name, credentials: credentials, # ... )
For details on configuring region and credentials see the [developer guide](/sdk-for-ruby/v3/developer-guide/setup-config.html).
See {#initialize} for a full list of supported configuration options.
Attributes
@api private
Public Class Methods
@overload initialize(options)
@param [Hash] options @option options [required, Aws::CredentialProvider] :credentials Your AWS credentials. This can be an instance of any one of the following classes: * `Aws::Credentials` - Used for configuring static, non-refreshing credentials. * `Aws::SharedCredentials` - Used for loading static credentials from a shared file, such as `~/.aws/config`. * `Aws::AssumeRoleCredentials` - Used when you need to assume a role. * `Aws::AssumeRoleWebIdentityCredentials` - Used when you need to assume a role after providing credentials via the web. * `Aws::SSOCredentials` - Used for loading credentials from AWS SSO using an access token generated from `aws login`. * `Aws::ProcessCredentials` - Used for loading credentials from a process that outputs to stdout. * `Aws::InstanceProfileCredentials` - Used for loading credentials from an EC2 IMDS on an EC2 instance. * `Aws::ECSCredentials` - Used for loading credentials from instances running in ECS. * `Aws::CognitoIdentityCredentials` - Used for loading credentials from the Cognito Identity service. When `:credentials` are not configured directly, the following locations will be searched for credentials: * `Aws.config[:credentials]` * The `:access_key_id`, `:secret_access_key`, and `:session_token` options. * ENV['AWS_ACCESS_KEY_ID'], ENV['AWS_SECRET_ACCESS_KEY'] * `~/.aws/credentials` * `~/.aws/config` * EC2/ECS IMDS instance profile - When used by default, the timeouts are very aggressive. Construct and pass an instance of `Aws::InstanceProfileCredentails` or `Aws::ECSCredentials` to enable retries and extended timeouts. @option options [required, String] :region The AWS region to connect to. The configured `:region` is used to determine the service `:endpoint`. When not passed, a default `:region` is searched for in the following locations: * `Aws.config[:region]` * `ENV['AWS_REGION']` * `ENV['AMAZON_REGION']` * `ENV['AWS_DEFAULT_REGION']` * `~/.aws/credentials` * `~/.aws/config` @option options [String] :access_key_id @option options [Boolean] :active_endpoint_cache (false) When set to `true`, a thread polling for endpoints will be running in the background every 60 secs (default). Defaults to `false`. @option options [Boolean] :adaptive_retry_wait_to_fill (true) Used only in `adaptive` retry mode. When true, the request will sleep until there is sufficent client side capacity to retry the request. When false, the request will raise a `RetryCapacityNotAvailableError` and will not retry instead of sleeping. @option options [Boolean] :client_side_monitoring (false) When `true`, client-side metrics will be collected for all API requests from this client. @option options [String] :client_side_monitoring_client_id ("") Allows you to provide an identifier for this client which will be attached to all generated client side metrics. Defaults to an empty string. @option options [String] :client_side_monitoring_host ("127.0.0.1") Allows you to specify the DNS hostname or IPv4 or IPv6 address that the client side monitoring agent is running on, where client metrics will be published via UDP. @option options [Integer] :client_side_monitoring_port (31000) Required for publishing client metrics. The port that the client side monitoring agent is running on, where client metrics will be published via UDP. @option options [Aws::ClientSideMonitoring::Publisher] :client_side_monitoring_publisher (Aws::ClientSideMonitoring::Publisher) Allows you to provide a custom client-side monitoring publisher class. By default, will use the Client Side Monitoring Agent Publisher. @option options [Boolean] :convert_params (true) When `true`, an attempt is made to coerce request parameters into the required types. @option options [Boolean] :correct_clock_skew (true) Used only in `standard` and adaptive retry modes. Specifies whether to apply a clock skew correction and retry requests with skewed client clocks. @option options [Boolean] :disable_host_prefix_injection (false) Set to true to disable SDK automatically adding host prefix to default service endpoint when available. @option options [String] :endpoint The client endpoint is normally constructed from the `:region` option. You should only configure an `:endpoint` when connecting to test or custom endpoints. This should be a valid HTTP(S) URI. @option options [Integer] :endpoint_cache_max_entries (1000) Used for the maximum size limit of the LRU cache storing endpoints data for endpoint discovery enabled operations. Defaults to 1000. @option options [Integer] :endpoint_cache_max_threads (10) Used for the maximum threads in use for polling endpoints to be cached, defaults to 10. @option options [Integer] :endpoint_cache_poll_interval (60) When :endpoint_discovery and :active_endpoint_cache is enabled, Use this option to config the time interval in seconds for making requests fetching endpoints information. Defaults to 60 sec. @option options [Boolean] :endpoint_discovery (false) When set to `true`, endpoint discovery will be enabled for operations when available. @option options [Aws::Log::Formatter] :log_formatter (Aws::Log::Formatter.default) The log formatter. @option options [Symbol] :log_level (:info) The log level to send messages to the `:logger` at. @option options [Logger] :logger The Logger instance to send log messages to. If this option is not set, logging will be disabled. @option options [Integer] :max_attempts (3) An integer representing the maximum number attempts that will be made for a single request, including the initial attempt. For example, setting this value to 5 will result in a request being retried up to 4 times. Used in `standard` and `adaptive` retry modes. @option options [String] :profile ("default") Used when loading credentials from the shared credentials file at HOME/.aws/credentials. When not specified, 'default' is used. @option options [Proc] :retry_backoff A proc or lambda used for backoff. Defaults to 2**retries * retry_base_delay. This option is only used in the `legacy` retry mode. @option options [Float] :retry_base_delay (0.3) The base delay in seconds used by the default backoff function. This option is only used in the `legacy` retry mode. @option options [Symbol] :retry_jitter (:none) A delay randomiser function used by the default backoff function. Some predefined functions can be referenced by name - :none, :equal, :full, otherwise a Proc that takes and returns a number. This option is only used in the `legacy` retry mode. @see https://www.awsarchitectureblog.com/2015/03/backoff.html @option options [Integer] :retry_limit (3) The maximum number of times to retry failed requests. Only ~ 500 level server errors and certain ~ 400 level client errors are retried. Generally, these are throttling errors, data checksum errors, networking errors, timeout errors, auth errors, endpoint discovery, and errors from expired credentials. This option is only used in the `legacy` retry mode. @option options [Integer] :retry_max_delay (0) The maximum number of seconds to delay between retries (0 for no limit) used by the default backoff function. This option is only used in the `legacy` retry mode. @option options [String] :retry_mode ("legacy") Specifies which retry algorithm to use. Values are: * `legacy` - The pre-existing retry behavior. This is default value if no retry mode is provided. * `standard` - A standardized set of retry rules across the AWS SDKs. This includes support for retry quotas, which limit the number of unsuccessful retries a client can make. * `adaptive` - An experimental retry mode that includes all the functionality of `standard` mode along with automatic client side throttling. This is a provisional mode that may change behavior in the future. @option options [String] :secret_access_key @option options [String] :session_token @option options [Boolean] :simple_json (false) Disables request parameter conversion, validation, and formatting. Also disable response data type conversions. This option is useful when you want to ensure the highest level of performance by avoiding overhead of walking request parameters and response data structures. When `:simple_json` is enabled, the request parameters hash must be formatted exactly as the DynamoDB API expects. @option options [Boolean] :stub_responses (false) Causes the client to return stubbed responses. By default fake responses are generated and returned. You can specify the response data to return or errors to raise by calling {ClientStubs#stub_responses}. See {ClientStubs} for more information. ** Please note ** When response stubbing is enabled, no HTTP requests are made, and retries are disabled. @option options [Boolean] :validate_params (true) When `true`, request parameters are validated before sending the request. @option options [URI::HTTP,String] :http_proxy A proxy to send requests through. Formatted like 'http://proxy.com:123'. @option options [Float] :http_open_timeout (15) The number of seconds to wait when opening a HTTP session before raising a `Timeout::Error`. @option options [Integer] :http_read_timeout (60) The default number of seconds to wait for response data. This value can safely be set per-request on the session. @option options [Float] :http_idle_timeout (5) The number of seconds a connection is allowed to sit idle before it is considered stale. Stale connections are closed and removed from the pool before making a request. @option options [Float] :http_continue_timeout (1) The number of seconds to wait for a 100-continue response before sending the request body. This option has no effect unless the request has "Expect" header set to "100-continue". Defaults to `nil` which disables this behaviour. This value can safely be set per request on the session. @option options [Boolean] :http_wire_trace (false) When `true`, HTTP debug output will be sent to the `:logger`. @option options [Boolean] :ssl_verify_peer (true) When `true`, SSL peer certificates are verified when establishing a connection. @option options [String] :ssl_ca_bundle Full path to the SSL certificate authority bundle file that should be used when verifying peer certificates. If you do not pass `:ssl_ca_bundle` or `:ssl_ca_directory` the the system default will be used if available. @option options [String] :ssl_ca_directory Full path of the directory that contains the unbundled SSL certificate authority files for verifying peer certificates. If you do not pass `:ssl_ca_bundle` or `:ssl_ca_directory` the the system default will be used if available.
# File lib/aws-sdk-acmpca/client.rb, line 334 def initialize(*args) super end
Private Class Methods
@api private
# File lib/aws-sdk-acmpca/client.rb, line 2520 def errors_module Errors end
Public Instance Methods
@param params ({}) @api private
# File lib/aws-sdk-acmpca/client.rb, line 2378 def build_request(operation_name, params = {}) handlers = @handlers.for(operation_name) context = Seahorse::Client::RequestContext.new( operation_name: operation_name, operation: config.api.operation(operation_name), client: self, params: params, config: config) context[:gem_name] = 'aws-sdk-acmpca' context[:gem_version] = '1.40.0' Seahorse::Client::Request.new(handlers, context) end
Grants one or more permissions on a private CA to the AWS Certificate Manager (ACM) service principal (`acm.amazonaws.com`). These permissions allow ACM to issue and renew ACM certificates that reside in the same AWS account as the CA.
You can list current permissions with the [ListPermissions] action and revoke them with the [DeletePermission] action.
**About Permissions**
-
If the private CA and the certificates it issues reside in the same account, you can use `CreatePermission` to grant permissions for ACM to carry out automatic certificate renewals.
-
For automatic certificate renewal to succeed, the ACM service principal needs permissions to create, retrieve, and list certificates.
-
If the private CA and the ACM certificates reside in different accounts, then permissions cannot be used to enable automatic renewals. Instead, the ACM certificate owner must set up a resource-based policy to enable cross-account issuance and renewals. For more information, see [Using a
Resource
Based Policy with ACM Private CA].
[1]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_ListPermissions.html [2]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_DeletePermission.html [3]: docs.aws.amazon.com/acm-pca/latest/userguide/pca-rbp.html
@option params [required, String] :certificate_authority_arn
The Amazon Resource Name (ARN) of the CA that grants the permissions. You can find the ARN by calling the [ListCertificateAuthorities][1] action. This must have the following form: `arn:aws:acm-pca:region:account:certificate-authority/12345678-1234-1234-1234-123456789012 `. [1]: https://docs.aws.amazon.com/acm-pca/latest/APIReference/API_ListCertificateAuthorities.html
@option params [required, String] :principal
The AWS service or identity that receives the permission. At this time, the only valid principal is `acm.amazonaws.com`.
@option params [String] :source_account
The ID of the calling account.
@option params [required, Array<String>] :actions
The actions that the specified AWS service principal can use. These include `IssueCertificate`, `GetCertificate`, and `ListPermissions`.
@return [Struct] Returns an empty {Seahorse::Client::Response response}.
@example Request syntax with placeholder values
resp = client.create_permission({ certificate_authority_arn: "Arn", # required principal: "Principal", # required source_account: "AccountId", actions: ["IssueCertificate"], # required, accepts IssueCertificate, GetCertificate, ListPermissions })
@see docs.aws.amazon.com/goto/WebAPI/acm-pca-2017-08-22/CreatePermission AWS API Documentation
@overload create_permission
(params = {}) @param [Hash] params ({})
# File lib/aws-sdk-acmpca/client.rb, line 672 def create_permission(params = {}, options = {}) req = build_request(:create_permission, params) req.send_request(options) end
Revokes permissions on a private CA granted to the AWS Certificate Manager (ACM) service principal (acm.amazonaws.com).
These permissions allow ACM to issue and renew ACM certificates that reside in the same AWS account as the CA. If you revoke these permissions, ACM will no longer renew the affected certificates automatically.
Permissions can be granted with the [CreatePermission] action and listed with the [ListPermissions] action.
**About Permissions**
-
If the private CA and the certificates it issues reside in the same account, you can use `CreatePermission` to grant permissions for ACM to carry out automatic certificate renewals.
-
For automatic certificate renewal to succeed, the ACM service principal needs permissions to create, retrieve, and list certificates.
-
If the private CA and the ACM certificates reside in different accounts, then permissions cannot be used to enable automatic renewals. Instead, the ACM certificate owner must set up a resource-based policy to enable cross-account issuance and renewals. For more information, see [Using a
Resource
Based Policy with ACM Private CA].
[1]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_CreatePermission.html [2]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_ListPermissions.html [3]: docs.aws.amazon.com/acm-pca/latest/userguide/pca-rbp.html
@option params [required, String] :certificate_authority_arn
The Amazon Resource Number (ARN) of the private CA that issued the permissions. You can find the CA's ARN by calling the [ListCertificateAuthorities][1] action. This must have the following form: `arn:aws:acm-pca:region:account:certificate-authority/12345678-1234-1234-1234-123456789012 `. [1]: https://docs.aws.amazon.com/acm-pca/latest/APIReference/API_ListCertificateAuthorities.html
@option params [required, String] :principal
The AWS service or identity that will have its CA permissions revoked. At this time, the only valid service principal is `acm.amazonaws.com`
@option params [String] :source_account
The AWS account that calls this action.
@return [Struct] Returns an empty {Seahorse::Client::Response response}.
@example Request syntax with placeholder values
resp = client.delete_permission({ certificate_authority_arn: "Arn", # required principal: "Principal", # required source_account: "AccountId", })
@see docs.aws.amazon.com/goto/WebAPI/acm-pca-2017-08-22/DeletePermission AWS API Documentation
@overload delete_permission
(params = {}) @param [Hash] params ({})
# File lib/aws-sdk-acmpca/client.rb, line 817 def delete_permission(params = {}, options = {}) req = build_request(:delete_permission, params) req.send_request(options) end
Deletes the resource-based policy attached to a private CA. Deletion will remove any access that the policy has granted. If there is no policy attached to the private CA, this action will return successful.
If you delete a policy that was applied through AWS Resource
Access Manager (RAM), the CA will be removed from all shares in which it was included.
The AWS Certificate Manager Service Linked Role that the policy supports is not affected when you delete the policy.
The current policy can be shown with [GetPolicy] and updated with [PutPolicy].
**About Policies**
-
A policy grants access on a private CA to an AWS customer account, to AWS Organizations, or to an AWS Organizations unit. Policies are under the control of a CA administrator. For more information, see [Using a
Resource
Based Policy with ACM Private CA]. -
A policy permits a user of AWS Certificate Manager (ACM) to issue ACM certificates signed by a CA in another account.
-
For ACM to manage automatic renewal of these certificates, the ACM user must configure a Service Linked Role (SLR). The SLR allows the ACM service to assume the identity of the user, subject to confirmation against the ACM Private CA policy. For more information, see [Using a Service Linked Role with ACM].
-
Updates made in AWS
Resource
Manager (RAM) are reflected in policies. For more information, see [Attach a Policy for Cross-Account Access].
[1]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_GetPolicy.html [2]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_PutPolicy.html [3]: docs.aws.amazon.com/acm-pca/latest/userguide/pca-rbp.html [4]: docs.aws.amazon.com/acm/latest/userguide/acm-slr.html [5]: docs.aws.amazon.com/acm-pca/latest/userguide/pca-ram.html
@option params [required, String] :resource_arn
The Amazon Resource Number (ARN) of the private CA that will have its policy deleted. You can find the CA's ARN by calling the [ListCertificateAuthorities][1] action. The ARN value must have the form `arn:aws:acm-pca:region:account:certificate-authority/01234567-89ab-cdef-0123-0123456789ab`. [1]: https://docs.aws.amazon.com/acm-pca/latest/APIReference/API_ListCertificateAuthorities.html
@return [Struct] Returns an empty {Seahorse::Client::Response response}.
@example Request syntax with placeholder values
resp = client.delete_policy({ resource_arn: "Arn", # required })
@see docs.aws.amazon.com/goto/WebAPI/acm-pca-2017-08-22/DeletePolicy AWS API Documentation
@overload delete_policy
(params = {}) @param [Hash] params ({})
# File lib/aws-sdk-acmpca/client.rb, line 887 def delete_policy(params = {}, options = {}) req = build_request(:delete_policy, params) req.send_request(options) end
Retrieves a certificate from your private CA or one that has been shared with you. The ARN of the certificate is returned when you call the [IssueCertificate] action. You must specify both the ARN of your private CA and the ARN of the issued certificate when calling the GetCertificate action. You can retrieve the certificate if it is in the ISSUED state. You can call the
- CreateCertificateAuthorityAuditReport][2
-
action to create a report
that contains information about all of the certificates issued and revoked by your private CA.
[1]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_IssueCertificate.html [2]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_CreateCertificateAuthorityAuditReport.html
@option params [required, String] :certificate_authority_arn
The Amazon Resource Name (ARN) that was returned when you called [CreateCertificateAuthority][1]. This must be of the form: `arn:aws:acm-pca:region:account:certificate-authority/12345678-1234-1234-1234-123456789012 `. [1]: https://docs.aws.amazon.com/acm-pca/latest/APIReference/API_CreateCertificateAuthority.html
@option params [required, String] :certificate_arn
The ARN of the issued certificate. The ARN contains the certificate serial number and must be in the following form: `arn:aws:acm-pca:region:account:certificate-authority/12345678-1234-1234-1234-123456789012/certificate/286535153982981100925020015808220737245 `
@return [Types::GetCertificateResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods:
* {Types::GetCertificateResponse#certificate #certificate} => String * {Types::GetCertificateResponse#certificate_chain #certificate_chain} => String
@example Request syntax with placeholder values
resp = client.get_certificate({ certificate_authority_arn: "Arn", # required certificate_arn: "Arn", # required })
@example Response structure
resp.certificate #=> String resp.certificate_chain #=> String
The following waiters are defined for this operation (see {Client#wait_until} for detailed usage):
* certificate_issued
@see docs.aws.amazon.com/goto/WebAPI/acm-pca-2017-08-22/GetCertificate AWS API Documentation
@overload get_certificate
(params = {}) @param [Hash] params ({})
# File lib/aws-sdk-acmpca/client.rb, line 1143 def get_certificate(params = {}, options = {}) req = build_request(:get_certificate, params) req.send_request(options) end
Retrieves the resource-based policy attached to a private CA. If either the private CA resource or the policy cannot be found, this action returns a `ResourceNotFoundException`.
The policy can be attached or updated with [PutPolicy] and removed with [DeletePolicy].
**About Policies**
-
A policy grants access on a private CA to an AWS customer account, to AWS Organizations, or to an AWS Organizations unit. Policies are under the control of a CA administrator. For more information, see [Using a
Resource
Based Policy with ACM Private CA]. -
A policy permits a user of AWS Certificate Manager (ACM) to issue ACM certificates signed by a CA in another account.
-
For ACM to manage automatic renewal of these certificates, the ACM user must configure a Service Linked Role (SLR). The SLR allows the ACM service to assume the identity of the user, subject to confirmation against the ACM Private CA policy. For more information, see [Using a Service Linked Role with ACM].
-
Updates made in AWS
Resource
Manager (RAM) are reflected in policies. For more information, see [Attach a Policy for Cross-Account Access].
[1]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_PutPolicy.html [2]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_DeletePolicy.html [3]: docs.aws.amazon.com/acm-pca/latest/userguide/pca-rbp.html [4]: docs.aws.amazon.com/acm/latest/userguide/acm-slr.html [5]: docs.aws.amazon.com/acm-pca/latest/userguide/pca-ram.html
@option params [required, String] :resource_arn
The Amazon Resource Number (ARN) of the private CA that will have its policy retrieved. You can find the CA's ARN by calling the ListCertificateAuthorities action.
@return [Types::GetPolicyResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods:
* {Types::GetPolicyResponse#policy #policy} => String
@example Request syntax with placeholder values
resp = client.get_policy({ resource_arn: "Arn", # required })
@example Response structure
resp.policy #=> String
@see docs.aws.amazon.com/goto/WebAPI/acm-pca-2017-08-22/GetPolicy AWS API Documentation
@overload get_policy
(params = {}) @param [Hash] params ({})
# File lib/aws-sdk-acmpca/client.rb, line 1296 def get_policy(params = {}, options = {}) req = build_request(:get_policy, params) req.send_request(options) end
Uses your private certificate authority (CA), or one that has been shared with you, to issue a client certificate. This action returns the Amazon Resource
Name (ARN) of the certificate. You can retrieve the certificate by calling the [GetCertificate] action and specifying the ARN.
<note markdown=“1”> You cannot use the ACM ListCertificateAuthorities action to retrieve the ARNs of the certificates that you issue by using ACM Private CA.
</note>
[1]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_GetCertificate.html
@option params [Types::ApiPassthrough] :api_passthrough
Specifies X.509 certificate information to be included in the issued certificate. An `APIPassthrough` or `APICSRPassthrough` template variant must be selected, or else this parameter is ignored. For more information about using these templates, see [Understanding Certificate Templates][1]. If conflicting or duplicate certificate information is supplied during certificate issuance, ACM Private CA applies [order of operation rules][2] to determine what information is used. [1]: https://docs.aws.amazon.com/acm-pca/latest/userguide/UsingTemplates.html [2]: https://docs.aws.amazon.com/acm-pca/latest/userguide/UsingTemplates.html#template-order-of-operations
@option params [required, String] :certificate_authority_arn
The Amazon Resource Name (ARN) that was returned when you called [CreateCertificateAuthority][1]. This must be of the form: `arn:aws:acm-pca:region:account:certificate-authority/12345678-1234-1234-1234-123456789012 ` [1]: https://docs.aws.amazon.com/acm-pca/latest/APIReference/API_CreateCertificateAuthority.html
@option params [required, String, StringIO, File] :csr
The certificate signing request (CSR) for the certificate you want to issue. As an example, you can use the following OpenSSL command to create the CSR and a 2048 bit RSA private key. `openssl req -new -newkey rsa:2048 -days 365 -keyout private/test_cert_priv_key.pem -out csr/test_cert_.csr` If you have a configuration file, you can then use the following OpenSSL command. The `usr_cert` block in the configuration file contains your X509 version 3 extensions. `openssl req -new -config openssl_rsa.cnf -extensions usr_cert -newkey rsa:2048 -days -365 -keyout private/test_cert_priv_key.pem -out csr/test_cert_.csr` Note: A CSR must provide either a *subject name* or a *subject alternative name* or the request will be rejected.
@option params [required, String] :signing_algorithm
The name of the algorithm that will be used to sign the certificate to be issued. This parameter should not be confused with the `SigningAlgorithm` parameter used to sign a CSR in the `CreateCertificateAuthority` action.
@option params [String] :template_arn
Specifies a custom configuration template to use when issuing a certificate. If this parameter is not provided, ACM Private CA defaults to the `EndEntityCertificate/V1` template. For CA certificates, you should choose the shortest path length that meets your needs. The path length is indicated by the PathLen*N* portion of the ARN, where *N* is the [CA depth][1]. Note: The CA depth configured on a subordinate CA certificate must not exceed the limit set by its parents in the CA hierarchy. For a list of `TemplateArn` values supported by ACM Private CA, see [Understanding Certificate Templates][2]. [1]: https://docs.aws.amazon.com/acm-pca/latest/userguide/PcaTerms.html#terms-cadepth [2]: https://docs.aws.amazon.com/acm-pca/latest/userguide/UsingTemplates.html
@option params [required, Types::Validity] :validity
Information describing the end of the validity period of the certificate. This parameter sets the “Not After” date for the certificate. Certificate validity is the period of time during which a certificate is valid. Validity can be expressed as an explicit date and time when the certificate expires, or as a span of time after issuance, stated in days, months, or years. For more information, see [Validity][1] in RFC 5280. This value is unaffected when `ValidityNotBefore` is also specified. For example, if `Validity` is set to 20 days in the future, the certificate will expire 20 days from issuance time regardless of the `ValidityNotBefore` value. The end of the validity period configured on a certificate must not exceed the limit set on its parents in the CA hierarchy. [1]: https://tools.ietf.org/html/rfc5280#section-4.1.2.5
@option params [Types::Validity] :validity_not_before
Information describing the start of the validity period of the certificate. This parameter sets the “Not Before" date for the certificate. By default, when issuing a certificate, ACM Private CA sets the "Not Before" date to the issuance time minus 60 minutes. This compensates for clock inconsistencies across computer systems. The `ValidityNotBefore` parameter can be used to customize the “Not Before” value. Unlike the `Validity` parameter, the `ValidityNotBefore` parameter is optional. The `ValidityNotBefore` value is expressed as an explicit date and time, using the `Validity` type value `ABSOLUTE`. For more information, see [Validity][1] in this API reference and [Validity][2] in RFC 5280. [1]: https://docs.aws.amazon.com/acm-pca/latest/APIReference/API_Validity.html [2]: https://tools.ietf.org/html/rfc5280#section-4.1.2.5
@option params [String] :idempotency_token
Alphanumeric string that can be used to distinguish between calls to the **IssueCertificate** action. Idempotency tokens for **IssueCertificate** time out after one minute. Therefore, if you call **IssueCertificate** multiple times with the same idempotency token within one minute, ACM Private CA recognizes that you are requesting only one certificate and will issue only one. If you change the idempotency token for each call, PCA recognizes that you are requesting multiple certificates.
@return [Types::IssueCertificateResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods:
* {Types::IssueCertificateResponse#certificate_arn #certificate_arn} => String
@example Request syntax with placeholder values
resp = client.issue_certificate({ api_passthrough: { extensions: { certificate_policies: [ { cert_policy_id: "CustomObjectIdentifier", # required policy_qualifiers: [ { policy_qualifier_id: "CPS", # required, accepts CPS qualifier: { # required cps_uri: "String256", # required }, }, ], }, ], extended_key_usage: [ { extended_key_usage_type: "SERVER_AUTH", # accepts SERVER_AUTH, CLIENT_AUTH, CODE_SIGNING, EMAIL_PROTECTION, TIME_STAMPING, OCSP_SIGNING, SMART_CARD_LOGIN, DOCUMENT_SIGNING, CERTIFICATE_TRANSPARENCY extended_key_usage_object_identifier: "CustomObjectIdentifier", }, ], key_usage: { digital_signature: false, non_repudiation: false, key_encipherment: false, data_encipherment: false, key_agreement: false, key_cert_sign: false, crl_sign: false, encipher_only: false, decipher_only: false, }, subject_alternative_names: [ { other_name: { type_id: "CustomObjectIdentifier", # required value: "String256", # required }, rfc_822_name: "String256", dns_name: "String253", directory_name: { country: "CountryCodeString", organization: "String64", organizational_unit: "String64", distinguished_name_qualifier: "ASN1PrintableString64", state: "String128", common_name: "String64", serial_number: "ASN1PrintableString64", locality: "String128", title: "String64", surname: "String40", given_name: "String16", initials: "String5", pseudonym: "String128", generation_qualifier: "String3", }, edi_party_name: { party_name: "String256", # required name_assigner: "String256", }, uniform_resource_identifier: "String253", ip_address: "String39", registered_id: "CustomObjectIdentifier", }, ], }, subject: { country: "CountryCodeString", organization: "String64", organizational_unit: "String64", distinguished_name_qualifier: "ASN1PrintableString64", state: "String128", common_name: "String64", serial_number: "ASN1PrintableString64", locality: "String128", title: "String64", surname: "String40", given_name: "String16", initials: "String5", pseudonym: "String128", generation_qualifier: "String3", }, }, certificate_authority_arn: "Arn", # required csr: "data", # required signing_algorithm: "SHA256WITHECDSA", # required, accepts SHA256WITHECDSA, SHA384WITHECDSA, SHA512WITHECDSA, SHA256WITHRSA, SHA384WITHRSA, SHA512WITHRSA template_arn: "Arn", validity: { # required value: 1, # required type: "END_DATE", # required, accepts END_DATE, ABSOLUTE, DAYS, MONTHS, YEARS }, validity_not_before: { value: 1, # required type: "END_DATE", # required, accepts END_DATE, ABSOLUTE, DAYS, MONTHS, YEARS }, idempotency_token: "IdempotencyToken", })
@example Response structure
resp.certificate_arn #=> String
@see docs.aws.amazon.com/goto/WebAPI/acm-pca-2017-08-22/IssueCertificate AWS API Documentation
@overload issue_certificate
(params = {}) @param [Hash] params ({})
# File lib/aws-sdk-acmpca/client.rb, line 1703 def issue_certificate(params = {}, options = {}) req = build_request(:issue_certificate, params) req.send_request(options) end
List all permissions on a private CA, if any, granted to the AWS Certificate Manager (ACM) service principal (acm.amazonaws.com).
These permissions allow ACM to issue and renew ACM certificates that reside in the same AWS account as the CA.
Permissions can be granted with the [CreatePermission] action and revoked with the [DeletePermission] action.
**About Permissions**
-
If the private CA and the certificates it issues reside in the same account, you can use `CreatePermission` to grant permissions for ACM to carry out automatic certificate renewals.
-
For automatic certificate renewal to succeed, the ACM service principal needs permissions to create, retrieve, and list certificates.
-
If the private CA and the ACM certificates reside in different accounts, then permissions cannot be used to enable automatic renewals. Instead, the ACM certificate owner must set up a resource-based policy to enable cross-account issuance and renewals. For more information, see [Using a
Resource
Based Policy with ACM Private CA].
[1]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_CreatePermission.html [2]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_DeletePermission.html [3]: docs.aws.amazon.com/acm-pca/latest/userguide/pca-rbp.html
@option params [required, String] :certificate_authority_arn
The Amazon Resource Number (ARN) of the private CA to inspect. You can find the ARN by calling the [ListCertificateAuthorities][1] action. This must be of the form: `arn:aws:acm-pca:region:account:certificate-authority/12345678-1234-1234-1234-123456789012` You can get a private CA's ARN by running the [ListCertificateAuthorities][1] action. [1]: https://docs.aws.amazon.com/acm-pca/latest/APIReference/API_ListCertificateAuthorities.html
@option params [String] :next_token
When paginating results, use this parameter in a subsequent request after you receive a response with truncated results. Set it to the value of **NextToken** from the response you just received.
@option params [Integer] :max_results
When paginating results, use this parameter to specify the maximum number of items to return in the response. If additional items exist beyond the number you specify, the **NextToken** element is sent in the response. Use this **NextToken** value in a subsequent request to retrieve additional items.
@return [Types::ListPermissionsResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods:
* {Types::ListPermissionsResponse#permissions #permissions} => Array<Types::Permission> * {Types::ListPermissionsResponse#next_token #next_token} => String
The returned {Seahorse::Client::Response response} is a pageable response and is Enumerable. For details on usage see {Aws::PageableResponse PageableResponse}.
@example Request syntax with placeholder values
resp = client.list_permissions({ certificate_authority_arn: "Arn", # required next_token: "NextToken", max_results: 1, })
@example Response structure
resp.permissions #=> Array resp.permissions[0].certificate_authority_arn #=> String resp.permissions[0].created_at #=> Time resp.permissions[0].principal #=> String resp.permissions[0].source_account #=> String resp.permissions[0].actions #=> Array resp.permissions[0].actions[0] #=> String, one of "IssueCertificate", "GetCertificate", "ListPermissions" resp.permissions[0].policy #=> String resp.next_token #=> String
@see docs.aws.amazon.com/goto/WebAPI/acm-pca-2017-08-22/ListPermissions AWS API Documentation
@overload list_permissions
(params = {}) @param [Hash] params ({})
# File lib/aws-sdk-acmpca/client.rb, line 1918 def list_permissions(params = {}, options = {}) req = build_request(:list_permissions, params) req.send_request(options) end
Attaches a resource-based policy to a private CA.
A policy can also be applied by sharing a private CA through AWS Resource
Access Manager (RAM). For more information, see [Attach a Policy for Cross-Account Access].
The policy can be displayed with [GetPolicy] and removed with [DeletePolicy].
**About Policies**
-
A policy grants access on a private CA to an AWS customer account, to AWS Organizations, or to an AWS Organizations unit. Policies are under the control of a CA administrator. For more information, see [Using a
Resource
Based Policy with ACM Private CA]. -
A policy permits a user of AWS Certificate Manager (ACM) to issue ACM certificates signed by a CA in another account.
-
For ACM to manage automatic renewal of these certificates, the ACM user must configure a Service Linked Role (SLR). The SLR allows the ACM service to assume the identity of the user, subject to confirmation against the ACM Private CA policy. For more information, see [Using a Service Linked Role with ACM].
-
Updates made in AWS
Resource
Manager (RAM) are reflected in policies. For more information, see [Attach a Policy for Cross-Account Access].
[1]: docs.aws.amazon.com/acm-pca/latest/userguide/pca-ram.html [2]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_GetPolicy.html [3]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_DeletePolicy.html [4]: docs.aws.amazon.com/acm-pca/latest/userguide/pca-rbp.html [5]: docs.aws.amazon.com/acm/latest/userguide/acm-slr.html
@option params [required, String] :resource_arn
The Amazon Resource Number (ARN) of the private CA to associate with the policy. The ARN of the CA can be found by calling the [ListCertificateAuthorities][1] action. [1]: https://docs.aws.amazon.com/acm-pca/latest/APIReference/API_ListCertificateAuthorities.html
@option params [required, String] :policy
The path and file name of a JSON-formatted IAM policy to attach to the specified private CA resource. If this policy does not contain all required statements or if it includes any statement that is not allowed, the `PutPolicy` action returns an `InvalidPolicyException`. For information about IAM policy and statement structure, see [Overview of JSON Policies][1]. [1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#access_policies-json
@return [Struct] Returns an empty {Seahorse::Client::Response response}.
@example Request syntax with placeholder values
resp = client.put_policy({ resource_arn: "Arn", # required policy: "AWSPolicy", # required })
@see docs.aws.amazon.com/goto/WebAPI/acm-pca-2017-08-22/PutPolicy AWS API Documentation
@overload put_policy
(params = {}) @param [Hash] params ({})
# File lib/aws-sdk-acmpca/client.rb, line 2062 def put_policy(params = {}, options = {}) req = build_request(:put_policy, params) req.send_request(options) end
Revokes a certificate that was issued inside ACM Private CA. If you enable a certificate revocation list (CRL) when you create or update your private CA, information about the revoked certificates will be included in the CRL. ACM Private CA writes the CRL to an S3 bucket that you specify. A CRL is typically updated approximately 30 minutes after a certificate is revoked. If for any reason the CRL update fails, ACM Private CA attempts makes further attempts every 15 minutes. With Amazon CloudWatch, you can create alarms for the metrics `CRLGenerated` and `MisconfiguredCRLBucket`. For more information, see [Supported CloudWatch Metrics].
<note markdown=“1”> Both PCA and the IAM principal must have permission to write to the S3 bucket that you specify. If the IAM principal making the call does not have permission to write to the bucket, then an exception is thrown. For more information, see [Configure Access to ACM Private CA].
</note>
ACM Private CA also writes revocation information to the audit report. For more information, see [CreateCertificateAuthorityAuditReport].
<note markdown=“1”> You cannot revoke a root CA self-signed certificate.
</note>
[1]: docs.aws.amazon.com/acm-pca/latest/userguide/PcaCloudWatch.html [2]: docs.aws.amazon.com/acm-pca/latest/userguide/PcaAuthAccess.html [3]: docs.aws.amazon.com/acm-pca/latest/APIReference/API_CreateCertificateAuthorityAuditReport.html
@option params [required, String] :certificate_authority_arn
Amazon Resource Name (ARN) of the private CA that issued the certificate to be revoked. This must be of the form: `arn:aws:acm-pca:region:account:certificate-authority/12345678-1234-1234-1234-123456789012 `
@option params [required, String] :certificate_serial
Serial number of the certificate to be revoked. This must be in hexadecimal format. You can retrieve the serial number by calling [GetCertificate][1] with the Amazon Resource Name (ARN) of the certificate you want and the ARN of your private CA. The **GetCertificate** action retrieves the certificate in the PEM format. You can use the following OpenSSL command to list the certificate in text format and copy the hexadecimal serial number. `openssl x509 -in file_path -text -noout` You can also copy the serial number from the console or use the [DescribeCertificate][2] action in the *AWS Certificate Manager API Reference*. [1]: https://docs.aws.amazon.com/acm-pca/latest/APIReference/API_GetCertificate.html [2]: https://docs.aws.amazon.com/acm/latest/APIReference/API_DescribeCertificate.html
@option params [required, String] :revocation_reason
Specifies why you revoked the certificate.
@return [Struct] Returns an empty {Seahorse::Client::Response response}.
@example Request syntax with placeholder values
resp = client.revoke_certificate({ certificate_authority_arn: "Arn", # required certificate_serial: "String128", # required revocation_reason: "UNSPECIFIED", # required, accepts UNSPECIFIED, KEY_COMPROMISE, CERTIFICATE_AUTHORITY_COMPROMISE, AFFILIATION_CHANGED, SUPERSEDED, CESSATION_OF_OPERATION, PRIVILEGE_WITHDRAWN, A_A_COMPROMISE })
@see docs.aws.amazon.com/goto/WebAPI/acm-pca-2017-08-22/RevokeCertificate AWS API Documentation
@overload revoke_certificate
(params = {}) @param [Hash] params ({})
# File lib/aws-sdk-acmpca/client.rb, line 2196 def revoke_certificate(params = {}, options = {}) req = build_request(:revoke_certificate, params) req.send_request(options) end
Polls an API operation until a resource enters a desired state.
## Basic Usage
A waiter will call an API operation until:
-
It is successful
-
It enters a terminal state
-
It makes the maximum number of attempts
In between attempts, the waiter will sleep.
# polls in a loop, sleeping between attempts client.wait_until(waiter_name, params)
## Configuration
You can configure the maximum number of polling attempts, and the delay (in seconds) between each polling attempt. You can pass configuration as the final arguments hash.
# poll for ~25 seconds client.wait_until(waiter_name, params, { max_attempts: 5, delay: 5, })
## Callbacks
You can be notified before each polling attempt and before each delay. If you throw `:success` or `:failure` from these callbacks, it will terminate the waiter.
started_at = Time.now client.wait_until(waiter_name, params, { # disable max attempts max_attempts: nil, # poll for 1 hour, instead of a number of attempts before_wait: -> (attempts, response) do throw :failure if Time.now - started_at > 3600 end })
## Handling Errors
When a waiter is unsuccessful, it will raise an error. All of the failure errors extend from {Aws::Waiters::Errors::WaiterFailed}.
begin client.wait_until(...) rescue Aws::Waiters::Errors::WaiterFailed # resource did not enter the desired state in time end
## Valid Waiters
The following table lists the valid waiter names, the operations they call, and the default `:delay` and `:max_attempts` values.
| waiter_name | params | :delay | :max_attempts | | ——————————— | —————————————————- | ——– | ————- | | audit_report_created | {Client#describe_certificate_authority_audit_report} | 3 | 60 | | certificate_authority_csr_created | {Client#get_certificate_authority_csr} | 3 | 60 | | certificate_issued | {Client#get_certificate} | 3 | 60 |
@raise [Errors::FailureStateError] Raised when the waiter terminates
because the waiter has entered a state that it will not transition out of, preventing success.
@raise [Errors::TooManyAttemptsError] Raised when the configured
maximum number of attempts have been made, and the waiter is not yet successful.
@raise [Errors::UnexpectedError] Raised when an error is encounted
while polling for a resource that is not expected.
@raise [Errors::NoSuchWaiterError] Raised when you request to wait
for an unknown state.
@return [Boolean] Returns `true` if the waiter was successful. @param [Symbol] waiter_name @param [Hash] params ({}) @param [Hash] options ({}) @option options [Integer] :max_attempts @option options [Integer] :delay @option options [Proc] :before_attempt @option options [Proc] :before_wait
# File lib/aws-sdk-acmpca/client.rb, line 2481 def wait_until(waiter_name, params = {}, options = {}) w = waiter(waiter_name, options) yield(w.waiter) if block_given? # deprecated w.wait(params) end
@api private @deprecated
# File lib/aws-sdk-acmpca/client.rb, line 2489 def waiter_names waiters.keys end
Private Instance Methods
@param [Symbol] waiter_name @param [Hash] options ({})
# File lib/aws-sdk-acmpca/client.rb, line 2497 def waiter(waiter_name, options = {}) waiter_class = waiters[waiter_name] if waiter_class waiter_class.new(options.merge(client: self)) else raise Aws::Waiters::Errors::NoSuchWaiterError.new(waiter_name, waiters.keys) end end
# File lib/aws-sdk-acmpca/client.rb, line 2506 def waiters { audit_report_created: Waiters::AuditReportCreated, certificate_authority_csr_created: Waiters::CertificateAuthorityCSRCreated, certificate_issued: Waiters::CertificateIssued } end