add socket.getPeerCertificate to KibanaRequest (elastic#42929)

* add socket.getPeerCertificate to KibanaRequest

* update request mocks

* update docs

docs/development/core/server/kibana-plugin-server.ikibanasocket.getpeercertificate_1.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [IKibanaSocket](./kibana-plugin-server.ikibanasocket.md) &gt; [getPeerCertificate](./kibana-plugin-server.ikibanasocket.getpeercertificate_1.md)
+
+## IKibanaSocket.getPeerCertificate() method
+
+<b>Signature:</b>
+
+```typescript
+getPeerCertificate(detailed: true): DetailedPeerCertificate | null;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  detailed | <code>true</code> |  |
+
+<b>Returns:</b>
+
+`DetailedPeerCertificate | null`
+

docs/development/core/server/kibana-plugin-server.ikibanasocket.getpeercertificate_2.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [IKibanaSocket](./kibana-plugin-server.ikibanasocket.md) &gt; [getPeerCertificate](./kibana-plugin-server.ikibanasocket.getpeercertificate_2.md)
+
+## IKibanaSocket.getPeerCertificate() method
+
+<b>Signature:</b>
+
+```typescript
+getPeerCertificate(detailed: false): PeerCertificate | null;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  detailed | <code>false</code> |  |
+
+<b>Returns:</b>
+
+`PeerCertificate | null`
+

docs/development/core/server/kibana-plugin-server.ikibanasocket.getpeercertificate_3.md

@@ -0,0 +1,26 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [IKibanaSocket](./kibana-plugin-server.ikibanasocket.md) &gt; [getPeerCertificate](./kibana-plugin-server.ikibanasocket.getpeercertificate_3.md)
+
+## IKibanaSocket.getPeerCertificate() method
+
+Returns an object representing the peer's certificate. The returned object has some properties corresponding to the field of the certificate. If detailed argument is true the full chain with issuer property will be returned, if false only the top certificate without issuer property. If the peer does not provide a certificate, it returns null.
+
+<b>Signature:</b>
+
+```typescript
+getPeerCertificate(detailed?: boolean): PeerCertificate | DetailedPeerCertificate | null;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  detailed | <code>boolean</code> | If true; the full chain with issuer property will be returned. |
+
+<b>Returns:</b>
+
+`PeerCertificate | DetailedPeerCertificate | null`
+
+An object representing the peer's certificate.
+

docs/development/core/server/kibana-plugin-server.ikibanasocket.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [IKibanaSocket](./kibana-plugin-server.ikibanasocket.md)
+
+## IKibanaSocket interface
+
+A tiny abstraction for TCP socket.
+
+<b>Signature:</b>
+
+```typescript
+export interface IKibanaSocket 
+```
+
+## Methods
+
+|  Method | Description |
+|  --- | --- |
+|  [getPeerCertificate(detailed)](./kibana-plugin-server.ikibanasocket.getpeercertificate_1.md) |  |
+|  [getPeerCertificate(detailed)](./kibana-plugin-server.ikibanasocket.getpeercertificate_2.md) |  |
+|  [getPeerCertificate(detailed)](./kibana-plugin-server.ikibanasocket.getpeercertificate_3.md) | Returns an object representing the peer's certificate. The returned object has some properties corresponding to the field of the certificate. If detailed argument is true the full chain with issuer property will be returned, if false only the top certificate without issuer property. If the peer does not provide a certificate, it returns null. |
+

docs/development/core/server/kibana-plugin-server.kibanarequest.md

@@ -27,5 +27,6 @@ export declare class KibanaRequest<Params = unknown, Query = unknown, Body = unk
 |  [params](./kibana-plugin-server.kibanarequest.params.md) |  | <code>Params</code> |  |
 |  [query](./kibana-plugin-server.kibanarequest.query.md) |  | <code>Query</code> |  |
 |  [route](./kibana-plugin-server.kibanarequest.route.md) |  | <code>RecursiveReadonly&lt;KibanaRequestRoute&gt;</code> | matched route details |
+|  [socket](./kibana-plugin-server.kibanarequest.socket.md) |  | <code>IKibanaSocket</code> |  |
 |  [url](./kibana-plugin-server.kibanarequest.url.md) |  | <code>Url</code> | a WHATWG URL standard object. |
 

docs/development/core/server/kibana-plugin-server.kibanarequest.socket.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [KibanaRequest](./kibana-plugin-server.kibanarequest.md) &gt; [socket](./kibana-plugin-server.kibanarequest.socket.md)
+
+## KibanaRequest.socket property
+
+<b>Signature:</b>
+
+```typescript
+readonly socket: IKibanaSocket;
+```

docs/development/core/server/kibana-plugin-server.md

@@ -49,6 +49,7 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
 |  [HttpResponseOptions](./kibana-plugin-server.httpresponseoptions.md) | HTTP response parameters |
 |  [HttpServerSetup](./kibana-plugin-server.httpserversetup.md) | Kibana HTTP Service provides own abstraction for work with HTTP stack. Plugins don't have direct access to <code>hapi</code> server and its primitives anymore. Moreover, plugins shouldn't rely on the fact that HTTP Service uses one or another library under the hood. This gives the platform flexibility to upgrade or changing our internal HTTP stack without breaking plugins. If the HTTP Service lacks functionality you need, we are happy to discuss and support your needs. |
 |  [HttpServiceStart](./kibana-plugin-server.httpservicestart.md) |  |
+|  [IKibanaSocket](./kibana-plugin-server.ikibanasocket.md) | A tiny abstraction for TCP socket. |
 |  [InternalCoreStart](./kibana-plugin-server.internalcorestart.md) |  |
 |  [KibanaRequestRoute](./kibana-plugin-server.kibanarequestroute.md) | Request specific route information exposed to a handler. |
 |  [LegacyRequest](./kibana-plugin-server.legacyrequest.md) |  |

src/core/server/http/index.ts

@@ -24,6 +24,7 @@ export { GetAuthHeaders } from './auth_headers_storage';
 export { AuthStatus, GetAuthState, IsAuthenticated } from './auth_state_storage';
 export {
   CustomHttpResponseOptions,
+  IKibanaSocket,
   isRealRequest,
   HttpResponseOptions,
   HttpResponsePayload,

src/core/server/http/router/index.ts

@@ -41,3 +41,5 @@ export {
   lifecycleResponseFactory,
   LifecycleResponseFactory,
 } from './response';
+
+export { IKibanaSocket } from './socket';

src/core/server/http/router/request.ts

@@ -25,6 +25,7 @@ import { ObjectType, TypeOf } from '@kbn/config-schema';
 import { deepFreeze, RecursiveReadonly } from '../../../utils';
 import { Headers } from './headers';
 import { RouteMethod, RouteSchemas, RouteConfigOptions } from './route';
+import { KibanaSocket, IKibanaSocket } from './socket';
 
 const requestSymbol = Symbol('request');
 
@@ -120,6 +121,8 @@ export class KibanaRequest<Params = unknown, Query = unknown, Body = unknown> {
    */
   public readonly headers: Headers;
 
+  public readonly socket: IKibanaSocket;
+
   /** @internal */
   protected readonly [requestSymbol]: Request;
 
@@ -142,6 +145,7 @@ export class KibanaRequest<Params = unknown, Query = unknown, Body = unknown> {
     });
 
     this.route = deepFreeze(this.getRouteInfo());
+    this.socket = new KibanaSocket(request.raw.req.socket);
   }
 
   private getRouteInfo() {

src/core/server/http/router/socket.test.ts

@@ -0,0 +1,59 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { Socket } from 'net';
+import { DetailedPeerCertificate, TLSSocket } from 'tls';
+import { KibanaSocket } from './socket';
+
+describe('KibanaSocket', () => {
+  describe('getPeerCertificate', () => {
+    it('returns null for net.Socket instance', () => {
+      const socket = new KibanaSocket(new Socket());
+
+      expect(socket.getPeerCertificate()).toBe(null);
+    });
+
+    it('delegates a call to tls.Socket instance', () => {
+      const tlsSocket = new TLSSocket(new Socket());
+      const cert = { issuerCertificate: {} } as DetailedPeerCertificate;
+      const spy = jest.spyOn(tlsSocket, 'getPeerCertificate').mockImplementation(() => cert);
+      const socket = new KibanaSocket(tlsSocket);
+      const result = socket.getPeerCertificate(true);
+
+      expect(spy).toBeCalledTimes(1);
+      expect(spy).toBeCalledWith(true);
+      expect(result).toBe(cert);
+    });
+
+    it('returns null if tls.Socket getPeerCertificate returns null', () => {
+      const tlsSocket = new TLSSocket(new Socket());
+      jest.spyOn(tlsSocket, 'getPeerCertificate').mockImplementation(() => null as any);
+      const socket = new KibanaSocket(tlsSocket);
+
+      expect(socket.getPeerCertificate()).toBe(null);
+    });
+
+    it('returns null if tls.Socket getPeerCertificate returns empty object', () => {
+      const tlsSocket = new TLSSocket(new Socket());
+      jest.spyOn(tlsSocket, 'getPeerCertificate').mockImplementation(() => ({} as any));
+      const socket = new KibanaSocket(tlsSocket);
+
+      expect(socket.getPeerCertificate()).toBe(null);
+    });
+  });
+});

src/core/server/http/router/socket.ts

@@ -0,0 +1,59 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { Socket } from 'net';
+import { DetailedPeerCertificate, PeerCertificate, TLSSocket } from 'tls';
+
+/**
+ * A tiny abstraction for TCP socket.
+ * @public
+ */
+export interface IKibanaSocket {
+  getPeerCertificate(detailed: true): DetailedPeerCertificate | null;
+  getPeerCertificate(detailed: false): PeerCertificate | null;
+  /**
+   * Returns an object representing the peer's certificate.
+   * The returned object has some properties corresponding to the field of the certificate.
+   * If detailed argument is true the full chain with issuer property will be returned,
+   * if false only the top certificate without issuer property.
+   * If the peer does not provide a certificate, it returns null.
+   * @param detailed - If true; the full chain with issuer property will be returned.
+   * @returns An object representing the peer's certificate.
+   */
+  getPeerCertificate(detailed?: boolean): PeerCertificate | DetailedPeerCertificate | null;
+}
+
+export class KibanaSocket implements IKibanaSocket {
+  constructor(private readonly socket: Socket) {}
+
+  getPeerCertificate(detailed: true): DetailedPeerCertificate | null;
+  getPeerCertificate(detailed: false): PeerCertificate | null;
+  getPeerCertificate(detailed?: boolean): PeerCertificate | DetailedPeerCertificate | null;
+
+  public getPeerCertificate(detailed?: boolean) {
+    if (this.socket instanceof TLSSocket) {
+      const peerCertificate = this.socket.getPeerCertificate(detailed);
+
+      // If the peer does not provide a certificate, it returns null (if the socket has been destroyed)
+      // or an empty object, so we should check for both these cases.
+      if (peerCertificate && Object.keys(peerCertificate).length > 0) return peerCertificate;
+    }
+    return null;
+  }
+}

src/core/server/index.ts

@@ -75,6 +75,7 @@ export {
   HttpResponseOptions,
   HttpResponsePayload,
   HttpServerSetup,
+  IKibanaSocket,
   IsAuthenticated,
   KibanaRequest,
   KibanaRequestRoute,

src/core/server/server.api.md

@@ -7,10 +7,12 @@
 import Boom from 'boom';
 import { CallCluster } from 'src/legacy/core_plugins/elasticsearch';
 import { ConfigOptions } from 'elasticsearch';
+import { DetailedPeerCertificate } from 'tls';
 import { Duration } from 'moment';
 import { IncomingHttpHeaders } from 'http';
 import { ObjectType } from '@kbn/config-schema';
 import { Observable } from 'rxjs';
+import { PeerCertificate } from 'tls';
 import { Readable } from 'stream';
 import { Request } from 'hapi';
 import { ResponseObject } from 'hapi';
@@ -246,6 +248,15 @@ export interface HttpServiceStart {
     isListening: (port: number) => boolean;
 }
 
+// @public
+export interface IKibanaSocket {
+    // (undocumented)
+    getPeerCertificate(detailed: true): DetailedPeerCertificate | null;
+    // (undocumented)
+    getPeerCertificate(detailed: false): PeerCertificate | null;
+    getPeerCertificate(detailed?: boolean): PeerCertificate | DetailedPeerCertificate | null;
+}
+
 // @internal (undocumented)
 export interface InternalCoreSetup {
     // (undocumented)
@@ -282,6 +293,8 @@ export class KibanaRequest<Params = unknown, Query = unknown, Body = unknown> {
     // (undocumented)
     readonly query: Query;
     readonly route: RecursiveReadonly<KibanaRequestRoute>;
+    // (undocumented)
+    readonly socket: IKibanaSocket;
     readonly url: Url;
     }
 

x-pack/legacy/plugins/xpack_main/server/lib/__tests__/replace_injected_vars.js

@@ -21,6 +21,11 @@ const buildRequest = (telemetryOptedIn = null, path = '/app/kibana') => {
   return {
     path,
     route: { settings: {} },
+    raw: {
+      req: {
+        socket: {}
+      }
+    },
     getSavedObjectsClient: () => {
       return {
         get,