(#22807) Document certificate_status endpoint

api/docs/http_api_index.md

@@ -3,6 +3,7 @@ Services
 
 * {file:api/docs/http_certificate.md Certificate}
 * {file:api/docs/http_certificate_request.md Certificate Signing Requests}
+* {file:api/docs/http_certificate_status.md Certificate Status}
 * {file:api/docs/http_certificate_revocation_list.md Certificate Revocation List}
 * {file:api/docs/http_catalog.md Catalog}
 * {file:api_docs/http_facts.md Facts}
@@ -15,7 +16,6 @@ To be documented:
 
 * node
 * file_bucket_file
-* certificate_status
 * resource
 * key
 * status

api/docs/http_certificate_status.md

@@ -0,0 +1,112 @@
+Certificate Status
+===============
+
+The `certificate status` endpoint allows a client to read or alter the
+status of a certificate or pending certificate request. It is only
+useful on the CA.
+
+In all requests the `:environment` must be given, but it has no bearing
+on the request. Certificates are global.
+
+Find
+----
+
+    GET /:environment/certificate_status/:certname
+    Accept: pson
+
+Retrieve information about the specified certificate. Similar to puppet
+cert --list :certname.
+
+Search
+-----
+
+    GET /:environment/certificate_statuses/no_key
+    Accept: pson
+
+Retrieve information about all known certificates. Similar to puppet
+cert --list --all.
+
+Save
+----
+
+    PUT /:environment/certificate_status/:certname
+    Content-Type: text/pson
+
+Change the status of the specified certificate. The desired state
+is sent in the body of the PUT request as a one-item PSON hash; the two
+allowed complete hashes are `{"desired_state":"signed"}` (for signing a
+certificate signing request; similar to `puppet cert --sign`) and
+`{"desired_state":"revoked"}` (for revoking a certificate; similar to
+puppet cert --revoke).
+
+When revoking certificates, you may wish to use a DELETE request
+instead, which will also clean up other info about the host.
+
+
+Delete
+-----
+
+    DELETE /:environment/certificate_status/:hostname
+    Accept: pson
+
+Cause the certificate authority to discard all SSL information regarding
+a host (including any certificates, certificate requests, and keys).
+This does not revoke the certificate if one is present; if you wish to
+emulate the behavior of `puppet cert --clean`, you must PUT a
+`desired_state` of `revoked` before deleting the host’s SSL information.
+
+If the deletion was successful, it returns a string listing the deleted
+classes like
+
+    "Deleted for myhost: Puppet::SSL::Certificate, Puppet::SSL::Key"
+
+Otherwise it returns
+
+    "Nothing was deleted"
+
+### Supported HTTP Methods
+
+This endpoint is disabled in the default configuration. It is
+recommended to be careful with this endpoint, as it can allow control
+over the certificates used by the puppet master.
+
+GET, PUT, DELETE
+
+
+### Supported Format
+
+Accept: pson
+
+This endpoint can produce yaml as well, but the returned data is
+incomplete.
+
+### Examples
+
+#### Certificate information
+
+    GET /env/certificate_status/mycertname
+
+    HTTP/1.1 200 OK 
+    Content-Type: text/pson
+
+    {
+      "name":"mycertname",
+      "state":"signed",
+      "fingerprint":"A6:44:08:A6:38:62:88:5B:32:97:20:49:8A:4A:4A:AD:65:C3:3E:A2:4C:30:72:73:02:C5:F3:D4:0E:B7:FC:2F",
+      "fingerprints":{
+        "default":"A6:44:08:A6:38:62:88:5B:32:97:20:49:8A:4A:4A:AD:65:C3:3E:A2:4C:30:72:73:02:C5:F3:D4:0E:B7:FC:2F",
+        "SHA1":"77:E6:5A:7E:DD:83:78:DC:F8:51:E3:8B:12:71:F4:57:F1:C2:34:AE",
+        "SHA256":"A6:44:08:A6:38:62:88:5B:32:97:20:49:8A:4A:4A:AD:65:C3:3E:A2:4C:30:72:73:02:C5:F3:D4:0E:B7:FC:2F",
+        "SHA512":"CA:A0:8C:B9:FE:9D:C2:72:18:57:08:E9:4B:11:B7:BC:4E:F7:52:C8:9C:76:03:45:B4:B6:C5:D2:DC:E8:79:43:D7:71:1F:5C:97:FA:B2:F3:ED:AE:19:BD:A9:3B:DB:9F:A5:B4:8D:57:3F:40:34:29:50:AA:AA:0A:93:D8:D7:54"
+      },
+      "dns_alt_names":["DNS:puppet","DNS:mycertname"]
+    }
+
+
+
+Schema
+-----
+
+Find and search operations return Puppet::SSL::Host objects which
+conform to the json schema at {file:api/schemas/host.json
+api/schemas/host.json}.

api/schemas/host.json

@@ -0,0 +1,44 @@
+{
+    "$schema":     "http://json-schema.org/draft-04/schema#",
+    "title":       "Host",
+    "description": "SSL Host information",
+    "type":        "object",
+    "properties": {
+        "name": {
+            "type": "string"
+        },
+        "state": {
+            "type": "string",
+            "enum": [
+                "requested",
+                "signed",
+                "revoked"
+            ]
+        },
+        "desired_state": {
+            "type": "string",
+            "enum": [
+                "signed",
+                "revoked"
+            ]
+        },
+        "fingerprint": {
+            "type": "string"
+        },
+        "fingerprints": {
+            "type": "object",
+            "patternProperties": {
+                "^[A-Za-z0-9_]*$": {}
+            },
+            "additionalProperties": false
+        },
+        "dns_alt_names": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            }
+        }
+    },
+    "required": ["name", "state", "fingerprint", "fingerprints", "dns_alt_names"],
+    "additionalProperties": false
+}

spec/unit/ssl/host_spec.rb

@@ -9,9 +9,24 @@ def base_pson_comparison(result, pson_hash)
   result["state"].should       == pson_hash["desired_state"]
 end
 
+# the json-schema gem doesn't support windows
+if not Puppet.features.microsoft_windows?
+  HOST_SCHEMA = JSON.parse(File.read(File.join(File.dirname(__FILE__), '../../../api/schemas/host.json')))
+
+  describe "host schema" do
+    it "should validate against the json meta-schema" do
+      JSON::Validator.validate!(JSON_META_SCHEMA, HOST_SCHEMA)
+    end
+  end
+end
+
 describe Puppet::SSL::Host do
   include PuppetSpec::Files
 
+  def validate_as_json(host)
+    JSON::Validator.validate!(HOST_SCHEMA, host.to_pson)
+  end
+
   before do
     Puppet::SSL::Host.indirection.terminus_class = :file
 
@@ -823,23 +838,28 @@ def base_pson_comparison(result, pson_hash)
       let(:host) do
         Puppet::SSL::Host.new("bazinga")
       end
-      
+
       let(:pson_hash) do
         {
           "fingerprint"   => host.certificate_request.fingerprint,
           "desired_state" => 'requested',
           "name"          => host.name
         }
       end
-      
+
       it "should be able to identify a host with an unsigned certificate request" do
         host.generate_certificate_request
 
         result = PSON.parse(Puppet::SSL::Host.new(host.name).to_pson)
-        
+
         base_pson_comparison result, pson_hash
       end
-
+
+      it "should validate against the schema", :unless => Puppet.features.microsoft_windows? do
+        host.generate_certificate_request
+        validate_as_json(host)
+      end
+
       describe "explicit fingerprints" do
         [:SHA1, :SHA256, :SHA512].each do |md|
           it "should include #{md}" do
@@ -854,7 +874,7 @@ def base_pson_comparison(result, pson_hash)
           end
         end
       end
-      
+
       describe "dns_alt_names" do
         describe "when not specified" do
           it "should include the dns_alt_names associated with the certificate" do
@@ -867,22 +887,28 @@ def base_pson_comparison(result, pson_hash)
           end
         end
 
-        [ "", 
+        [ "",
           "test, alt, names"
         ].each do |alt_names|
           describe "when #{alt_names}" do
-            it "should include the dns_alt_names associated with the certificate" do
+            before(:each) do
               host.generate_certificate_request :dns_alt_names => alt_names
+            end
+
+            it "should include the dns_alt_names associated with the certificate" do
               pson_hash["desired_alt_names"] = host.certificate_request.subject_alt_names
 
               result = PSON.parse(Puppet::SSL::Host.new(host.name).to_pson)
               base_pson_comparison result, pson_hash
               result["dns_alt_names"].should == pson_hash["desired_alt_names"]
             end
+
+            it "should validate against the schema", :unless => Puppet.features.microsoft_windows? do
+              validate_as_json(host)
+            end
           end
         end
       end
-
 
       it "should be able to identify a host with a signed certificate" do
         host.generate_certificate_request