aws-sdk 1.0.4 → 1.1.0

data/lib/aws/iam/server_certificate_collection.rb

@@ -0,0 +1,174 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/iam/collection'
+require 'aws/iam/server_certificate'
+
+module AWS
+  class IAM
+
+    # A collection that provides access to IAM server certificates
+    # belonging to this account.
+    #
+    #   iam = AWS::IAM.new
+    #   certificates = iam.server_certificates
+    #
+    # == Uploading A Server Certificate
+    #
+    # You can upload any valid, signed certificate using {#upload}.
+    #
+    #   certificates.upload(:name => "MyCert",
+    #                       :certificate_body => my_certificate_body,
+    #                       :private_key => my_private_key)
+    #
+    # For information about generating a server certificate for use
+    # with IAM, see
+    # {http://docs.amazonwebservices.com/IAM/latest/UserGuide/InstallCert.html
+    # Creating and Uploading Server Certificates} in <i>Using AWS
+    # Identity and Access Management</i>.
+    #
+    # == Getting a Server Certificate by Name
+    #
+    # You can get a reference to a server certificate using array notation:
+    #
+    #   certificate = certificates['MyCert']
+    #
+    # == Enumerating Server Certificates
+    #
+    # Server certificate collections can also be used to enumerate
+    # certificates:
+    #
+    #   certificates.each do |cert|
+    #     puts cert.name
+    #   end
+    #
+    # You can limit the certificates returned by passing a +:prefix+
+    # option to any of the enumerator methods.  When you pass a
+    # prefix, only the certificates whose paths start with the given
+    # string will be returned.
+    class ServerCertificateCollection
+
+      include Collection::WithPrefix
+
+      # Uploads a server certificate entity for the AWS account. The
+      # server certificate entity includes a public key certificate, a
+      # private key, and an optional certificate chain, which should
+      # all be PEM-encoded.
+      #
+      # @param [Hash] options Options for uploading the certificate.
+      #   +:name+, +:certificate_body+, and +:private_key+ are
+      #   required.
+      #
+      # @option options [String] :certificate_body The contents of the
+      #   public key certificate in PEM-encoded format.
+      #
+      # @option options [String] :name The name for the server
+      #   certificate. Do not include the path in this value.
+      #
+      # @option options [String] :path The path for the server
+      #   certificate. For more information about paths, see
+      #   {http://docs.amazonwebservices.com/IAM/latest/UserGuide/index.html?Using_Identifiers.html
+      #   Identifiers for IAM Entities} in <i>Using AWS Identity and
+      #   Access Management</i>.
+      #
+      # @option options [String] :private_key The contents of the
+      #   private key in PEM-encoded format.
+      #
+      # @option options [String] :certificate_chain The contents of
+      #   the certificate chain. This is typically a concatenation of
+      #   the PEM-encoded public key certificates of the chain.
+      #
+      # @return [ServerCertificate] The newly created server
+      #   certificate.
+      def upload(options = {})
+        client_opts = options.dup
+        client_opts[:server_certificate_name] = client_opts.delete(:name)
+
+        if path = client_opts[:path]
+          client_opts[:path] = "/#{path}/".
+            sub(%r{^//}, "/").
+            sub(%r{//$}, "/")
+        end
+
+        resp = client.upload_server_certificate(client_opts)
+        ServerCertificate.new(resp.server_certificate_metadata.
+                              server_certificate_name,
+                              :config => config)
+      end
+      alias_method :create, :upload
+
+      # Returns a reference to the server certificate with the given
+      # name:
+      #
+      #   certificate = iam.server_certificates['MyCert']
+      #
+      # @param [String] name Name of the server certificate.
+      #
+      # @return [ServerCertificate] Returns a reference to the named
+      #   server certificate.
+      def [] name
+        ServerCertificate.new(name, :config => config)
+      end
+
+      # Yields once for each server certificate
+      #
+      # You can limit the number of certificates yielded using
+      # +:limit+ and +:path_prefix+.
+      #
+      # @param [Hash] options
+      #
+      # @option options [String] :path_prefix ('/') A path prefix that
+      #   filters according to the path of the certificate.
+      #
+      # @option options [Integer] :limit The maximum number of
+      #   certificates to yield.
+      #
+      # @option options [Integer] :batch_size The maximum number of
+      #   certificates to retrieve in each service request.
+      #
+      # @yieldparam [ServerCertificate] certificate
+      # @return [nil]
+      def each options = {}, &block
+        super(options, &block)
+      end
+
+      # Returns an enumerable object for this collection.  This can be
+      # useful if you want to call an enumerable method that does
+      # not accept options (e.g. +collect+, +first+, etc).
+      #
+      #   certificates.enumerator(:path_prefix => '/production').
+      #     collect(&:name)
+      #
+      # @param (see #each)
+      # @option (see #each)
+      # @return [Enumerator]
+      def enumerator options = {}
+        super(options)
+      end
+
+      # @private
+      protected
+      def each_item(response, &block)
+        response.server_certificate_metadata_list.each do |sc|
+          certificate = ServerCertificate.new_from(:list_server_certificates,
+                                                   sc,
+                                                   sc.server_certificate_name,
+                                                   :config => config)
+          yield(certificate)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/aws/iam/signing_certificate.rb

@@ -0,0 +1,171 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/iam/resource'
+
+module AWS
+  class IAM
+
+    # Signing certificates can be activated and deactivated.
+    # By default, newly-uploaded certifictes are active.
+    #
+    #   certificate = iam.signing_certificates.upload(cert_body)
+    #   certificate.status
+    #   #=> :active
+    #
+    #   certificate.deactivate!
+    #   certificate.active?
+    #   #=> false
+    #
+    # == Contents
+    #
+    # You can access the certificate contents you uploaded:
+    #
+    #   > puts certificate.contents
+    #   -----BEGIN CERTIFICATE-----
+    #   MIICdzCCAeCgAwIBAgIFGS4fY6owDQYJKoZIhvcNAQEFBQAwUzELMAkGA1UEBhMC
+    #   ......
+    #   Glli79yh87PRi0vNDlFEoHXNynkvC/c4TiWruZ4haM9BR9EdWr1DBNNu73ui093K
+    #   F9TbdXSWdgMl7E0=
+    #   -----END CERTIFICATE-----
+    #
+    # == User
+    #
+    # A certificate can also return the user it belongs to.  If the certificate
+    # belongs to the AWS account, then {#user} will return +nil+.
+    #
+    #   user = iam.users['someuser'].signing_certificates.first
+    #   user.name
+    #   #=> 'someuser'
+    #
+    # @attr_reader [String] contents Returns the contents of this 
+    #   signing certificate.
+    #
+    # @attr_reader [Symbol] status The status of this signing
+    #   certificate.  Status may be +:active+ or +:inactive+.
+    #
+    class SigningCertificate < Resource
+
+      # @param [String] certificate_id The id of the signing certificate.
+      # @param [Hash] options
+      # @param [User] :user The user this signing certificate belongs to.
+      def initialize certificate_id, options = {}
+        @id = certificate_id
+        @user = options[:user]
+        @user ? super(@user, options) : super(options)
+      end
+
+      # @return [String] Returns the signing certificate's ID.
+      attr_reader :id
+
+      # @return [User,nil] Returns the user this cerficiate belongs to.  
+      #   Returns +nil+ if the cerficiate is a root credential for the 
+      #   account.  If the configured credentials belong to an IAM user, 
+      #   then that user is the implied owner.
+      attr_reader :user
+
+      attribute :contents, :as => :certificate_body, :static => true
+
+      mutable_attribute :status, :to_sym => true
+
+      protected :status=
+
+      populates_from(
+        :upload_signing_certificate, 
+        :update_signing_certificate
+      ) do |resp|
+        resp.certificate if matches_response_object?(resp.certificate)
+      end
+
+      populates_from(:list_signing_certificates) do |resp|
+        resp.certificates.find {|c| matches_response_object?(c) }
+      end
+
+      # @return [String,nil] Returns the name of the user this certificate
+      #   belogns to.  If the certificate belongs to the account, +nil+ is
+      #   returned.
+      def user_name
+        @user ? @user.name : nil
+      end
+
+      # @return [Boolean] Returns true if this signing certificate is active.
+      def active?
+        status == :active
+      end
+
+      # @return [Boolean] Returns true if this signing certificate is inactive.
+      def inactive?
+        status == :inactive
+      end
+
+      # Activates this signing cerificate.
+      #
+      # @example
+      #   signing_certificate.activate!
+      #   signing_certificate.status
+      #   # => :active
+      #
+      # @return [nil]
+      def activate!
+        self.status = 'Active'
+        nil
+      end
+
+      # Deactivates this signing cerificate.
+      #
+      # @example
+      #   signing_certificate.deactivate!
+      #   signing_certificate.status
+      #   # => :inactive
+      #
+      # @return [nil]
+      def deactivate!
+        self.status = 'Inactive'
+        nil
+      end
+
+      # Deletes the signing certificate.
+      def delete
+        client.delete_signing_certificate(resource_options)
+        nil
+      end
+
+      # @private
+      protected
+      def resource_identifiers
+        identifiers = []
+        identifiers << [:certificate_id, id]
+        identifiers << [:user_name, user.name] if user
+        identifiers
+      end
+
+      # IAM does not provide a request for "get signing certificate".  
+      # Also note, we do not page the response. This is because 
+      # restrictions on how many certificates an account / user may 
+      # have is fewer than one page of results.
+      # @private
+      protected
+      def get_resource attribute
+        options = user ? { :user_name => user.name } : {}
+        client.list_signing_certificates(options)
+      end
+
+      # @private
+      protected
+      def matches_response_object? obj
+        user_name = obj.respond_to?(:user_name) ? obj.user_name : nil
+        obj.certificate_id == self.id and user_name == self.user_name
+      end
+
+    end
+  end
+end

data/lib/aws/iam/signing_certificate_collection.rb

@@ -0,0 +1,134 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/iam/collection'
+require 'aws/iam/signing_certificate'
+
+module AWS
+  class IAM
+
+    # This is the primary interface for uploading X.509 signing certificates
+    # to an AWS account or an IAM user.
+    #
+    #   iam = AWS::IAM.new
+    #
+    #   # upload a certificate for the AWS account:
+    #   iam.signing_certificates.upload(<<-CERT)
+    #   -----BEGIN CERTIFICATE-----
+    #   MIICdzCCAeCgAwIBAgIFGS4fY6owDQYJKoZIhvcNAQEFBQAwUzELMAkGA1UEBhMC
+    #   ......
+    #   Glli79yh87PRi0vNDlFEoHXNynkvC/c4TiWruZ4haM9BR9EdWr1DBNNu73ui093K
+    #   F9TbdXSWdgMl7E0=
+    #   -----END CERTIFICATE-----
+    #   CERT
+    #
+    # If you want to work with an IAM user's certificates just use the
+    # signing certificate interface on a user:
+    #
+    #   user = iam.users['someuser']
+    #   user.signing_certificates.upload(cert_body)
+    #
+    class SigningCertificateCollection
+
+      include Collection
+
+      # @param [Hash] options
+      # @option options [User] :user (nil) When +:user+ is provided the
+      #   collection will represents the signing certificates belonging only
+      #   to that user.  When +:user+ is omitted the collection will manage
+      #   root credentials on the AWS account (instead those belonging to a
+      #   particular user).
+      def initialize options = {}
+        @user = options[:user]
+        @user ? super(@user, options) : super(options)
+      end
+
+      # @return [User,nil] Returns the user this collection belongs to.  
+      #   Returns +nil+ if the collection represents the root credentials
+      #   for the account.  If the configured credentials belong to an 
+      #   IAM user, then that user is the implied owner.
+      attr_reader :user
+
+      # @param [String] certificate_body The contents of the signing 
+      #   certificate.
+      # @return [SigningCertificate] Returns the newly created signing
+      #   certificate.
+      def upload certificate_body
+
+        options = {}
+        options[:certificate_body] = certificate_body
+        options[:user_name] = user.name if user
+
+        resp = client.upload_signing_certificate(options)
+
+        SigningCertificate.new_from(:upload_signing_certificate, 
+          resp.certificate, resp.certificate.certificate_id, new_options)
+
+      end
+
+      alias_method :create, :upload
+
+      # @param [String] certificate_id The ID of the signing certificate.
+      # @return [SigningCertificate] Returns a reference to the signing
+      #   certificate with the given certificate ID.
+      def [] certificate_id
+        SigningCertificate.new(certificate_id.to_s, new_options)
+      end
+
+      # Deletes all of the signing certificates from this collection.
+      # @return [nil]
+      def clear
+        each do |certificate|
+          certificate.delete
+        end
+        nil
+      end
+
+      # Yields once for each signing certificate.
+      #
+      # You can limit the number of certificates yielded using +:limit+.
+      #
+      # @param [Hash] options
+      # @option options [Integer] :limit The maximum number of certificates
+      #   to yield.
+      # @option options [Integer] :batch_size The maximum number of 
+      #   certificates received each service reqeust.
+      # @yieldparam [SigningCertificate] signing_certificate 
+      # @return [nil]
+      def each options = {}, &block
+        each_options = options.dup
+        each_options[:user_name] = user.name if user
+        super(each_options, &block)
+      end
+
+      # @private
+      protected
+      def each_item response, &block
+        response.certificates.each do |item|
+
+          cert = SigningCertificate.new_from(:list_signing_certificates, 
+            item, item.certificate_id, new_options)
+
+          yield(cert)
+
+        end
+      end
+
+      # @private
+      protected
+      def new_options
+        user ? { :user => user } : { :config => config }
+      end
+
+    end
+  end
+end