[Proof of concept] Certificate Handling Improvements

[Robbie-Microsoft]

Core Library

MSAL Node (@azure/msal-node)

Wrapper Library

Not Applicable

Public or Confidential Client?

Confidential

Description

How can we simply (for the developer) the way that certificate information - SHA256 thumbprint, private key, and x5 - is passed into MSAL Node when the Confidential Client flow is used?

Currently, the developer can pass the following into the MSAL app's configuration object:

export type NodeAuthOptions = {
    ...
    clientCertificate?: {
        /**
         * @deprecated Use thumbprintSha2 property instead. Thumbprint needs to be computed with SHA-256 algorithm.
         * SHA-1 is only needed for backwards compatibility with older versions of ADFS.
         */
        thumbprint?: string;
        thumbprintSha256?: string;
        privateKey: string;
        x5c?: string;
    };
    ...
}

[Robbie-Microsoft]

type ClientCertificate = 
  | { type: 'pem'; data: string }       // PEM format: base64 encoded or text
  | { type: 'der'; data: Buffer }       // DER format: raw binary data
  | { type: 'pkcs12'; data: Buffer }    // PKCS#12 format: binary data
  | { type: 'pkcs7'; data: Buffer };    // PKCS#7 format: binary data

export type NodeAuthOptions = {
    ...
    clientCertificate?: ClientCertificate;
    clientCertificatePassword?: string;
    ...
}

The developer could now pass in a certificate in the following formats:

• PEM (.pem, .crt, .cer)
• DER (.der)
• PKCS#12 (.p12, .pfx)
• PKCS#7 (.p7b)

Along with an optional password for their certificate.

This new "certificate handling" functionality below will extract the SHA256 thumbprint, private key and x5c header from the provided certificate. Please see the provided JSDocs and comments for more detailed information.

---

/*
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */

import { createHash } from 'crypto';
import { execSync } from 'child_process';

/**
 * Extracts both the SHA-256 fingerprint and private key from various certificate formats.
 *
 * This function supports the following certificate formats:
 *  - PEM (.pem, .crt, .cer) - Base64 encoded with BEGIN/END markers
 *  - DER (.der) - Binary encoded certificate
 *  - PKCS#12 (.p12, .pfx) - Contains certificates and private keys, password protected
 *  - PKCS#7 (.p7b) - Certificate chain format (private key not included)
 *
 * The function returns an object with the SHA-256 fingerprint and the private key (if available).
 *
 * @param certificateData - The certificate data (can be PEM, DER, or PKCS formats).
 * @param password - The password for the PKCS#12 file, if applicable.
 * @returns An object containing the SHA-256 fingerprint and private key (if available).
 * @throws Will throw an error if the certificate format is unsupported or cannot be processed.
 */
function extractCertificateInfo(
    certificateData: Buffer | string,
    password: string = ''
): { sha256Fingerprint: string; privateKey: string | null; x5c?: string[] } {
    const certBuffer = Buffer.isBuffer(certificateData)
        ? certificateData
        : Buffer.from(certificateData, 'utf8');

    // Check for PEM format (used in .pem, .crt, .cer files)
    if (isPemFormat(certBuffer)) {
        return getPemCertificateInfo(certBuffer);
    }

    // Check for DER format (used in .der files)
    if (isDerFormat(certBuffer)) {
        return getDerCertificateInfo(certBuffer);
    }

    // Check for PKCS#12 (PFX format, used in .p12, .pfx files)
    if (isPkcs12Format(certBuffer)) {
        return getPkcs12CertificateInfo(certBuffer, password);
    }

    // Check for PKCS#7 (P7B format, used in .p7b files)
    if (isPkcs7Format(certBuffer)) {
        return getPkcs7CertificateInfo(certBuffer);
    }

    // If the format isn't recognized
    throw new Error('Unsupported certificate format');
}

/**
 * Checks if the provided data is in PEM format.
 * PEM format is base64 encoded with specific BEGIN/END markers.
 * Typically used for .pem, .crt, .cer file extensions.
 * 
 * @param data - The certificate data to check.
 * @returns Whether the data is PEM format.
 */
function isPemFormat(data: Buffer): boolean {
    const pemPattern = /-----BEGIN CERTIFICATE-----/;
    return pemPattern.test(data.toString('utf8'));
}

/**
 * Checks if the provided data is in DER format.
 * DER format is binary encoded with no delimiters.
 * Typically used for .der file extension.
 *
 * @param data - The certificate data to check.
 * @returns Whether the data is DER format.
 */
function isDerFormat(data: Buffer): boolean {
    return !isPemFormat(data) && data.length > 0;
}

/**
 * Checks if the provided data is in PKCS#12 (PFX) format.
 * PKCS#12 format is used for .p12, .pfx files and contains certificates and private keys.
 * 
 * @param data - The certificate data to check.
 * @returns Whether the data is PKCS#12 format.
 */
function isPkcs12Format(data: Buffer): boolean {
    return data.slice(0, 4).equals(Buffer.from([0x30, 0x82, 0x02, 0x01]));
}

/**
 * Checks if the provided data is in PKCS#7 (P7B) format.
 * PKCS#7 format is often used for certificate chains and typically has a header starting with 0x30 0x82 0x06 0x0A.
 * 
 * @param data - The certificate data to check.
 * @returns Whether the data is PKCS#7 format.
 */
function isPkcs7Format(data: Buffer): boolean {
    return data.slice(0, 4).equals(Buffer.from([0x30, 0x82, 0x06, 0x0A]));
}

/**
 * Extracts the SHA-256 fingerprint and private key from a PEM-encoded certificate.
 * PEM is typically used for .pem, .crt, .cer files.
 *
 * @param pemData - The PEM-encoded certificate data.
 * @returns The SHA-256 fingerprint and private key (if available).
 */
function getPemCertificateInfo(pemData: Buffer): { sha256Fingerprint: string; privateKey: string | null; x5c?: string[] } {
    const privateKey = extractPemPrivateKey(pemData);
    const sha256Fingerprint = getPemSha256Fingerprint(pemData);
    const x5c = extractPemX5C(pemData); // Extract x5c (certificate chain) if available

    if (x5c && isX5CReversed(x5c)) {
        console.log('Detected reversed x5c chain');
        // Optionally, reverse the x5c chain here if needed:
        x5c.reverse();
    }

    return { sha256Fingerprint, privateKey, x5c };
}

/**
 * Extracts the private key from PEM-encoded certificate data, if available.
 * PEM format private keys are typically found between BEGIN/END PRIVATE KEY markers.
 *
 * @param pemData - The PEM-encoded certificate data.
 * @returns The private key (if found), or null if no private key is present.
 */
function extractPemPrivateKey(pemData: Buffer): string | null {
    const pemString = pemData.toString('utf8');
    const privateKeyMatch = pemString.match(
        /-----BEGIN (EC|RSA) PRIVATE KEY-----([\s\S]*?)-----END (EC|RSA) PRIVATE KEY-----/
    );
    if (privateKeyMatch) {
        return privateKeyMatch[0]; // Return the private key as a string
    }
    return null; // No private key found
}

/**
 * Extracts the SHA-256 fingerprint from a PEM-encoded certificate.
 *
 * @param pemData - The PEM-encoded certificate data.
 * @returns The SHA-256 fingerprint of the certificate in uppercase.
 */
function getPemSha256Fingerprint(pemData: Buffer): string {
    const pem = pemData
        .toString('utf8')
        .replace(/-----BEGIN CERTIFICATE-----/g, '')
        .replace(/-----END CERTIFICATE-----/g, '')
        .replace(/\n/g, '');
    const certBuffer = Buffer.from(pem, 'base64');
    return getSha256Fingerprint(certBuffer);
}

/**
 * Extracts the X.509 Certificate Chain (x5c) from PEM-encoded certificate data, if available.
 *
 * @param pemData - The PEM-encoded certificate data.
 * @returns An array of certificates forming the x5c chain (if available).
 */
function extractPemX5C(pemData: Buffer): string[] | undefined {
    const pemString = pemData.toString('utf8');
    const certMatches = pemString.match(
        /-----BEGIN CERTIFICATE-----([\s\S]*?)-----END CERTIFICATE-----/g
    );
    if (certMatches) {
        return certMatches.map((cert) =>
            cert.replace(/-----BEGIN CERTIFICATE-----/g, '').replace(/-----END CERTIFICATE-----/g, '').replace(/\n/g, '')
        );
    }
    return undefined; // No x5c chain found
}

/**
 * Extracts the SHA-256 fingerprint from a DER-encoded certificate.
 *
 * @param derData - The DER-encoded certificate (binary).
 * @returns The SHA-256 fingerprint and private key (DER does not contain a private key).
 */
function getDerCertificateInfo(derData: Buffer): { sha256Fingerprint: string; privateKey: null } {
    const sha256Fingerprint = getSha256Fingerprint(derData);
    return { sha256Fingerprint, privateKey: null }; // DER does not contain a private key
}

/**
 * Extracts the SHA-256 fingerprint and private key from a PKCS#12 (PFX) certificate.
 *
 * @param pkcs12Data - The PKCS#12 file data (binary).
 * @param password - The password for the PKCS#12 file.
 * @returns The SHA-256 fingerprint and private key.
 */
function getPkcs12CertificateInfo(pkcs12Data: Buffer, password: string): { sha256Fingerprint: string; privateKey: string; x5c?: string[] } {
    try {
        // Extract the certificate and private key from PKCS#12 using OpenSSL in-memory
        const certData = execSync(`openssl pkcs12 -in /dev/stdin -passin pass:${password} -nokeys -clcerts -out /dev/stdout`, {
            input: pkcs12Data,
            encoding: 'utf8'
        });
        const privateKey = execSync(`openssl pkcs12 -in /dev/stdin -passin pass:${password} -nocerts -out /dev/stdout`, {
            input: pkcs12Data,
            encoding: 'utf8'
        });

        const sha256Fingerprint = getPemSha256Fingerprint(certData);
        const x5c = extractPemX5C(certData); // Extract x5c from the PEM-encoded certificate

        if (x5c && isX5CReversed(x5c)) {
            console.log('Detected reversed x5c chain');
            x5c.reverse();  // Reverse the x5c chain if needed
        }

        return { sha256Fingerprint, privateKey, x5c };
    } catch (error) {
        throw new Error('Failed to extract certificate or private key from PKCS#12 file in memory: ' + error.message);
    }
}

/**
 * Extracts the SHA-256 fingerprint from a PKCS#7 (P7B) certificate.
 * PKCS#7 certificates typically do not contain a private key.
 *
 * @param p7bData - The PKCS#7 certificate data (binary).
 * @returns The SHA-256 fingerprint and private key (null for P7B format).
 */
function getPkcs7CertificateInfo(p7bData: Buffer): { sha256Fingerprint: string; privateKey: null; x5c?: string[] } {
    try {
        // Extract the certificate(s) from the PKCS#7 file in-memory
        const certData = execSync(`openssl pkcs7 -in /dev/stdin -print_certs -out /dev/stdout`, {
            input: p7bData,
            encoding: 'utf8'
        });

        const sha256Fingerprint = getPemSha256Fingerprint(certData);
        const x5c = extractPemX5C(certData); // Extract x5c from the PEM-encoded certificate

        if (x5c && isX5CReversed(x5c)) {
            console.log('Detected reversed x5c chain');
            x5c.reverse();  // Reverse the x5c chain if needed
        }

        return { sha256Fingerprint, privateKey: null, x5c };
    } catch (error) {
        throw new Error('Failed to extract certificate from PKCS#7 file in memory: ' + error.message);
    }
}

/**
 * Generates the SHA-256 fingerprint of a certificate.
 *
 * @param certData - The certificate data.
 * @returns The SHA-256 fingerprint in uppercase.
 */
function getSha256Fingerprint(certData: Buffer): string {
    return createHash('sha256').update(certData).digest('hex').toUpperCase();
}

/**
 * Detects if the x5c chain is reversed based on a heuristic and manual check.
 * This function will first check using a heuristic, then validate the chain order manually.
 * 
 * @param x5c - The certificate chain.
 * @returns Whether the certificate chain is reversed or not.
 */
function isX5CReversed(x5c: string[]): boolean {
    // First, try to use the heuristic check for RSA public key pattern
    if (isReversedX5C(x5c)) {
        console.log('Using heuristic: Reversed');
        return true; // Chain is reversed based on heuristic
    }

    // If heuristic check fails, use the manual certificate chain order check
    const isCorrectOrder = checkCertificateChainOrder(x5c);
    console.log('Using manual check: ', isCorrectOrder ? 'Correct Order' : 'Reversed');
    return !isCorrectOrder; // Return reversed if manual check fails
}

/**
 * A heuristic to check if x5c is reversed based on the first certificate.
 * This is typically the case when x5c chain starts with an intermediate instead of the root.
 *
 * @param x5c - The certificate chain to check.
 * @returns True if the chain is reversed; false otherwise.
 */
function isReversedX5C(x5c: string[]): boolean {
    const firstCert = x5c[0];
    const match = /^MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A/.test(firstCert); // Check for specific pattern
    return match;
}

/**
 * Validates the certificate chain order by checking the issuer-subject relationship.
 * The issuer of each certificate should match the subject of the next certificate in the chain.
 * 
 * @param x5c - The certificate chain to check.
 * @returns Whether the certificate chain is correctly ordered.
 */
function checkCertificateChainOrder(x5c: string[]): boolean {
    const parsedCerts = x5c.map(cert => parseCert(cert));
    for (let i = 0; i < parsedCerts.length - 1; i++) {
        if (parsedCerts[i].issuer !== parsedCerts[i + 1].subject) {
            return false; // Chain order is incorrect
        }
    }
    return true; // All certificates match issuer-subject order
}

/**
 * Parses a certificate string to extract the issuer and subject fields.
 * 
 * This function uses OpenSSL to extract the issuer and subject fields from the certificate
 * provided as a string, and returns them in a structured format. If parsing fails, an error is thrown.
 * 
 * @param {string} cert - The certificate in PEM format to parse.
 * @returns {{ issuer: string; subject: string }} The parsed issuer and subject of the certificate.
 * @throws {Error} If the OpenSSL command fails or certificate parsing is unsuccessful.
 */
function parseCert(cert: string): { issuer: string; subject: string } {
    try {
        // Run OpenSSL command to get issuer and subject by passing the certificate via stdin
        const issuer = execSync(`echo "${cert}" | openssl x509 -noout -issuer`).toString().trim();
        const subject = execSync(`echo "${cert}" | openssl x509 -noout -subject`).toString().trim();

        // Regular expression to match the issuer and subject fields
        const issuerMatch = issuer.match(/issuer= (.*)/);
        const subjectMatch = subject.match(/subject= (.*)/);

        // Return the extracted fields, ensuring that we trim any surrounding whitespace
        return {
            issuer: issuerMatch ? issuerMatch[1].trim() : '',
            subject: subjectMatch ? subjectMatch[1].trim() : ''
        };
    } catch (error) {
        // Handle any errors that may occur during OpenSSL execution
        throw new Error('Failed to parse certificate with OpenSSL: ' + error.message);
    }
}

export { extractCertificateInfo };

---

With this new functionality in mind, the entirety of the ClientAssertion class will need to be updated:

/*
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */

import jwt, { JwtHeader } from 'jsonwebtoken';
import {
    TimeUtils,
    createClientAuthError,
    ClientAuthErrorCodes,
} from '@azure/msal-common/node';
import { CryptoProvider } from '../crypto/CryptoProvider.js';
import { EncodingUtils } from '../utils/EncodingUtils.js';
import { JwtConstants } from '../utils/Constants.js';
import { extractCertificateInfo } from '../utils/certificateExtractor'; // Assuming this is the path for the code that extracts SHA-256 and private key

/**
 * Client assertion of type jwt-bearer used in confidential client flows.
 * @public
 */
export class ClientAssertion {
    private jwt: string = '';  // Changed this to an empty string instead of null
    private privateKey: string = '';
    private thumbprint: string = '';
    private expirationTime: number = 0;
    private issuer: string = '';
    private jwtAudience: string = '';
    private publicCertificate: string[] = [];

    /**
     * Initialize the ClientAssertion class from the client assertion passed by the user.
     * @param assertion - The JWT client assertion string (per RFC7521).
     * @returns The ClientAssertion instance.
     */
    public static fromAssertion(assertion: string): ClientAssertion {
        const clientAssertion = new ClientAssertion();
        clientAssertion.jwt = assertion;
        return clientAssertion;
    }

    /**
     * Initialize the ClientAssertion class from the certificate passed by the user.
     * @param certificateData - The certificate data (can be PEM, DER, PFX, or P7B format).
     * @param password - Password for PFX certificates (if applicable).
     * @returns The ClientAssertion instance.
     */
    public static fromCertificate(
        certificateData: Buffer | string,
        password: string = ''
    ): ClientAssertion {
        const { sha256Fingerprint, privateKey, x5c } = extractCertificateInfo(certificateData, password);

        const clientAssertion = new ClientAssertion();
        clientAssertion.privateKey = privateKey;
        clientAssertion.thumbprint = sha256Fingerprint;

        // If a public certificate chain is available (x5c), store it
        if (x5c && x5c.length > 0) {
            clientAssertion.publicCertificate = x5c;
        }

        return clientAssertion;
    }

    /**
     * Update JWT for certificate-based clientAssertion.
     * If passed by the user, uses it as-is and checks expiration.
     * @param cryptoProvider - The library's crypto helper.
     * @param issuer - The issuer (iss claim).
     * @param jwtAudience - The audience (aud claim).
     * @returns The JWT token.
     * @throws ClientAuthError if assertion is invalid.
     */
    public getJwt(
        cryptoProvider: CryptoProvider,
        issuer: string,
        jwtAudience: string
    ): string {
        if (this.privateKey && this.thumbprint) {
            if (
                this.jwt &&
                !this.isExpired() &&
                issuer === this.issuer &&
                jwtAudience === this.jwtAudience
            ) {
                return this.jwt;
            }

            return this.createJwt(cryptoProvider, issuer, jwtAudience);
        }

        throw createClientAuthError(ClientAuthErrorCodes.invalidAssertion);
    }

    /**
     * Creates the JWT token, with necessary claims and headers.
     * @param cryptoProvider - The library's crypto helper.
     * @param issuer - The issuer (iss claim).
     * @param jwtAudience - The audience (aud claim).
     * @returns The JWT token.
     */
    private createJwt(
        cryptoProvider: CryptoProvider,
        issuer: string,
        jwtAudience: string
    ): string {
        this.issuer = issuer;
        this.jwtAudience = jwtAudience;
        const issuedAt = TimeUtils.nowSeconds();
        this.expirationTime = issuedAt + 600; // JWT expiration set to 10 minutes from issuedAt

        const header: JwtHeader = {
            alg: JwtConstants.PSS_256, // Always use PSS_256 for SHA-256 thumbprint
            [JwtConstants.X5T_256]: EncodingUtils.base64EncodeUrl(
                this.thumbprint,
                'hex'
            ),
        };

        // If the public certificate chain is available, add it to the header
        if (this.publicCertificate && this.publicCertificate.length > 0) {
            Object.assign(header, {
                [JwtConstants.X5C]: this.publicCertificate,
            });
        }

        const payload = {
            [JwtConstants.AUDIENCE]: this.jwtAudience,
            [JwtConstants.EXPIRATION_TIME]: this.expirationTime,
            [JwtConstants.ISSUER]: this.issuer,
            [JwtConstants.SUBJECT]: this.issuer,
            [JwtConstants.NOT_BEFORE]: issuedAt,
            [JwtConstants.JWT_ID]: cryptoProvider.createNewGuid(),
        };

        this.jwt = jwt.sign(payload, this.privateKey, { header });
        return this.jwt;
    }

    /**
     * Utility function to check if the JWT has expired.
     * @returns Whether the JWT has expired.
     */
    private isExpired(): boolean {
        return this.expirationTime < TimeUtils.nowSeconds();
    }
}

---

Lastly, this code in ConfidentialClientApplication.ts will need to be updated to:

this.clientAssertion = ClientAssertion.fromCertificate(
    <certificate passed in by dev>,
    <optional certificate password>
);

[maorleger]

In general I love the simplification of the public API and it may allow us to remove the certificate parsing logic we have in @azure/identity - would love to help test this out if/when you have an alpha build!

For reference, here's what we do in @azure/identity today when parsing a certificate: https://github.com/Azure/azure-sdk-for-js/blob/ef1cfa3d5147479b997e52322b8e09e5c373914f/sdk/identity/identity/src/credentials/clientCertificateCredential.ts#L157-L231

Gave it a quick review this morning and have a few thoughts as I was going through this:

getPkcs12CertificateInfo

1. Assumption that openssl is installed and available may not always be true
2. Passing the password directly to openssl can have a few painful side-effects:
   1. Command line arguments can be viewed by using ps, top, etc. which may expose this password
   2. If password is provided by the customer, that should be considered as untrusted input and properly sanitized to avoid command injection. I think child_process.spawn handles sanitization when you pass arguments as an array, but you might consult security experts on the best way to handle that

isPemFormat

1. Should this test for -----END CERTIFICATE----- pattern as well or do you feel the existing check is robust enough?

parseCert

1. Same concern about sanitizing untrusted input

General

1. Consider using the promise API of exec and making this asynchronous to avoid blocking the event loop.
2. For the ClientCertificate type, consider using kind instead of type which is idiomatic for TypeScript. So instead of { type: 'pem'; data: string } it might be { kind: 'pem'; data: string }
   1. Sidenote I always appreciate when libraries provide a discriminated union for this as it helps narrow down the types and values of input and provides better intellisense 👍