Fortify

Overview

Fortify enables cross-browser usage of local certificates, smart cards and do certificate enrollment.

What does Fortify do?

Use your smart card or security token that has already been enrolled with a certificate with web applications.
Enroll for a new certificate or renew an existing one.
Build applications that can sign/verify or encrypt/decrypt using locally installed certificates, smart cards or security tokens.

Support

Platform/Browser	Supported versions
MacOS	10.9 and later
Windows	7 and later
Linux
Chrome	43 and later
Safari	9 and later
Firefox	32 and later

Installation

Crypto

Webcrypto socket module implements WebCrypto interface and uses Fortify application for crypto implementation.

Browser

To support cross-browser work you can apply some scripts to your HTML page. webcrypto-sockets.js exports global namespace WebcryptoSocket.

<!-- Babel Polyfill -->
<script defer src="https://fortifyapp.com/external/babel-polyfill/6.26.0/polyfill.min.js"></script>

<!-- Fetch Polyfill -->
<script defer nomodule src="https://fortifyapp.com/external/whatwg-fetch/3.0.0/fetch.umd.js"></script>

<!-- Crypto Polyfill -->
<script defer src="https://fortifyapp.com/external/asmCrypto/2.3.2/asmcrypto.all.es5.min.js"></script>
<script defer src="https://fortifyapp.com/external/elliptic/elliptic.min.js"></script>
<script defer type="module" src="https://fortifyapp.com/external/webcrypto-liner/1.2.3/webcrypto-liner.shim.min.mjs"></script>
<script defer nomodule src="https://fortifyapp.com/external/webcrypto-liner/1.2.3/webcrypto-liner.shim.min.js"></script>

<!-- WebCrypto Socket -->
<script defer src="https://fortifyapp.com/external/protobuf/6.8.0/protobuf.min.js"></script>
<script defer type="module" src="https://fortifyapp.com/external/webcrypto-local/client/1.1.7/webcrypto-socket.min.mjs"></script>
<script defer nomodule src="https://fortifyapp.com/external/webcrypto-local/client/1.1.7/webcrypto-socket.min.js"></script>

Be sure to use your own compose of third-party dependencies in production applications.

NPM

# Crypto Polyfill
npm install asmcrypto.js elliptic webcrypto-liner

# WebCrypto Socket
npm install protobufjs @webcrypto-local/client

Web-component

Browser

Put a script and link tag in the head of your index.html.

<script type="module" src="https://cdn.jsdelivr.net/npm/@peculiar/fortify-webcomponents/dist/peculiar/peculiar.esm.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@peculiar/fortify-webcomponents/dist/peculiar/peculiar.css">

NPM

npm install @peculiar/fortify-webcomponents

Then you can use the element anywhere in your template, JSX, html, etc.

<peculiar-fortify-certificates />

Web-components

Fortify Certificates WebComponent

The web-component provides an easier way to connect a web-page to the Fortify App, show certificates from available OS crypto providers, and choose a certificate for signing.

Usage

Basic

Quick example embed web component in to you application:

<peculiar-fortify-certificates
  id="fortify-certificates-wc"
  language="en"
/>

Then in js you can access to component lifecycle events and filter properties:

const fortifyCertificates = document.getElementById('fortify-certificates-wc');

fortifyCertificates.filters = {
  expired: false,
  onlySmartcards: false,
  onlyWithPrivateKey: false,
  keyUsage: ['digitalSignature'],
  subjectDNMatch: 'kubernetes-master',
  issuerDNMatch: 'kubernetes',
  providerNameMatch: 'MacOS Crypto',
  providerATRMatch: '0123456789',
  certificateIdMatch: '0123456789',
};

fortifyCertificates.addEventListener('selectionCancel', () => {
  console.log('cancel flow');
});

fortifyCertificates.addEventListener('selectionSuccess', (result) => {
  console.log(result);
});

Properties

downloadAppLink
Attribute	`download-app-link`
Description	A link to download the application when a connection to Fortify is not found.
Type	`string`
Default	`'https://fortifyapp.com'`

filters
Description	Component data filters. KeyUsageType you can find on certificate specification.
Type	`{ expired?: boolean; onlySmartcards?: boolean; onlyWithPrivateKey?: boolean; keyUsage?: KeyUsageType[] \| KeyUsageType[][]; subjectDNMatch?: string \| RegExp; issuerDNMatch?: string \| RegExp; providerNameMatch?: string \| RegExp; providerATRMatch?: string \| RegExp; onlyQualified?: boolean; certificateIdMatch?: string \| RegExp; qualifiedCertificateStatements?: string[]; ca?: boolean; }`
Default	`{}`

helpPageLink
Attribute	`help-page-link`
Description	A link to redirect the user to the help page if there are any questions about the operation of the application.
Type	`string`
Default	`'https://fortifyapp.com/help'`

hideFooter
Attribute	`hide-footer`
Description	If `true`, the component footer will be hidden.
Type	`boolean`
Default	`false`

language
Attribute	`language`
Description	Component language.
Type	`"de" \| "el" \| "en" \| "es" \| "fr" \| "he" \| "it" \| "ja" \| "nl" \| "pl" \| "pt" \| "ru" \| "tr"`

Events

selectionCancel
Description	Fires when the user has canceled the selection flow.
Type	`CustomEvent<void>`

selectionSuccess
Description	Fires when the user has successfully selected a certificate.
Type	`CustomEvent<ISelectionSuccessEvent>`

Fortify Enrollment WebComponent

The web-component provides an easier way to connect a web-page to the Fortify App, show available OS crypto providers, and enroll self-signed certificate or certificate request with prefilled parameters.

Usage

Basic

Quick example embed web component in to you application:

<peculiar-fortify-enrollment
  id="fortify-enrollment-wc"
  language="en"
/>

Then in js you can access to component lifecycle events and filter properties:

const fortifyEnrollment = document.getElementById('fortify-enrollment-wc');

fortifyEnrollment.filters = {
  onlySmartcards: false,
  providerNameMatch: 'MacOS Crypto',
  providerATRMatch: '0123456789',
};

fortifyEnrollment.addEventListener('creationCancel', () => {
  console.log('creationCancel');
});

fortifyEnrollment.addEventListener('creationClose', () => {
  console.log('creationClose');
});

fortifyEnrollment.addEventListener('creationSuccess', (result) => {
  console.log(result);
});

fortifyEnrollment.addEventListener('creationFail', (error) => {
  console.log(error);
});

Form-policy

To provide custom form policy you need to pass object to component.

Default policy config:

{
  subject: {
    fields: {
      CN: {
        required: true
      },
      O: {
        required: false
      },
      OU: {
        required: false
      },
      C: {
        required: false,
        defaultValue: "US"
      },
      L: {
        required: false
      },
      ST: {
        required: false
      }
    }
  },
  publicKey: {
    fields: {
      signatureAlgorithm: {
        required: true,
        defaultValue: "RSA-2048"
      },
      hashAlgorithm: {
        required: true,
        defaultValue: "SHA-256"
      }
    }
  },
  options: {
    fields: {
      useSelfSignedCertificate: {
        required: false
      }
    }
  }
}

Example of read only policy with prefilled values:

const fortifyEnrollment = document.getElementById('fortify-enrollment-wc');

fortifyEnrollment.formPolicy = {
  subject: {
    fields: {
      CN: {
        required: true,
        readOnly: true,
        defaultValue: 'kubernetes',
      },
      O: {
        required: false,
        readOnly: true,
        defaultValue: 'kubernetes org.',
      },
      OU: {
        required: false,
        readOnly: true,
        defaultValue: 'kubernetes org. unit',
      },
      C: {
        required: false,
        readOnly: true,
        defaultValue: "US"
      },
      L: {
        required: false,
        readOnly: true,
        defaultValue: "kubernetes world"
      },
      ST: {
        required: false,
        readOnly: true,
        defaultValue: "kubernetes west"
      }
    }
  },
  publicKey: {
    fields: {
      signatureAlgorithm: {
        required: true,
        readOnly: true,
        defaultValue: "RSA-2048"
      },
      hashAlgorithm: {
        required: true,
        readOnly: true,
        defaultValue: "SHA-256"
      }
    }
  },
  options: {
    fields: {
      useSelfSignedCertificate: {
        required: false,
        readOnly: true,
        defaultValue: true
      }
    }
  }
};

Properties

downloadAppLink
Attribute	`download-app-link`
Description	A link to download the application when a connection to Fortify is not found.
Type	`string`
Default	`'https://fortifyapp.com'`

filters
Description	Object that contains filters for user certificates and providers.
Type	`{ onlySmartcards?: boolean; providerNameMatch?: string \| RegExp; providerATRMatch?: string \| RegExp; }`
Default	`{}`

formPolicy
Description	Object that contains configurations for enrollment form.
Type	`IFormPolicyConfig`

helpPageLink
Attribute	`help-page-link`
Description	A link to redirect the user to the help page if there are any questions about the operation of the application.
Type	`string`
Default	`'https://fortifyapp.com/help'`

hideFooter
Attribute	`hide-footer`
Description	If `true`, the component footer will be hidden.
Type	`boolean`
Default	`false`

language
Attribute	`language`
Description	Component language.
Type	`"de" \| "el" \| "en" \| "es" \| "fr" \| "he" \| "it" \| "ja" \| "nl" \| "pl" \| "pt" \| "ru" \| "tr"`

Events

creationCancel
Description	Fires when the user has canceled the creation flow.
Type	`CustomEvent<void>`

creationClose
Description	Fires when the user clicks on the "Close" button after successfully creating a certificate or certificate request.
Type	`CustomEvent<void>`

creationFail
Description	Fires when the user failed to generate a certificate or certificate request.
Type	`CustomEvent<Error>`

creationSuccess
Description	Fires when the user has successfully created a certificate or certificate request.
Type	`CustomEvent<ICreationSuccessEvent>`