acme/api: Brush up documentation on key-change

Add more specific wording describing what a 501 means and add more color
explaining how official vs unofficial error types should be handled.

acme/api/handler.go

@@ -67,7 +67,6 @@ func (h *Handler) Route(r api.Router) {
 	r.MethodFunc("POST", getLink(acme.AuthzLink, "{provisionerID}", false, nil, "{authzID}"), extractPayloadByKid(h.isPostAsGet(h.GetAuthz)))
 	r.MethodFunc("POST", getLink(acme.ChallengeLink, "{provisionerID}", false, nil, "{chID}"), extractPayloadByKid(h.GetChallenge))
 	r.MethodFunc("POST", getLink(acme.CertificateLink, "{provisionerID}", false, nil, "{certID}"), extractPayloadByKid(h.isPostAsGet(h.GetCertificate)))
-
 }
 
 // GetNonce just sets the right header since a Nonce is added to each response
@@ -91,7 +90,8 @@ func (h *Handler) GetDirectory(w http.ResponseWriter, r *http.Request) {
 	api.JSON(w, dir)
 }
 
-// NotImplemented returns a 501. This is a place holder for future functionality.
+// NotImplemented returns a 501 and is generally a placeholder for functionality which
+// MAY be added at some point in the future but is not in any way a guarantee of such.
 func (h *Handler) NotImplemented(w http.ResponseWriter, r *http.Request) {
 	api.WriteError(w, acme.NotImplemented(nil).ToACME())
 }

acme/errors.go

@@ -412,9 +412,15 @@ func (e *Error) Cause() error {
 	return e.Err
 }
 
-// Official returns true if this error is registered with the IETF.
+// Official returns true if this error's type is listed in §6.7 of RFC 8555.
+// Error types in §6.7 are registered under IETF urn namespace:
 //
-// The RFC says:
+//   "urn:ietf:params:acme:error:"
+//
+// and should include the namespace as a prefix when appearing as a problem
+// document.
+//
+// RFC 8555 also says:
 //
 //   This list is not exhaustive.  The server MAY return errors whose
 //   "type" field is set to a URI other than those defined above.  Servers
@@ -422,11 +428,15 @@ func (e *Error) Cause() error {
 //   appropriate IANA registry (see Section 9.6).  Clients SHOULD display
 //   the "detail" field of all errors.
 //
+// In this case Official returns `false` so that a different namespace can
+// be used.
 func (e *Error) Official() bool {
 	return e.Type != notImplemented
 }
 
 // ToACME returns an acme representation of the problem type.
+// For official errors, the IETF ACME namespace is prepended to the error type.
+// For our own errors, we use an (yet) unregistered smallstep acme namespace.
 func (e *Error) ToACME() *AError {
 	prefix := "urn:step:acme:error"
 	if e.Official() {