quic: expose QUIC certificates as JS X509Certificate, not raw handles

Signed-off-by: Tim Perry <pimterry@gmail.com>
PR-URL: #63191
Backport-PR-URL: #64675
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ethan Arrowood <ethan@arrowood.dev>
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>

Author: pimterry

doc/api/quic.md

@@ -1404,23 +1404,24 @@ what this endpoint advertises to the peer as its own maximum.
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The local certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or no certificate is available.
+The local certificate as a [`crypto.X509Certificate`][] instance. Server
+sessions return the certificate configured for the negotiated SNI host.
+Client sessions return `undefined` unless a client certificate was sent.
+Returns `undefined` if the session is destroyed.
 
 ### `session.peerCertificate`
 
 <!-- YAML
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The peer's certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or the peer did not present a certificate.
+The peer's certificate as a [`crypto.X509Certificate`][] instance. Returns
+`undefined` if the peer did not present a certificate or the session is
+destroyed.
 
 ### `session.ephemeralKeyInfo`
 
@@ -4422,6 +4423,7 @@ throughput issues caused by flow control.
 [`application.enableConnectProtocol`]: #sessionoptionsapplication
 [`application.enableDatagrams`]: #sessionoptionsapplication
 [`application.qpackMaxDTableCapacity`]: #sessionoptionsapplication
+[`crypto.X509Certificate`]: crypto.md#class-x509certificate
 [`endpoint.busy`]: #endpointbusy
 [`endpoint.maxConnectionsPerHost`]: #endpointmaxconnectionsperhost
 [`endpoint.maxConnectionsTotal`]: #endpointmaxconnectionstotal

lib/internal/quic/quic.js

@@ -152,6 +152,10 @@ const {
  isKeyObject,
 }=require('internal/crypto/keys');
 
+const{
+ InternalX509Certificate,
+}=require('internal/crypto/x509');
+
 const{
  FileHandle,
 kHandle: kFileHandle,
@@ -3180,24 +3184,37 @@ class QuicSession {
 }
 
 /**
- * The local certificate as an object, or undefined if not available.
- * @type {object|undefined}
+ * The local certificate as a {@link crypto.X509Certificate}, or undefined
+ * if no local certificate is available. Server sessions return their
+ * configured certificate; client sessions return undefined unless a
+ * client certificate was sent.
+ * @type {crypto.X509Certificate|undefined}
  */
 getcertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.certificate??=this.#handle.getCertificate();
+if(this.#inner.certificate===undefined){
+consthandle=this.#handle.getCertificate();
+this.#inner.certificate=handle ? newInternalX509Certificate(handle) : null;
+}
+returnthis.#inner.certificate??undefined;
 }
 
 /**
- * The peer's certificate as an object, or undefined if the peer did
- * not present a certificate or the session is destroyed.
- * @type {object|undefined}
+ * The peer's certificate as a {@link crypto.X509Certificate}, or undefined
+ * if the peer did not present a certificate or the session is destroyed.
+ * @type {crypto.X509Certificate|undefined}
  */
 getpeerCertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.peerCertificate??=this.#handle.getPeerCertificate();
+if(this.#inner.peerCertificate===undefined){
+consthandle=this.#handle.getPeerCertificate();
+this.#inner.peerCertificate=handle ?
+newInternalX509Certificate(handle) :
+null;
+}
+returnthis.#inner.peerCertificate??undefined;
 }
 
 /**

test/parallel/test-quic-session-properties.mjs

@@ -11,11 +11,20 @@
 // All three cached.
 // All three return undefined after destroy.
 
-import{hasQuic,skip,mustCall}from'../common/index.mjs';
+import{hasQuic,skip,mustCall,hasCrypto}from'../common/index.mjs';
+import*asfixturesfrom'../common/fixtures.mjs';
 importassertfrom'node:assert';
 
 const{ ok, strictEqual }=assert;
 
+if(!hasCrypto)
+skip('missing crypto');
+
+const{ X509Certificate }=awaitimport('node:crypto');
+
+// The QUIC test helpers configure both sides with the agent1 fixture cert,
+constexpectedCert=newX509Certificate(fixtures.readKey('agent1-cert.pem'));
+
 if(!hasQuic){
 skip('QUIC is not enabled');
 }
@@ -38,7 +47,10 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 // Own certificate.
 constcert=serverSession.certificate;
-ok(cert);
+ok(certinstanceofX509Certificate);
+strictEqual(cert.subject,expectedCert.subject);
+strictEqual(cert.issuer,expectedCert.issuer);
+strictEqual(cert.fingerprint256,expectedCert.fingerprint256);
 
 // Peer certificate (client's cert — not set in this
 // test since we don't use verifyClient, so it's undefined).
@@ -65,7 +77,10 @@ strictEqual(clientSession.path, path);
 
 // Peer certificate (server's cert).
 constpeerCert=clientSession.peerCertificate;
-ok(peerCert);
+ok(peerCertinstanceofX509Certificate);
+strictEqual(peerCert.subject,expectedCert.subject);
+strictEqual(peerCert.issuer,expectedCert.issuer);
+strictEqual(peerCert.fingerprint256,expectedCert.fingerprint256);
 
 // Ephemeral key info (client only).
 constkeyInfo=clientSession.ephemeralKeyInfo;

doc/api/quic.md

@@ -1404,23 +1404,24 @@ what this endpoint advertises to the peer as its own maximum.
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The local certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or no certificate is available.
+The local certificate as a [`crypto.X509Certificate`][] instance. Server
+sessions return the certificate configured for the negotiated SNI host.
+Client sessions return `undefined` unless a client certificate was sent.
+Returns `undefined` if the session is destroyed.
 
 ### `session.peerCertificate`
 
 <!-- YAML
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The peer's certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or the peer did not present a certificate.
+The peer's certificate as a [`crypto.X509Certificate`][] instance. Returns
+`undefined` if the peer did not present a certificate or the session is
+destroyed.
 
 ### `session.ephemeralKeyInfo`
 
@@ -4422,6 +4423,7 @@ throughput issues caused by flow control.
 [`application.enableConnectProtocol`]: #sessionoptionsapplication
 [`application.enableDatagrams`]: #sessionoptionsapplication
 [`application.qpackMaxDTableCapacity`]: #sessionoptionsapplication
+[`crypto.X509Certificate`]: crypto.md#class-x509certificate
 [`endpoint.busy`]: #endpointbusy
 [`endpoint.maxConnectionsPerHost`]: #endpointmaxconnectionsperhost
 [`endpoint.maxConnectionsTotal`]: #endpointmaxconnectionstotal

lib/internal/quic/quic.js

@@ -152,6 +152,10 @@ const {
  isKeyObject,
 }=require('internal/crypto/keys');
 
+const{
+ InternalX509Certificate,
+}=require('internal/crypto/x509');
+
 const{
  FileHandle,
 kHandle: kFileHandle,
@@ -3180,24 +3184,37 @@ class QuicSession {
 }
 
 /**
- * The local certificate as an object, or undefined if not available.
- * @type {object|undefined}
+ * The local certificate as a {@link crypto.X509Certificate}, or undefined
+ * if no local certificate is available. Server sessions return their
+ * configured certificate; client sessions return undefined unless a
+ * client certificate was sent.
+ * @type {crypto.X509Certificate|undefined}
  */
 getcertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.certificate??=this.#handle.getCertificate();
+if(this.#inner.certificate===undefined){
+consthandle=this.#handle.getCertificate();
+this.#inner.certificate=handle ? newInternalX509Certificate(handle) : null;
+}
+returnthis.#inner.certificate??undefined;
 }
 
 /**
- * The peer's certificate as an object, or undefined if the peer did
- * not present a certificate or the session is destroyed.
- * @type {object|undefined}
+ * The peer's certificate as a {@link crypto.X509Certificate}, or undefined
+ * if the peer did not present a certificate or the session is destroyed.
+ * @type {crypto.X509Certificate|undefined}
  */
 getpeerCertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.peerCertificate??=this.#handle.getPeerCertificate();
+if(this.#inner.peerCertificate===undefined){
+consthandle=this.#handle.getPeerCertificate();
+this.#inner.peerCertificate=handle ?
+newInternalX509Certificate(handle) :
+null;
+}
+returnthis.#inner.peerCertificate??undefined;
 }
 
 /**

test/parallel/test-quic-session-properties.mjs

@@ -11,11 +11,20 @@
 // All three cached.
 // All three return undefined after destroy.
 
-import{hasQuic,skip,mustCall}from'../common/index.mjs';
+import{hasQuic,skip,mustCall,hasCrypto}from'../common/index.mjs';
+import*asfixturesfrom'../common/fixtures.mjs';
 importassertfrom'node:assert';
 
 const{ ok, strictEqual }=assert;
 
+if(!hasCrypto)
+skip('missing crypto');
+
+const{ X509Certificate }=awaitimport('node:crypto');
+
+// The QUIC test helpers configure both sides with the agent1 fixture cert,
+constexpectedCert=newX509Certificate(fixtures.readKey('agent1-cert.pem'));
+
 if(!hasQuic){
 skip('QUIC is not enabled');
 }
@@ -38,7 +47,10 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 // Own certificate.
 constcert=serverSession.certificate;
-ok(cert);
+ok(certinstanceofX509Certificate);
+strictEqual(cert.subject,expectedCert.subject);
+strictEqual(cert.issuer,expectedCert.issuer);
+strictEqual(cert.fingerprint256,expectedCert.fingerprint256);
 
 // Peer certificate (client's cert — not set in this
 // test since we don't use verifyClient, so it's undefined).
@@ -65,7 +77,10 @@ strictEqual(clientSession.path, path);
 
 // Peer certificate (server's cert).
 constpeerCert=clientSession.peerCertificate;
-ok(peerCert);
+ok(peerCertinstanceofX509Certificate);
+strictEqual(peerCert.subject,expectedCert.subject);
+strictEqual(peerCert.issuer,expectedCert.issuer);
+strictEqual(peerCert.fingerprint256,expectedCert.fingerprint256);
 
 // Ephemeral key info (client only).
 constkeyInfo=clientSession.ephemeralKeyInfo;

doc/api/quic.md

@@ -1404,23 +1404,24 @@ what this endpoint advertises to the peer as its own maximum.
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The local certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or no certificate is available.
+The local certificate as a [`crypto.X509Certificate`][] instance. Server
+sessions return the certificate configured for the negotiated SNI host.
+Client sessions return `undefined` unless a client certificate was sent.
+Returns `undefined` if the session is destroyed.
 
 ### `session.peerCertificate`
 
 <!-- YAML
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The peer's certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or the peer did not present a certificate.
+The peer's certificate as a [`crypto.X509Certificate`][] instance. Returns
+`undefined` if the peer did not present a certificate or the session is
+destroyed.
 
 ### `session.ephemeralKeyInfo`
 
@@ -4422,6 +4423,7 @@ throughput issues caused by flow control.
 [`application.enableConnectProtocol`]: #sessionoptionsapplication
 [`application.enableDatagrams`]: #sessionoptionsapplication
 [`application.qpackMaxDTableCapacity`]: #sessionoptionsapplication
+[`crypto.X509Certificate`]: crypto.md#class-x509certificate
 [`endpoint.busy`]: #endpointbusy
 [`endpoint.maxConnectionsPerHost`]: #endpointmaxconnectionsperhost
 [`endpoint.maxConnectionsTotal`]: #endpointmaxconnectionstotal

lib/internal/quic/quic.js

@@ -152,6 +152,10 @@ const {
  isKeyObject,
 }=require('internal/crypto/keys');
 
+const{
+ InternalX509Certificate,
+}=require('internal/crypto/x509');
+
 const{
  FileHandle,
 kHandle: kFileHandle,
@@ -3180,24 +3184,37 @@ class QuicSession {
 }
 
 /**
- * The local certificate as an object, or undefined if not available.
- * @type {object|undefined}
+ * The local certificate as a {@link crypto.X509Certificate}, or undefined
+ * if no local certificate is available. Server sessions return their
+ * configured certificate; client sessions return undefined unless a
+ * client certificate was sent.
+ * @type {crypto.X509Certificate|undefined}
  */
 getcertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.certificate??=this.#handle.getCertificate();
+if(this.#inner.certificate===undefined){
+consthandle=this.#handle.getCertificate();
+this.#inner.certificate=handle ? newInternalX509Certificate(handle) : null;
+}
+returnthis.#inner.certificate??undefined;
 }
 
 /**
- * The peer's certificate as an object, or undefined if the peer did
- * not present a certificate or the session is destroyed.
- * @type {object|undefined}
+ * The peer's certificate as a {@link crypto.X509Certificate}, or undefined
+ * if the peer did not present a certificate or the session is destroyed.
+ * @type {crypto.X509Certificate|undefined}
  */
 getpeerCertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.peerCertificate??=this.#handle.getPeerCertificate();
+if(this.#inner.peerCertificate===undefined){
+consthandle=this.#handle.getPeerCertificate();
+this.#inner.peerCertificate=handle ?
+newInternalX509Certificate(handle) :
+null;
+}
+returnthis.#inner.peerCertificate??undefined;
 }
 
 /**

test/parallel/test-quic-session-properties.mjs

@@ -11,11 +11,20 @@
 // All three cached.
 // All three return undefined after destroy.
 
-import{hasQuic,skip,mustCall}from'../common/index.mjs';
+import{hasQuic,skip,mustCall,hasCrypto}from'../common/index.mjs';
+import*asfixturesfrom'../common/fixtures.mjs';
 importassertfrom'node:assert';
 
 const{ ok, strictEqual }=assert;
 
+if(!hasCrypto)
+skip('missing crypto');
+
+const{ X509Certificate }=awaitimport('node:crypto');
+
+// The QUIC test helpers configure both sides with the agent1 fixture cert,
+constexpectedCert=newX509Certificate(fixtures.readKey('agent1-cert.pem'));
+
 if(!hasQuic){
 skip('QUIC is not enabled');
 }
@@ -38,7 +47,10 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 // Own certificate.
 constcert=serverSession.certificate;
-ok(cert);
+ok(certinstanceofX509Certificate);
+strictEqual(cert.subject,expectedCert.subject);
+strictEqual(cert.issuer,expectedCert.issuer);
+strictEqual(cert.fingerprint256,expectedCert.fingerprint256);
 
 // Peer certificate (client's cert — not set in this
 // test since we don't use verifyClient, so it's undefined).
@@ -65,7 +77,10 @@ strictEqual(clientSession.path, path);
 
 // Peer certificate (server's cert).
 constpeerCert=clientSession.peerCertificate;
-ok(peerCert);
+ok(peerCertinstanceofX509Certificate);
+strictEqual(peerCert.subject,expectedCert.subject);
+strictEqual(peerCert.issuer,expectedCert.issuer);
+strictEqual(peerCert.fingerprint256,expectedCert.fingerprint256);
 
 // Ephemeral key info (client only).
 constkeyInfo=clientSession.ephemeralKeyInfo;

doc/api/quic.md

@@ -1404,23 +1404,24 @@ what this endpoint advertises to the peer as its own maximum.
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The local certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or no certificate is available.
+The local certificate as a [`crypto.X509Certificate`][] instance. Server
+sessions return the certificate configured for the negotiated SNI host.
+Client sessions return `undefined` unless a client certificate was sent.
+Returns `undefined` if the session is destroyed.
 
 ### `session.peerCertificate`
 
 <!-- YAML
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The peer's certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or the peer did not present a certificate.
+The peer's certificate as a [`crypto.X509Certificate`][] instance. Returns
+`undefined` if the peer did not present a certificate or the session is
+destroyed.
 
 ### `session.ephemeralKeyInfo`
 
@@ -4422,6 +4423,7 @@ throughput issues caused by flow control.
 [`application.enableConnectProtocol`]: #sessionoptionsapplication
 [`application.enableDatagrams`]: #sessionoptionsapplication
 [`application.qpackMaxDTableCapacity`]: #sessionoptionsapplication
+[`crypto.X509Certificate`]: crypto.md#class-x509certificate
 [`endpoint.busy`]: #endpointbusy
 [`endpoint.maxConnectionsPerHost`]: #endpointmaxconnectionsperhost
 [`endpoint.maxConnectionsTotal`]: #endpointmaxconnectionstotal

lib/internal/quic/quic.js

@@ -152,6 +152,10 @@ const {
  isKeyObject,
 }=require('internal/crypto/keys');
 
+const{
+ InternalX509Certificate,
+}=require('internal/crypto/x509');
+
 const{
  FileHandle,
 kHandle: kFileHandle,
@@ -3180,24 +3184,37 @@ class QuicSession {
 }
 
 /**
- * The local certificate as an object, or undefined if not available.
- * @type {object|undefined}
+ * The local certificate as a {@link crypto.X509Certificate}, or undefined
+ * if no local certificate is available. Server sessions return their
+ * configured certificate; client sessions return undefined unless a
+ * client certificate was sent.
+ * @type {crypto.X509Certificate|undefined}
  */
 getcertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.certificate??=this.#handle.getCertificate();
+if(this.#inner.certificate===undefined){
+consthandle=this.#handle.getCertificate();
+this.#inner.certificate=handle ? newInternalX509Certificate(handle) : null;
+}
+returnthis.#inner.certificate??undefined;
 }
 
 /**
- * The peer's certificate as an object, or undefined if the peer did
- * not present a certificate or the session is destroyed.
- * @type {object|undefined}
+ * The peer's certificate as a {@link crypto.X509Certificate}, or undefined
+ * if the peer did not present a certificate or the session is destroyed.
+ * @type {crypto.X509Certificate|undefined}
  */
 getpeerCertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.peerCertificate??=this.#handle.getPeerCertificate();
+if(this.#inner.peerCertificate===undefined){
+consthandle=this.#handle.getPeerCertificate();
+this.#inner.peerCertificate=handle ?
+newInternalX509Certificate(handle) :
+null;
+}
+returnthis.#inner.peerCertificate??undefined;
 }
 
 /**

test/parallel/test-quic-session-properties.mjs

@@ -11,11 +11,20 @@
 // All three cached.
 // All three return undefined after destroy.
 
-import{hasQuic,skip,mustCall}from'../common/index.mjs';
+import{hasQuic,skip,mustCall,hasCrypto}from'../common/index.mjs';
+import*asfixturesfrom'../common/fixtures.mjs';
 importassertfrom'node:assert';
 
 const{ ok, strictEqual }=assert;
 
+if(!hasCrypto)
+skip('missing crypto');
+
+const{ X509Certificate }=awaitimport('node:crypto');
+
+// The QUIC test helpers configure both sides with the agent1 fixture cert,
+constexpectedCert=newX509Certificate(fixtures.readKey('agent1-cert.pem'));
+
 if(!hasQuic){
 skip('QUIC is not enabled');
 }
@@ -38,7 +47,10 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 // Own certificate.
 constcert=serverSession.certificate;
-ok(cert);
+ok(certinstanceofX509Certificate);
+strictEqual(cert.subject,expectedCert.subject);
+strictEqual(cert.issuer,expectedCert.issuer);
+strictEqual(cert.fingerprint256,expectedCert.fingerprint256);
 
 // Peer certificate (client's cert — not set in this
 // test since we don't use verifyClient, so it's undefined).
@@ -65,7 +77,10 @@ strictEqual(clientSession.path, path);
 
 // Peer certificate (server's cert).
 constpeerCert=clientSession.peerCertificate;
-ok(peerCert);
+ok(peerCertinstanceofX509Certificate);
+strictEqual(peerCert.subject,expectedCert.subject);
+strictEqual(peerCert.issuer,expectedCert.issuer);
+strictEqual(peerCert.fingerprint256,expectedCert.fingerprint256);
 
 // Ephemeral key info (client only).
 constkeyInfo=clientSession.ephemeralKeyInfo;

doc/api/quic.md

@@ -1404,23 +1404,24 @@ what this endpoint advertises to the peer as its own maximum.
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The local certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or no certificate is available.
+The local certificate as a [`crypto.X509Certificate`][] instance. Server
+sessions return the certificate configured for the negotiated SNI host.
+Client sessions return `undefined` unless a client certificate was sent.
+Returns `undefined` if the session is destroyed.
 
 ### `session.peerCertificate`
 
 <!-- YAML
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The peer's certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or the peer did not present a certificate.
+The peer's certificate as a [`crypto.X509Certificate`][] instance. Returns
+`undefined` if the peer did not present a certificate or the session is
+destroyed.
 
 ### `session.ephemeralKeyInfo`
 
@@ -4422,6 +4423,7 @@ throughput issues caused by flow control.
 [`application.enableConnectProtocol`]: #sessionoptionsapplication
 [`application.enableDatagrams`]: #sessionoptionsapplication
 [`application.qpackMaxDTableCapacity`]: #sessionoptionsapplication
+[`crypto.X509Certificate`]: crypto.md#class-x509certificate
 [`endpoint.busy`]: #endpointbusy
 [`endpoint.maxConnectionsPerHost`]: #endpointmaxconnectionsperhost
 [`endpoint.maxConnectionsTotal`]: #endpointmaxconnectionstotal

lib/internal/quic/quic.js

@@ -152,6 +152,10 @@ const {
  isKeyObject,
 }=require('internal/crypto/keys');
 
+const{
+ InternalX509Certificate,
+}=require('internal/crypto/x509');
+
 const{
  FileHandle,
 kHandle: kFileHandle,
@@ -3180,24 +3184,37 @@ class QuicSession {
 }
 
 /**
- * The local certificate as an object, or undefined if not available.
- * @type {object|undefined}
+ * The local certificate as a {@link crypto.X509Certificate}, or undefined
+ * if no local certificate is available. Server sessions return their
+ * configured certificate; client sessions return undefined unless a
+ * client certificate was sent.
+ * @type {crypto.X509Certificate|undefined}
  */
 getcertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.certificate??=this.#handle.getCertificate();
+if(this.#inner.certificate===undefined){
+consthandle=this.#handle.getCertificate();
+this.#inner.certificate=handle ? newInternalX509Certificate(handle) : null;
+}
+returnthis.#inner.certificate??undefined;
 }
 
 /**
- * The peer's certificate as an object, or undefined if the peer did
- * not present a certificate or the session is destroyed.
- * @type {object|undefined}
+ * The peer's certificate as a {@link crypto.X509Certificate}, or undefined
+ * if the peer did not present a certificate or the session is destroyed.
+ * @type {crypto.X509Certificate|undefined}
  */
 getpeerCertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.peerCertificate??=this.#handle.getPeerCertificate();
+if(this.#inner.peerCertificate===undefined){
+consthandle=this.#handle.getPeerCertificate();
+this.#inner.peerCertificate=handle ?
+newInternalX509Certificate(handle) :
+null;
+}
+returnthis.#inner.peerCertificate??undefined;
 }
 
 /**

test/parallel/test-quic-session-properties.mjs

@@ -11,11 +11,20 @@
 // All three cached.
 // All three return undefined after destroy.
 
-import{hasQuic,skip,mustCall}from'../common/index.mjs';
+import{hasQuic,skip,mustCall,hasCrypto}from'../common/index.mjs';
+import*asfixturesfrom'../common/fixtures.mjs';
 importassertfrom'node:assert';
 
 const{ ok, strictEqual }=assert;
 
+if(!hasCrypto)
+skip('missing crypto');
+
+const{ X509Certificate }=awaitimport('node:crypto');
+
+// The QUIC test helpers configure both sides with the agent1 fixture cert,
+constexpectedCert=newX509Certificate(fixtures.readKey('agent1-cert.pem'));
+
 if(!hasQuic){
 skip('QUIC is not enabled');
 }
@@ -38,7 +47,10 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 // Own certificate.
 constcert=serverSession.certificate;
-ok(cert);
+ok(certinstanceofX509Certificate);
+strictEqual(cert.subject,expectedCert.subject);
+strictEqual(cert.issuer,expectedCert.issuer);
+strictEqual(cert.fingerprint256,expectedCert.fingerprint256);
 
 // Peer certificate (client's cert — not set in this
 // test since we don't use verifyClient, so it's undefined).
@@ -65,7 +77,10 @@ strictEqual(clientSession.path, path);
 
 // Peer certificate (server's cert).
 constpeerCert=clientSession.peerCertificate;
-ok(peerCert);
+ok(peerCertinstanceofX509Certificate);
+strictEqual(peerCert.subject,expectedCert.subject);
+strictEqual(peerCert.issuer,expectedCert.issuer);
+strictEqual(peerCert.fingerprint256,expectedCert.fingerprint256);
 
 // Ephemeral key info (client only).
 constkeyInfo=clientSession.ephemeralKeyInfo;

doc/api/quic.md

@@ -1404,23 +1404,24 @@ what this endpoint advertises to the peer as its own maximum.
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The local certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or no certificate is available.
+The local certificate as a [`crypto.X509Certificate`][] instance. Server
+sessions return the certificate configured for the negotiated SNI host.
+Client sessions return `undefined` unless a client certificate was sent.
+Returns `undefined` if the session is destroyed.
 
 ### `session.peerCertificate`
 
 <!-- YAML
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The peer's certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or the peer did not present a certificate.
+The peer's certificate as a [`crypto.X509Certificate`][] instance. Returns
+`undefined` if the peer did not present a certificate or the session is
+destroyed.
 
 ### `session.ephemeralKeyInfo`
 
@@ -4422,6 +4423,7 @@ throughput issues caused by flow control.
 [`application.enableConnectProtocol`]: #sessionoptionsapplication
 [`application.enableDatagrams`]: #sessionoptionsapplication
 [`application.qpackMaxDTableCapacity`]: #sessionoptionsapplication
+[`crypto.X509Certificate`]: crypto.md#class-x509certificate
 [`endpoint.busy`]: #endpointbusy
 [`endpoint.maxConnectionsPerHost`]: #endpointmaxconnectionsperhost
 [`endpoint.maxConnectionsTotal`]: #endpointmaxconnectionstotal

lib/internal/quic/quic.js

@@ -152,6 +152,10 @@ const {
  isKeyObject,
 }=require('internal/crypto/keys');
 
+const{
+ InternalX509Certificate,
+}=require('internal/crypto/x509');
+
 const{
  FileHandle,
 kHandle: kFileHandle,
@@ -3180,24 +3184,37 @@ class QuicSession {
 }
 
 /**
- * The local certificate as an object, or undefined if not available.
- * @type {object|undefined}
+ * The local certificate as a {@link crypto.X509Certificate}, or undefined
+ * if no local certificate is available. Server sessions return their
+ * configured certificate; client sessions return undefined unless a
+ * client certificate was sent.
+ * @type {crypto.X509Certificate|undefined}
  */
 getcertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.certificate??=this.#handle.getCertificate();
+if(this.#inner.certificate===undefined){
+consthandle=this.#handle.getCertificate();
+this.#inner.certificate=handle ? newInternalX509Certificate(handle) : null;
+}
+returnthis.#inner.certificate??undefined;
 }
 
 /**
- * The peer's certificate as an object, or undefined if the peer did
- * not present a certificate or the session is destroyed.
- * @type {object|undefined}
+ * The peer's certificate as a {@link crypto.X509Certificate}, or undefined
+ * if the peer did not present a certificate or the session is destroyed.
+ * @type {crypto.X509Certificate|undefined}
  */
 getpeerCertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.peerCertificate??=this.#handle.getPeerCertificate();
+if(this.#inner.peerCertificate===undefined){
+consthandle=this.#handle.getPeerCertificate();
+this.#inner.peerCertificate=handle ?
+newInternalX509Certificate(handle) :
+null;
+}
+returnthis.#inner.peerCertificate??undefined;
 }
 
 /**

test/parallel/test-quic-session-properties.mjs

@@ -11,11 +11,20 @@
 // All three cached.
 // All three return undefined after destroy.
 
-import{hasQuic,skip,mustCall}from'../common/index.mjs';
+import{hasQuic,skip,mustCall,hasCrypto}from'../common/index.mjs';
+import*asfixturesfrom'../common/fixtures.mjs';
 importassertfrom'node:assert';
 
 const{ ok, strictEqual }=assert;
 
+if(!hasCrypto)
+skip('missing crypto');
+
+const{ X509Certificate }=awaitimport('node:crypto');
+
+// The QUIC test helpers configure both sides with the agent1 fixture cert,
+constexpectedCert=newX509Certificate(fixtures.readKey('agent1-cert.pem'));
+
 if(!hasQuic){
 skip('QUIC is not enabled');
 }
@@ -38,7 +47,10 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 // Own certificate.
 constcert=serverSession.certificate;
-ok(cert);
+ok(certinstanceofX509Certificate);
+strictEqual(cert.subject,expectedCert.subject);
+strictEqual(cert.issuer,expectedCert.issuer);
+strictEqual(cert.fingerprint256,expectedCert.fingerprint256);
 
 // Peer certificate (client's cert — not set in this
 // test since we don't use verifyClient, so it's undefined).
@@ -65,7 +77,10 @@ strictEqual(clientSession.path, path);
 
 // Peer certificate (server's cert).
 constpeerCert=clientSession.peerCertificate;
-ok(peerCert);
+ok(peerCertinstanceofX509Certificate);
+strictEqual(peerCert.subject,expectedCert.subject);
+strictEqual(peerCert.issuer,expectedCert.issuer);
+strictEqual(peerCert.fingerprint256,expectedCert.fingerprint256);
 
 // Ephemeral key info (client only).
 constkeyInfo=clientSession.ephemeralKeyInfo;

doc/api/quic.md

@@ -1404,23 +1404,24 @@ what this endpoint advertises to the peer as its own maximum.
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The local certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or no certificate is available.
+The local certificate as a [`crypto.X509Certificate`][] instance. Server
+sessions return the certificate configured for the negotiated SNI host.
+Client sessions return `undefined` unless a client certificate was sent.
+Returns `undefined` if the session is destroyed.
 
 ### `session.peerCertificate`
 
 <!-- YAML
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The peer's certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or the peer did not present a certificate.
+The peer's certificate as a [`crypto.X509Certificate`][] instance. Returns
+`undefined` if the peer did not present a certificate or the session is
+destroyed.
 
 ### `session.ephemeralKeyInfo`
 
@@ -4422,6 +4423,7 @@ throughput issues caused by flow control.
 [`application.enableConnectProtocol`]: #sessionoptionsapplication
 [`application.enableDatagrams`]: #sessionoptionsapplication
 [`application.qpackMaxDTableCapacity`]: #sessionoptionsapplication
+[`crypto.X509Certificate`]: crypto.md#class-x509certificate
 [`endpoint.busy`]: #endpointbusy
 [`endpoint.maxConnectionsPerHost`]: #endpointmaxconnectionsperhost
 [`endpoint.maxConnectionsTotal`]: #endpointmaxconnectionstotal

lib/internal/quic/quic.js

@@ -152,6 +152,10 @@ const {
  isKeyObject,
 }=require('internal/crypto/keys');
 
+const{
+ InternalX509Certificate,
+}=require('internal/crypto/x509');
+
 const{
  FileHandle,
 kHandle: kFileHandle,
@@ -3180,24 +3184,37 @@ class QuicSession {
 }
 
 /**
- * The local certificate as an object, or undefined if not available.
- * @type {object|undefined}
+ * The local certificate as a {@link crypto.X509Certificate}, or undefined
+ * if no local certificate is available. Server sessions return their
+ * configured certificate; client sessions return undefined unless a
+ * client certificate was sent.
+ * @type {crypto.X509Certificate|undefined}
  */
 getcertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.certificate??=this.#handle.getCertificate();
+if(this.#inner.certificate===undefined){
+consthandle=this.#handle.getCertificate();
+this.#inner.certificate=handle ? newInternalX509Certificate(handle) : null;
+}
+returnthis.#inner.certificate??undefined;
 }
 
 /**
- * The peer's certificate as an object, or undefined if the peer did
- * not present a certificate or the session is destroyed.
- * @type {object|undefined}
+ * The peer's certificate as a {@link crypto.X509Certificate}, or undefined
+ * if the peer did not present a certificate or the session is destroyed.
+ * @type {crypto.X509Certificate|undefined}
  */
 getpeerCertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.peerCertificate??=this.#handle.getPeerCertificate();
+if(this.#inner.peerCertificate===undefined){
+consthandle=this.#handle.getPeerCertificate();
+this.#inner.peerCertificate=handle ?
+newInternalX509Certificate(handle) :
+null;
+}
+returnthis.#inner.peerCertificate??undefined;
 }
 
 /**

test/parallel/test-quic-session-properties.mjs

@@ -11,11 +11,20 @@
 // All three cached.
 // All three return undefined after destroy.
 
-import{hasQuic,skip,mustCall}from'../common/index.mjs';
+import{hasQuic,skip,mustCall,hasCrypto}from'../common/index.mjs';
+import*asfixturesfrom'../common/fixtures.mjs';
 importassertfrom'node:assert';
 
 const{ ok, strictEqual }=assert;
 
+if(!hasCrypto)
+skip('missing crypto');
+
+const{ X509Certificate }=awaitimport('node:crypto');
+
+// The QUIC test helpers configure both sides with the agent1 fixture cert,
+constexpectedCert=newX509Certificate(fixtures.readKey('agent1-cert.pem'));
+
 if(!hasQuic){
 skip('QUIC is not enabled');
 }
@@ -38,7 +47,10 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 // Own certificate.
 constcert=serverSession.certificate;
-ok(cert);
+ok(certinstanceofX509Certificate);
+strictEqual(cert.subject,expectedCert.subject);
+strictEqual(cert.issuer,expectedCert.issuer);
+strictEqual(cert.fingerprint256,expectedCert.fingerprint256);
 
 // Peer certificate (client's cert — not set in this
 // test since we don't use verifyClient, so it's undefined).
@@ -65,7 +77,10 @@ strictEqual(clientSession.path, path);
 
 // Peer certificate (server's cert).
 constpeerCert=clientSession.peerCertificate;
-ok(peerCert);
+ok(peerCertinstanceofX509Certificate);
+strictEqual(peerCert.subject,expectedCert.subject);
+strictEqual(peerCert.issuer,expectedCert.issuer);
+strictEqual(peerCert.fingerprint256,expectedCert.fingerprint256);
 
 // Ephemeral key info (client only).
 constkeyInfo=clientSession.ephemeralKeyInfo;

doc/api/quic.md

@@ -1404,23 +1404,24 @@ what this endpoint advertises to the peer as its own maximum.
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The local certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or no certificate is available.
+The local certificate as a [`crypto.X509Certificate`][] instance. Server
+sessions return the certificate configured for the negotiated SNI host.
+Client sessions return `undefined` unless a client certificate was sent.
+Returns `undefined` if the session is destroyed.
 
 ### `session.peerCertificate`
 
 <!-- YAML
 added: REPLACEME
 -->
 
-* Type: {Object|undefined}
+* Type: {crypto.X509Certificate|undefined}
 
-The peer's certificate as an object with properties such as `subject`,
-`issuer`, `valid_from`, `valid_to`, `fingerprint`, etc. Returns `undefined`
-if the session is destroyed or the peer did not present a certificate.
+The peer's certificate as a [`crypto.X509Certificate`][] instance. Returns
+`undefined` if the peer did not present a certificate or the session is
+destroyed.
 
 ### `session.ephemeralKeyInfo`
 
@@ -4422,6 +4423,7 @@ throughput issues caused by flow control.
 [`application.enableConnectProtocol`]: #sessionoptionsapplication
 [`application.enableDatagrams`]: #sessionoptionsapplication
 [`application.qpackMaxDTableCapacity`]: #sessionoptionsapplication
+[`crypto.X509Certificate`]: crypto.md#class-x509certificate
 [`endpoint.busy`]: #endpointbusy
 [`endpoint.maxConnectionsPerHost`]: #endpointmaxconnectionsperhost
 [`endpoint.maxConnectionsTotal`]: #endpointmaxconnectionstotal

lib/internal/quic/quic.js

@@ -152,6 +152,10 @@ const {
  isKeyObject,
 }=require('internal/crypto/keys');
 
+const{
+ InternalX509Certificate,
+}=require('internal/crypto/x509');
+
 const{
  FileHandle,
 kHandle: kFileHandle,
@@ -3180,24 +3184,37 @@ class QuicSession {
 }
 
 /**
- * The local certificate as an object, or undefined if not available.
- * @type {object|undefined}
+ * The local certificate as a {@link crypto.X509Certificate}, or undefined
+ * if no local certificate is available. Server sessions return their
+ * configured certificate; client sessions return undefined unless a
+ * client certificate was sent.
+ * @type {crypto.X509Certificate|undefined}
  */
 getcertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.certificate??=this.#handle.getCertificate();
+if(this.#inner.certificate===undefined){
+consthandle=this.#handle.getCertificate();
+this.#inner.certificate=handle ? newInternalX509Certificate(handle) : null;
+}
+returnthis.#inner.certificate??undefined;
 }
 
 /**
- * The peer's certificate as an object, or undefined if the peer did
- * not present a certificate or the session is destroyed.
- * @type {object|undefined}
+ * The peer's certificate as a {@link crypto.X509Certificate}, or undefined
+ * if the peer did not present a certificate or the session is destroyed.
+ * @type {crypto.X509Certificate|undefined}
  */
 getpeerCertificate(){
 assertIsQuicSession(this);
 if(this.destroyed)returnundefined;
-returnthis.#inner.peerCertificate??=this.#handle.getPeerCertificate();
+if(this.#inner.peerCertificate===undefined){
+consthandle=this.#handle.getPeerCertificate();
+this.#inner.peerCertificate=handle ?
+newInternalX509Certificate(handle) :
+null;
+}
+returnthis.#inner.peerCertificate??undefined;
 }
 
 /**

test/parallel/test-quic-session-properties.mjs

@@ -11,11 +11,20 @@
 // All three cached.
 // All three return undefined after destroy.
 
-import{hasQuic,skip,mustCall}from'../common/index.mjs';
+import{hasQuic,skip,mustCall,hasCrypto}from'../common/index.mjs';
+import*asfixturesfrom'../common/fixtures.mjs';
 importassertfrom'node:assert';
 
 const{ ok, strictEqual }=assert;
 
+if(!hasCrypto)
+skip('missing crypto');
+
+const{ X509Certificate }=awaitimport('node:crypto');
+
+// The QUIC test helpers configure both sides with the agent1 fixture cert,
+constexpectedCert=newX509Certificate(fixtures.readKey('agent1-cert.pem'));
+
 if(!hasQuic){
 skip('QUIC is not enabled');
 }
@@ -38,7 +47,10 @@ const serverEndpoint = await listen(mustCall(async (serverSession) => {
 
 // Own certificate.
 constcert=serverSession.certificate;
-ok(cert);
+ok(certinstanceofX509Certificate);
+strictEqual(cert.subject,expectedCert.subject);
+strictEqual(cert.issuer,expectedCert.issuer);
+strictEqual(cert.fingerprint256,expectedCert.fingerprint256);
 
 // Peer certificate (client's cert — not set in this
 // test since we don't use verifyClient, so it's undefined).
@@ -65,7 +77,10 @@ strictEqual(clientSession.path, path);
 
 // Peer certificate (server's cert).
 constpeerCert=clientSession.peerCertificate;
-ok(peerCert);
+ok(peerCertinstanceofX509Certificate);
+strictEqual(peerCert.subject,expectedCert.subject);
+strictEqual(peerCert.issuer,expectedCert.issuer);
+strictEqual(peerCert.fingerprint256,expectedCert.fingerprint256);
 
 // Ephemeral key info (client only).
 constkeyInfo=clientSession.ephemeralKeyInfo;