TrueCloudLab/certificates
16
0
Fork 2
Code Issues 1 Pull requests 1 Releases Activity Actions

acme/api: Brush up documentation on key-change

Browse source 
Add more specific wording describing what a 501 means and add more color
explaining how official vs unofficial error types should be handled.
This commit is contained in:
David Cowden 2020-05-27 17:08:47 -07:00
parent b26e6e42b3
commit a26b5f322d
2 changed files with 14 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
acme/api/handler.go
View file

@ -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.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.ChallengeLink, "{provisionerID}", false, nil, "{chID}"), extractPayloadByKid(h.GetChallenge))
r.MethodFunc("POST", getLink(acme.CertificateLink, "{provisionerID}", false, nil, "{certID}"), extractPayloadByKid(h.isPostAsGet(h.GetCertificate))) 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 // 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) 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) { func (h *Handler) NotImplemented(w http.ResponseWriter, r *http.Request) {
api.WriteError(w, acme.NotImplemented(nil).ToACME()) api.WriteError(w, acme.NotImplemented(nil).ToACME())
} }

14
acme/errors.go
View file

@ -412,9 +412,15 @@ func (e *Error) Cause() error {
return e.Err 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 // This list is not exhaustive. The server MAY return errors whose
// "type" field is set to a URI other than those defined above. Servers // "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 // appropriate IANA registry (see Section 9.6). Clients SHOULD display
// the "detail" field of all errors. // 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 { func (e *Error) Official() bool {
return e.Type != notImplemented return e.Type != notImplemented
} }
// ToACME returns an acme representation of the problem type. // 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 { func (e *Error) ToACME() *AError {
prefix := "urn:step:acme:error" prefix := "urn:step:acme:error"
if e.Official() { if e.Official() {