Certificate Transparency TLS extension patch for NSS

net/third_party/nss/ssl/ssl.h

 /*
  * This file contains prototypes for the public SSL functions.
  *
  * This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 #ifndef __ssl_h_
 #define __ssl_h_
 
@@ skipping 148 matching lines @@
  * configurations) prevent the same attack by prepending an empty
  * application_data record to every application_data record they send; we do
  * not do that because some implementations cannot handle empty
  * application_data records. Also, we only split application_data records and
  * not other types of records, because some implementations will not accept
  * fragmented records of some other types (e.g. some versions of NSS do not
  * accept fragmented alerts).
  */
 #define SSL_CBC_RANDOM_IV 23
 #define SSL_ENABLE_OCSP_STAPLING       24 /* Request OCSP stapling (client) */
+/* Request Signed Certificate Timestamps via TLS extension (client) */
+#define SSL_ENABLE_SIGNED_CERT_TIMESTAMPS 25
 
 #ifdef SSL_DEPRECATED_FUNCTION 
 /* Old deprecated function names */
 SSL_IMPORT SECStatus SSL_Enable(PRFileDesc *fd, int option, PRBool on);
 SSL_IMPORT SECStatus SSL_EnableDefault(int option, PRBool on);
 #endif
 
 /* New function names */
 SSL_IMPORT SECStatus SSL_OptionSet(PRFileDesc *fd, PRInt32 option, PRBool on);
 SSL_IMPORT SECStatus SSL_OptionGet(PRFileDesc *fd, PRInt32 option, PRBool *on);
@@ skipping 283 matching lines @@
  * You must set the SSL_ENABLE_OCSP_STAPLING option to enable OCSP stapling.
  * to be provided by a server.
  *
  * libssl does not do any validation of the OCSP response itself; the
  * authenticate certificate hook is responsible for doing so. The default
  * authenticate certificate hook, SSL_AuthCertificate, does not implement
  * any OCSP stapling funtionality, but this may change in future versions.
  */
 SSL_IMPORT const SECItemArray * SSL_PeerStapledOCSPResponses(PRFileDesc *fd);
 
+/* SSL_PeerSignedCertTimestamps returns the signed_certificate_timestamp
+ * extension data provided by the TLS server. The return value is a pointer

[wtc, 2013/11/08 19:51:31]

Should we mention the extension data is a SignedCertificateTimestampList?

[ekasper, 2013/11/18 17:47:18]

Can't hurt! Done.

+ * to an internal SECItem that contains the returned response; it is only valid
+ * until the callback function that calls SSL_PeerSignedCertTimestamps returns.

[wtc, 2013/11/08 19:51:31]

Please be explicit which callback function you are referring to. I guess it is
the SSLAuthCertificate callback?

[ekasper, 2013/11/18 17:47:18]

I believe the precise callback doesn't matter but normally you'd call it from
AuthCertificate or HandshakeCallback so I've made that explicit. This is similar
to how PeerStapledOCSPResponses are handled (tstclnt calls this from both
hooks).

+ *
+ * If no Signed Certificate Timestamps were given by the server then the result
+ * will be empty. If there was an error, then the result will be NULL.
+ *
+ * You must set the SSL_ENABLE_SIGNED_CERT_TIMESTAMPS option to enable Signed
+ * Certificate Timestamps to be provided by a server.

[wtc, 2013/11/08 19:51:31]

Nit: change "to enable Signed Certificate Timestamps to be provided by a server"
to "to request Signed Certificate Timestamps from a server" or "to indicate
support for Signed Certificate Timestamps to a server".

[ekasper, 2013/11/18 17:47:18]

That's much better, thanks. Done. I chose "indicate support" because the server
is not obliged to honour the request.

+ *
+ * libssl does not do any parsing or validation of the response itself.
+ */
+SSL_IMPORT const SECItem * SSL_PeerSignedCertTimestamps(PRFileDesc *fd);
+
 /* SSL_SetStapledOCSPResponses stores an array of one or multiple OCSP responses
  * in the fd's data, which may be sent as part of a server side cert_status
  * handshake message. Parameter |responses| is for the server certificate of
  * the key exchange type |kea|.
  * The function will duplicate the responses array.
  */
 SSL_IMPORT SECStatus
 SSL_SetStapledOCSPResponses(PRFileDesc *fd, const SECItemArray *responses,
                             SSLKEAType kea);
 
@@ skipping 669 matching lines @@
  * should continue using the connection. If the application passes a non-zero
  * value for second argument (error), or if SSL_AuthCertificateComplete returns
  * anything other than SECSuccess, then the application should close the
  * connection.
  */
 SSL_IMPORT SECStatus SSL_AuthCertificateComplete(PRFileDesc *fd,
                                                  PRErrorCode error);
 SEC_END_PROTOS
 
 #endif /* __ssl_h_ */