ocsp: Improve documentation for ParseResponse and ParseResponseForCert
This change clarifies the behaviors of ParseResponse and ParseResponseForCert,
particularly when parsing responses that contain multiple certificate statuses.
Fixes golang/go#30651
Change-Id: Ia632c8c2a69d1b0c17d71f9f9dcb59ddb0be401b
GitHub-Last-Rev: 481f613438c91521fd90078cc0915cf01cf44b4e
GitHub-Pull-Request: golang/crypto#122
Reviewed-on: https://go-review.googlesource.com/c/crypto/+/220353
Reviewed-by: Katie Hockman <katie@golang.org>
Trust: Roland Shoemaker <roland@golang.org>
diff --git a/ocsp/ocsp.go b/ocsp/ocsp.go
index d297ac9..9d3fffa 100644
--- a/ocsp/ocsp.go
+++ b/ocsp/ocsp.go
@@ -445,10 +445,18 @@
}, nil
}
-// ParseResponse parses an OCSP response in DER form. It only supports
-// responses for a single certificate. If the response contains a certificate
-// then the signature over the response is checked. If issuer is not nil then
-// it will be used to validate the signature or embedded certificate.
+// ParseResponse parses an OCSP response in DER form. The response must contain
+// only one certificate status. To parse the status of a specific certificate
+// from a response which may contain multiple statuses, use ParseResponseForCert
+// instead.
+//
+// If the response contains an embedded certificate, then that certificate will
+// be used to verify the response signature. If the response contains an
+// embedded certificate and issuer is not nil, then issuer will be used to verify
+// the signature on the embedded certificate.
+//
+// If the response does not contain an embedded certificate and issuer is not
+// nil, then issuer will be used to verify the response signature.
//
// Invalid responses and parse failures will result in a ParseError.
// Error responses will result in a ResponseError.
@@ -456,14 +464,11 @@
return ParseResponseForCert(bytes, nil, issuer)
}
-// ParseResponseForCert parses an OCSP response in DER form and searches for a
-// Response relating to cert. If such a Response is found and the OCSP response
-// contains a certificate then the signature over the response is checked. If
-// issuer is not nil then it will be used to validate the signature or embedded
-// certificate.
-//
-// Invalid responses and parse failures will result in a ParseError.
-// Error responses will result in a ResponseError.
+// ParseResponseForCert acts identically to ParseResponse, except it supports
+// parsing responses that contain multiple statuses. If the response contains
+// multiple statuses and cert is not nil, then ParseResponseForCert will return
+// the first status which contains a matching serial, otherwise it will return an
+// error. If cert is nil, then the first status in the response will be returned.
func ParseResponseForCert(bytes []byte, cert, issuer *x509.Certificate) (*Response, error) {
var resp responseASN1
rest, err := asn1.Unmarshal(bytes, &resp)
