Skip to content

Crayonic for Git(Hub) Authentication and Code Signing

Company: Crayonic B.V.

Created By: Peter Kolarov

1. Introduction

1.1 Purpose

This document describes a use case related to securing code repositories based on Git using FIDO and X.509 credentials and more specifically focusing on securing the GitHub repository.

1.2 Intended Audience

Administrators and developers.

1.3 Intended Use and Scope

Below we will address issues related to securing Git code repositories by enforcing biometric authentication for access to GitHub (or similar Git server) backend using command line and web browser.

The core use cases of the solution are:

1) Developer authentication to GitHub using the command line.

2) Developer authentication to GitHub website services.

3) Developer signing of commits and tags.

1.4 Definitions and Acronyms

Crayonic KeyVault - or CKV for short, is a secure certified vault for storing, using, and managing cryptographic keys and other secret material (OTPs, passwords, etc.). Since it uses biometrics to allow access to its cryptographic operations, allows flexible configuration and management in the enterprise context, and supports multiple protocols and standards, we refer to CKV as a smart authenticator. You can read more about its specifications here or a really detailed security whitepaper here.

Crayonic Gateway - or CGW for short, is an open-source backend solution for SSO authentication, access management, and CKV and its credentials (FIDO, X.509) management. It is delivered as a part of Crayonic's Passwordless-as-a-Service or as an on-prem self-hosted package for Docker or Kubernetes deployment. You can read more about it here.

Crayonic Gateway Lite - or CGL for short, is a simplified UX for CGW administrators that is meant to allow fast POCs or serve smaller companies in quickly deploying passwordless authentication and access management. More info can be found here.

SSO - single sign-on, mostly delivered in passwordless environments with CKV

FIDO - or FIDO2 is an open standard protocol developed by the FIDO Alliance and thus being supported by all major devices, operating systems, and web browsers. FIDO protocol is fully implemented by CKV and it is also used for managing credentials, CKV recovery, security policies, and settings.

PIV - X.509 credential-based protocol with a mini driver already present in Windows, Linux, and macOS for accessing and using X.509 certificates over USB and NFC.

SCEP - Simple Certificate Enrollment Protocol

2. Solution Description

Standard Git protocols allow for two different types of credentials: public-private key pairs (over SSH), or username and password (over HTTPS). For sake of security, only authentication with keys will be discussed from this point on.

Keys are a more secure solution until they are not. Very often the keys are stored on end-user (developer) devices directly, with public keys also distributed by these developers to target systems such as the Git backend we want to protect. This type of self-provisioned "PKI" is very efficient, however not really much more secure than shared secrets like passwords. Self-provisioned keys are not tied to any particular git user and can easily be shared or stolen as any protection by at least a password is often skipped and cannot be centrally enforced. In enterprise settings, the keys must be managed, distributed, and stored in accordance with enterprise-wide security policies. Considering today's highly popular SW supply chain attack vectors, these keys are as critical as any other in the enterprise context.

Starting from the end-point, the correct way to store any private key is in a certified secure cryptographic store a.k.a secure element. CKV provides such storage for different types of keys according to the credentialing system used. Via CKV PIV protocol we can now use enterprise-grade X.509 certificates and PKI with existing Git clients that use SSH for access.

2.1 Guaranteeing end-users identity over SSH to access Git service

Or Developer authentication to GitHub using the command line.

Using PIV with X.509 certificates for SSH enables a centrally-managed PKI framework to be extended to the management of credentials used to secure a remote access connection such as to Git servers. A large organization can take advantage of the features PIV offers to create a uniform, process-driven CKV implementation:

  • Standardized security policies can be uniformly enforced across the organization.

  • Issuing keys from a central location permits managed account recovery: a lost CKV need not result in loss of access.

  • SSH PIV (and FIDO) authentication methods use asymmetric keys—extending them to CKV adds an additional layer of security and the ability to tie cryptographic credentials to the real world persona using biometrics.

  • Wide support for the PKCS#11 interface opens up a large number of options for managing asymmetric keys on a CKV.

  • Because the CKV's PIV application allows for multiple keys to be loaded and used, the SSH use case can be added to existing PKI-supported functions such as Windows Login or VPN network access.

  • Additionally, it is possible to set up Git client to utilize the PIV protocol and issued X.509 certificate to allow for easy code signing of Git commits and tags.

As mentioned above, the SSH and X.509 PIV integration are based on PKCS#11 interface, thus for end-user to authenticate to Git server (i.e. GitHub, GitLab, etc.) these three things need to happen in the order:

  1. Identify end-user to be issued PIV X.509 credentials.

  2. Generate key pair (on the server or in CKV) and publish (and authorize for SAML2) public key to Git server user's account.

  3. Use CKV to sign authentication requests over SSH, optionally use CKV to sign commits and tags.

Starting from the last one, user authentication, the user (or SSH Agent) just executes the usual SSH authentication command:

 ssh user@remote.example.com

for example, in the case of Git service such as GitHub:

ssh -T git@github.com

or for GitLab:

ssh -T git@gitlab.com

Note: Starting with OpenSSH version 8.2 it is possible to utilize also FIDO2 credentials for ssh access, however as this solution is not mature yet it is not yet documented here for production purposes.

2.2 Guaranteeing end-users identity for web-based access GitHub service

To enforce biometric access to the web interface of GitHub or any other repo that supports SSO protocols is a simple integration exercise that is well documented in Crayonic Gateway and GitHub SAML2 integration. After the SAML2 connection is in place, the end-user can register and use her FIDO2 credential to access the GitHub web interface without passwords using multifactor biometric authentication. The issuance of FIDO2 credentials should be in accordance with enterprise policies and is configurable in Crayonic Gateway.

2.3 Guaranteeing end-users identity for Git commits and tags

In order to improve security, it is highly suggested to enforce signing of commits and tags within Git repo. GitHub can watch for unsigned commits and disable their merge. The signing of commits eliminates any possible supply chain attack vectors known today.

The X.509 certificate for S/MIME is delivered to the Crayonic Keyvault using Crayonic Gateway and web browser over the FIDO2 protocol. Thus, to enable end-users to sign their Git commits and tags, all that needs to be done by the code signing developer is to configure Git client to use smimesign as per the directions here: https://github.com/github/smimesign#installation

After configuration, the user needs to execute git commit and tag commands with the -S parameter in order to attach her signature which in turn is protected by her biometrics in a secure certified CKV key store.

At this point, we now have an end-user authenticator that is capable of storing and using X.509 PIV compatible certificates and keys for biometric authentication over SSH and for code signing using standard Git commands. To guarantee that the certificate and its key are also bound to the correct end-user, CKV can be set up to enforce authentication using only biometrics such as fingerprint recognition (soon voice and handwriting) or in combination with PIN code if another security factor (knowledge) is required.

Until now, we have assumed that: CKV has valid and authorized credentials, CKV is trusted by remote service to authenticate users via biometrics, the public key of the credential has been pushed to the end-users account and authorized and/or signed, and most of all that the correct credential has been generated for the correct end-user. These assumptions require a complicated manual process by the end-user (credential generation and distribution) and by the administrator (key authorization and signing, identity verification, and PKI orchestration). To simplify these processes for the end-user and the administrators we have developed Crayonic Gateway for Enterprise (CGW). This cloud or on-prem hosted solution has been built by Crayonic on top of the enterprise-ready application by RedHat and enables much more automatic management of the above plus many other useful features.

2.3 Managing credentials, users, and Git access with Crayonic Gateway

CGW offers a complete solution for remote issuance of X.509 credentials to Crayonic KeyVaults using just a web browser. Furthermore, CGW allows administrators to manage: policies and credentials (X.509 and FIDO), user access and roles (AM), SSO integrations (SAML2, OIDC), PKI integrations (SCEP), user identity federations (LDAP, AD), and custom integrations such as GitHub.

To meet the requirements for managed GitHub authentication and code signing, the Crayonic Gateway needs to be integrated into GitHub via the public REST API. Once this integration is in place, the CGW can distribute and authorize PIV-enabled public keys with X.509 certificates as well as FIDO2 public keys, for every user based on their identification and authorizations.

Besides the key distribution and lifecycle management, the CGW enables their issuance and signing via SCEP protocol for example with Microsoft Certificate Services or similar CA with SCEP support. Of course, custom integration with CAs beyond SCEP is possible too.

The standard features of CGW include user management and synchronization from LDAP sources, which enables fast user onboarding to the solution and invites by email. Additionally, KYC modules and services could be provided as per request for verifying end-users true identities, unless end users can already authenticate themselves within another trusted Identity Provider (IDP) connected by SAML2/OIDC protocol.

If needed, Crayonic Gateway can provide complete Single Sign-on to third-party services such as GitHub over SAML2 or OIDC integrations and even use a simpler reverse proxy approach.

Another important security aspect in enforcing biometric access to cryptographic keys is to verify that the end-user device actually performers biometric authentication and provides secure access to the stored keys. To verify the capabilities of an end-user device such as CKV, the attestation of the smart authenticator is needed before any certificates are issued to it. CKV is able to "introduce" itself to Crayonic Gateway using its own attestation key pair which has been burned into CKV during the manufacturing process. This way, we can verify the authenticity and thus the security capabilities of a remotely connected authenticator such as Crayonic KeyVault using just a web browser.

To learn more about the Crayonic Gateway follow the link below and request access to the demo tenant by email: demo@crayonic.com

3. Solution Features and Architecture

3.1 Crayonic KeyVault Specs and Features

Refer to the links below for details.

Crayonic KeyVault™ K1

Crayonic Gateway™

3.2 Solution Architecture