carla_urrea

I've been working as a software engineer since 2014, particularly as a backend engineer and doing system design. I consider myself a language-agnostic developer but if I had to choose, I like to work with Ruby, Python, and Elixir.  

After realizing how fun it was to create content and share experiences with the developer community I made the switch to Developer Advocacy. I like to learn and work with new technologies. 

When I'm not coding or creating content you could probably find me going on a bike ride, hiking, or just hanging out with my dog, Dasha. 

Senior Developer Advocate

Carla Urrea Stabile

Nowadays you could replace your physical driver's license with a digital, cryptographically verifiable one. Let's learn about it and how to start using them.

A driver's license is a document that gives legal authorization for people to drive certain types of vehicles, and they're often made of plastic and have the size of a credit card, so you usually store it in your wallet. Some countries, like Australia, the UK, and the US, use driver's licenses to prove their citizens' identity.

As driver's licenses continue to play a crucial role in verifying your identity, it makes sense that they evolve alongside our increasingly digital world. That's where Mobile Driver's Licenses come in. In this blog post, you'll learn more about them and how to use them.

## What is a Mobile Driver's License (mDL)?

Let's start from the beginning. **A Mobile Driver's License (mDL) is a driving license that resides on a mobile device** instead of physically in your wallet. The beauty behind an mDL is that **they are cryptographically verifiable**, meaning you can use cryptography to verify their information and authorship.

An mDL is a type of [Verifiable Credential (VC)](https://auth0.com/blog/what-are-verifiable-credentials-why-you-should-care/#What-are-Verifiable-Credentials) and they're an [ISO Standard](https://www.iso.org/standard/69084.html). As a VC, mobile driver's licenses also have an issuing authority, which is the authorized organization issuing the driver's license; for example, in the US, that'd be [the DMV](https://en.wikipedia.org/wiki/Department_of_motor_vehicles). There is an mDL holder, and it's the person to whom the mDL is issued. Finally, there is an mDL verifier, which is the entity that can verify the authorship of the mDL.

### mDL Step by Step

![mDL Roles](https://images.ctfassets.net/23aumh6u8s0i/7xGF2PSKekpejYPX11EOse/157c1415ce452ff436954197c1e90eb7/mdl-roles.png)

1. **Issuing:** A user can request an mDL from an issuing authority using their digital wallet. In mDL, this wallet is called an mDoc reader. An mDoc is a document that resides on a mobile device, so the mDoc reader can retrieve an mDoc for verification purposes. The issuer will verify the user's details and use their private key to sign and issue the mDL.

2. **Presenting:** A user can show their mDL using an application called an mDL reader to prove their identity, for example. This application would request the mDL data, which must be verified later.

3. **Verifying:** The mDL reader is in charge of cryptographically verifying the mDL data.

<include src="SmallBannerCTA"
         imgLink="https://images.ctfassets.net/23aumh6u8s0i/12gXwIIea5F2nkS1hNQFWy/70e57fab64095553831e4f4a0ee497d9/mdl-logo.png"
         text="Want to learn more about mDL?"
         linkText="Visit → mdl.me"
         link="https://mdl.me"/>

## Where Are We Today?

Today, many countries have started implementing and deploying pilots for Mobile Driver's Licenses. In the US, for example, there are already [multiple states that have mDL implementations](https://www.aamva.org/jurisdiction-data-maps#anchorformdlmap) in place. [The TSA (Transport Security Administration) has been accepting digital credentials as proof of identity since early 2022](https://www.tsa.gov/travel/frequently-asked-questions/when-will-phased-digital-id-rollout-start-which-airportsstates).

In November 2023, the [European Union also submitted a proposal to introduce mobile driver's licenses](https://data.consilium.europa.eu/doc/document/ST-15808-2023-INIT/en/pdf) and make them fully equivalent to their physical counterpart.

These are just a few examples to tell you that Mobile Driver's Licenses are coming to stay, and many other countries will start piloting and adopting them. Many companies are also beginning to build their own mDL readers and implementations; in fact, [the mDL ISO Standard was tested at the Interoperability Event](https://blog.spruceid.com/iso-iec-18013-7-interoperability-event-results/) where companies joined forces to test their implementations. Some mDL readers and mDL implementers included **Google, the National Institute of Standards and Technology (NIST), Okta, Samsung**, and more. You can read more about it in the [event results publication](https://docs.google.com/document/d/1M4ufcKqmj8gycNovslOSWzFB2nB1o1eu/edit?ref=blog.spruceid.com#heading=h.gjdgxs).


## Where to Use mDL?

Mobile Driver's Licenses have many potential use cases, but some of the most relevant are:

- Prove your Identity: as mentioned above, many countries use driver's licenses as proof of identity, and mDLs should be equivalent to prove someone's identity.
- Improve business processes involving Know Your Customer (KYC) and Anti-Money Laundering (AML)

## Getting Started with mDL

There are a few ways you can get started with mDL, the first one being going to [mdl.me](https://mdl.me) to learn more about it, how it works, and use the debugger to understand what's happening under the hood.

You can also start playing with a library like the one we crafted at [Auth0 Lab, mDL](https://github.com/auth0-lab/mdl). This NodeJS library allows you to issue and verify mDL [CBOR](https://cbor.io/) encoded documents. This library allows you to have a good start to understand how mDL works but **it's important to mention the library alone allows you to create, parse and validate mDL but it's not enough if you need to exchange mDLs.** So for example if you want to present mDL you need to implement a protocol such as the one in the [ISO/IEC DTS 18013-7](https://www.iso.org/standard/82772.html).

### Using the mDL library

First, you need to install the library. For that, run the following in your terminal:

```bash
npm install @auth0/mdl
```

> Note this blog post is for educational purposes and not meant to be used in production. In order to use mDL you'd need a protocol on top to exchange the data, such as the one in [ISO/IEC DTS 18013-7](https://www.iso.org/standard/82772.html) for presenting mDLs.


### Issuing a Credential

Let's take a look at what the code for issuing a new credential would look like:

```js
import { MDoc, Document } from "@auth0/mdl";
import fs from "node:fs";

// Create Document: representation of the mDL data
const document = await new Document('org.iso.18013.5.1.mDL')
  .addIssuerNameSpace('org.iso.18013.5.1', {
    family_name: 'Jones',
    given_name: 'Ava',
    birth_date: '2007-03-25',
  })
  .useDigestAlgorithm('SHA-512')
  .addValidityInfo({
    signed: new Date('2023-10-24'),
    validUntil: new Date('2050-10-24'),
  })
  .addDeviceKeyInfo({ deviceKey: devicePublicKeyJWK })
  .sign({
    issuerPrivateKey,
    issuerCertificate,
    alg: 'ES256',
  });

// Create MDoc
const mdoc = new MDoc([document]);

// CBOR encode the MDoc
const encodedMdoc = mdoc.encode();
```

This script is doing a few things. First, it adds the document type `org.iso.18013.5.1.mDL` to the `Document` instance; this refers to the mDoc document type that is used to identify the ISO driving license standard. Then, it adds the name and birth date attributes of the holder.

The digest algorithm is set to `SHA-512`, and it's used to compute the digest of each attribute. A digest algorithm is a cryptographic hash function that maps a large block of data into a fixed-size output (512 bits or 64 bytes in this case). The verifier will use the same algorithm to verify the disclosed attributes. This is related to the way that [selective disclosure](https://www.w3.org/TR/vc-data-model/#dfn-selective-disclosure) is implemented in mDL.

Then you'll see the `validityInfo`, which is the period of time the document is valid, and finally the device key information in the `addDeviceKeyInfo` method. Here, you specify the public key of the device that will hold the mDL to ensure that the mDL will only be used by the device that holds the corresponding private key. In other words, a presentation will only be accepted if it's signed with the private key that corresponds to the public key in the mDL.

Finally, you use the `sign` method to sign the document using the issuer's private key and certificate.

### Requesting a Credential

Now let's take a look at what should happen on the verifier side. The verifier is the entity that will request the mDL from the holder to later on verify its authenticity. 

Depending on the use case, the holder could have an application on their device that can serve as mDL reader (for example if they're opening a bank account online from their phone) or they could have be requested to show their mDL and the mDL reader resides in another device (for example, to enter a bar and prove that the holder is 18 years old or more, the person at the entrance could have an mDL reader where people can present their mDLs).

The mDL reader requests the mDL data that it needs and the holder uses the digital wallet to present the credential. When the holder presents the credential, the verifier needs to first generate an [ephemeral key pair](https://csrc.nist.gov/glossary/term/ephemeral_key_pair) and a nonce. An ephemeral key pair it's a short-term key pair generated when needed, and the nonce is a random value that is used to prevent replay attacks. The verifier then sends the nonce and the ephemeral public key to the holder. 

You could use [the JOSE package](https://www.npmjs.com/package/jose), for example, to generate these short-term keys. After installing `jose` with `npm install jose` you could do something like the following:

```js
const {generateKeyPair} = require('jose');
const ephemeralKey = await generateKeyPair('ES256')
```

### Generating a Device Response

Once the holder receives the nonce and the ephemeral key, their device can generate a device response. The device response is a signed message that contains the mDL and the nonce.

```js
const deviceResponseMDoc = await DeviceResponse.from(mdoc)
  .usingPresentationDefinition(PRESENTATION_DEFINITION_1)
  .usingHandover([holderNonce, clientId, responseUri, verifierGeneratedNonce])
  .authenticateWithMAC(DEVICE_JWK, ephemeralPublicKey, 'HS256')
  .addDeviceNameSpace('com.foobar-device', { test: 1234 })
  .sign();

const encodedSessionTranscript = getSessionTranscriptBytes(
  { client_id: clientId, response_uri: responseUri, nonce: verifierGeneratedNonce },
  holderNonce,
);

const deviceResponse = deviceResponseMDoc.encode();

sendToVerifier({ deviceResponse, encodedSessionTranscript });
```

With the mDL issued to the holder, the device creates a new device response using the `DeviceRespose` class. The `usingHandover` method is used to specify the date the verifier sent along with a nonce generated by the holder. Here, the `PRESENTATION_DEFINITION_1` constant refers to [which proofs the verifier is requesting from the holder](https://identity.foundation/presentation-exchange/spec/v2.0.0/#presentation-definition). An example could be:

```js
export const PRESENTATION_DEFINITION_1 = {
  id: 'mdl-test-age-over-18',
  input_descriptors: [
    {
      id: 'org.iso.18013.5.1.mDL',
      format: {
        mso_mdoc: {
          alg: ['EdDSA', 'ES256'],
        },
      },
      constraints: {
        limit_disclosure: 'required',
        fields: [
          {
            path: ["$['org.iso.18013.5.1']['age_over_18']"],
            intent_to_retain: false,
          },
        ],
      },
    },
  ],
};
```

In this case, the verifier is asking for an mDL with just one of the holder's attributes to verify that the holder is over 18 years old. You can find other examples in the [mDL repository](https://github.com/auth0-lab/mdl/blob/41724db924161c680c6fff0aa80450a8a2aa7286/__tests__/issuing/config.ts#L108). 

The `authenticateWithMAC` method is used to specify the way in which the device response is authenticated. In this case, it's authenticated [with a MAC](https://datatracker.ietf.org/doc/html/rfc9052#name-mac-objects) using the `HS256` algorithm. The secret for this MAC is computed as follows:

- On the holder's side it uses the public ephemeral key generated by the verifier plus the private key of the device.
- On the verifier's side it uses the private ephemeral key generated by the verifier plus the public key of the device.

The `addDeviceNameSpace` method adds a namespace to the device response.

Finally, the `sign` method is used to sign the device response.

### Verifying the Device Response

Finally the verifier verifies the `DeviceResponse`.

```js
const verifier = new Verifier([ISSUER_CERTIFICATE]);
await verifier.verify(encoded, {
  ephemeralReaderKey: ephemeralPrivateKey,
  encodedSessionTranscript,
});
```

First you need to construct a `Verifier` instance with a list of the issuer's certificates you trust.

Then you call the `verify` method with the encoded device response, the private key of the ephemeral key pair, and the encoded session transcript. This is a structure defined by the ISO standard. You can learn more about it in the  [ISO 18013.5 (section 9.1.5.1 - Session transcript)](https://www.iso.org/standard/69084.html)

## What's Coming: Verify mDL with Auth0

You can [sign up for the waitlist](https://regionalevents.okta.com/mdlearlyaccess) to be one of the first to know when mDL with Auth0 is available in Early Access.

You can also go to [mdl.me](https://mdl.me) to learn more, and if you know about any other mDL libraries out there, let us know so we can include them in the list of resources!

What is a Mobile Driver's License (mDL) and How to Start Using Them

jon-elliott

Hi, I'm a Software Engineer and lifelong learner with a passion for cryptography. I've been with the IAM-Core-Crypto team in Auth0 since 2021, but have been working on applying applied cryptography to systems and applications since 2015


Senior Software Engineer

Jon Elliott

Quantum computers may not be here yet, but we still need to prepare for them.

There’s a joke about Quantum Computing where a Computer Science Professor predicts to a rapt classroom that it’s just 10 years away, and the punchline is that they’ve been saying it for the last 50 years or so. The actual number of years in the future changes from telling to telling, but the point is always that it remains within sight but out of reach. Quantum Computing as a usable tool is definitely still out of reach, but you wouldn’t know it by the amount of discussion there is around it. We’re not going to go into the basics of Quantum Computing as there are plenty of articles already about that. 

Instead, we’re going to focus on how we actively need to prepare for it, whether it will be a reality soon or not. Post-Quantum Cryptography (PQC) refers to cryptographic algorithms that can be run on classical computers, but are believed to be secure enough to withstand a cryptoanalytic attack by a Quantum Computer. Don't get me wrong, I’m not saying that you need to go and ditch your brand-new laptop straight away. When they do reach maturity, Quantum computers probably aren't going to be relevant for every use case out there. The ones we have just now can’t even run that ultimate test of computing power, Doom. [Seriously](https://digitalcommons.denison.edu/cgi/viewcontent.cgi?article=1242&context=synapse).

## How Quantum Computing Impacts Security

However, Quantum Computing is of particular concern when it comes to cryptography, specifically end-to-end encryption. This is where the information is encrypted on the sender's device before transmission and is only decrypted when it reaches the intended receiver's device. This is how we use cryptography every day, in more ways than you can imagine. It’s not just when you log in to your computer to check your bank account; it’s when you message a friend to arrange to meet for lunch, it’s when you tap your card to pay for that lunch, and it’s when you’re reading this article. Take a look at the browser bar, and chances are you will see ‘https’ at the start of the web address rather than just ‘http’. That ‘s’ at the end means that no one online can tamper with what you are reading. The web page is being sent securely to your device via a protocol called TLS, encrypting all communication between your computer and this site.

So why is it such a concern for end-to-end encryption? Well Public Key Cryptography or Asymmetric Cryptography is built around the idea of certain problems being hard to solve, and one of these is what’s called the Integer Factorization Problem. Now, this is a bit counterintuitive but it’s based on the premise that while two numbers are very easy to multiply together, it is surprisingly difficult to divide that result back into its prime factors without first knowing them. The difficulty in calculating the two factors in computing terms equates to Computational Hardness. And Public Key Cryptography is a big part of end-to-end encryption.

> Public Key Cryptography is where a publicly available key is used to encrypt a message and a privately stored key is used to decrypt it. The maths behind it is that this is what is called a one-way function, i.e., very easy to compute in one direction but substantially more difficult to reverse, provided you pick two sufficiently large prime numbers. Examples usually revolve around RSA as it is relatively easy to explain and understand, but the more common Public Key algorithm used is Elliptic Curve, which is built around something called the Discrete Logarithm Problem. At a low level, it’s possible to prove that the Discrete Logarithm Problem and Integer Factorization Problem can be mathematically reduced to the same problem, but for the moment it’s best to think of RSA being based on the Integer Factorization Problem and Elliptic Curves being based on the Discrete Logarithm Problem.

So, how does quantum computing fit into this? Well, one of the earliest quantum algorithms is called [Shor's Algorithm](https://en.wikipedia.org/wiki/Shor%27s_algorithm) and is designed to, well, efficiently divide a number back into its prime factors.  In real-world terms, Shor’s Algorithm is currently a while away from meeting this goal in any meaningful manner. The largest number reliably factored is 21 (that’s 7 x 3 for anyone needing a hand) back in 2012,  but when the infrastructure exists to support fully developed implementations, then it’s not too hyperbolic to say that it will be a bit of a game changer.

[Grover's Algorithm](https://en.wikipedia.org/wiki/Grover%27s_algorithm) is a search algorithm that does the same for symmetric encryption but the solution is much simpler, which we’ll go into a little later on.

![Quantum Computing](https://images.ctfassets.net/23aumh6u8s0i/7L8e9elBfIZonTzxZDhPxh/4b95a9a75f7d82da0d43e29dc2ff330f/quantum-sep3.jpg)

One of the driving forces behind developing Post-Quantum Cryptography, or PQC, is the concern that with storage currently being so cheap, it is easy for criminals to stockpile data harvested from security breaches in preparation for when Quantum Computers are available, an approach known as Harvest Now, Decrypt Later, or Retrospective Decryption. Whilst some would argue against preparing for a technology that is a while away from maturity, these attacks are certainly technically feasible. All they involve is the intercepting and (more importantly) storing of a large amount of data that will still have value in 5/10/20 years time. It might not sound plausible that criminals would be that far thinking, however given the longevity of identifiable information, it's easy to see that captured data may still have value, and with storage being very affordable, it doesn’t require too much outlay on the chance that it will. Some predict that Quantum computers will be able to break classical encryption by 2030. Think back to where you were in 2018. Six years isn’t that long, is it? So, ultimately, the concern has changed: it’s not just what is to be kept secret, it’s also how long it needs to stay secret.

## Post-Quantum Cryptography Solutions

No great change is required to the core of asymmetric cryptography in order to make it Quantum secure. It’s still based on the difficulty of solving certain mathematical problems. So, if we want to make an encryption algorithm Quantum secure, we must ensure that the problem it is built around is sufficiently hard. This has a knock-on effect on verifying the security of the algorithms, as cryptography algorithms are validated by cryptographers rather than mechanical means, and the hardness of the problems means that there are fewer cryptographers qualified to do so.

There are six different approaches currently being worked on in Post-Quantum Cryptography:

- Lattice-based cryptography
- Multivariate cryptography
- Hash-based cryptography
- Code-based cryptography
- Isogeny-based cryptography
- Symmetric key Quantum resistance

Out of all of them, symmetric keys are the easiest to harden for Quantum Computing attacks, relatively speaking. In fact, in order to meet the same level of security strength (based on computational hardness) for a Post-Quantum algorithm as for a classical one, the key size can simply be doubled. This is because the computational hardness of symmetric key algorithms is based on the size of the keyspace rather than the difficulty of any problem to solve. So, to meet the same level of security currently offered by AES-256, you will need to use 512-bit keys.

Lattices are a mathematical construct based around matrices, which are arrangements of numbers in rows and columns. One of the more popular algorithms is called [Learning With Errors](https://en.wikipedia.org/wiki/Learning_with_errors), where the Error (a row of values) is added to the result of two matrices, providing the ‘difficulty’ in retrieving the result from the first factor. This can be represented formulaically as `ax+e = b`, where `a` and `b` make up the public key, and `x` and `e` make up the private key.

Hash-based cryptography involves using cryptographically secure hash functions to generate a private and public key for signing and is considered one of the more fully understood approaches. Lattice-based cryptography and Hash-based approaches have proved to be the most fertile ground for asymmetric solutions, leading to them making up the majority of the submissions for standardization by NIST.

## NIST Recommendations

The body that decides which encryption algorithms become standards isn't the NSA or one of the other three-letter agencies you might think of. Instead, it’s the National Institute for Standards in Technology, a subsection of the U.S. Department of Commerce whose job it is to cover both the algorithms and the key strengths recommended for guaranteeing high security. Established in 1901 as the National Bureau of Standards, NIST is responsible for fostering technological innovation and economic competitiveness in the United States. They first became part of the cryptography landscape as part of the first Government project to develop a publicly available cryptographic standard to satisfy a broad range of requirements and use cases, rather than leaving it to the military as had previously been the case.

An open call was made in the early 1970s for people and companies to submit candidate algorithms, and after receiving a submission from IBM called Lucifer, NIST chose that algorithm as the basis for its proposed [Data Encryption Standard (DES)](https://en.wikipedia.org/wiki/Data_Encryption_Standard). Offering only 56 bits of encryption, it wasn’t long before this proved to be wanting in overall security terms, as the hardware needed to crack DES encryption started to become less cost-prohibitive as time went on, and several public competitions were held in the late 90’s with the express goal of breaking DES. It was reconfigured as Triple DES in an attempt to extend its shelf life (literally just running the DES algorithm three times to give 112 bits of security), but it soon became clear that a new standard was required. This was followed up with the replacement, [Advanced Encryption Standard (AES)](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) in 1997, an implementation of the Rijndael Encryption Algorithm, selected from a list of viable candidates from another public competition.

![Data Encryption Standard](https://images.ctfassets.net/23aumh6u8s0i/1459k5sEGn3nETjOL2CIVP/8d1b15fe4602127fb343c8fe727c3152/quantum-sep2.jpg)

Encryption doesn’t stand still though, so NIST needs to keep updating its standards to meet the evolving security requirements. Since 2016, they have been running rounds of evaluation as part of their PQC Standardization Process, asking cryptographers to devise and vet encryption algorithms that could resist attacks from a Quantum computer. This has been done in the open to allay any concerns of the algorithm being tampered with, such as in the case of [Dual EC DRBG](https://en.wikipedia.org/wiki/Dual_EC_DRBG), a random number generator that was believed to have a backdoor inserted by the NSA.

Nist started with 82 candidate algorithms nominated. 69 of these were chosen to progress, and through four rounds of judging this was whittled down to the four current standardized algorithms in 2022.

### CRYSTALS-Kyber

Renamed by NIST as the Module Lattice-Based Key Encapsulation Mechanism (ML-KEM), this is based on the Learning With Errors (LWE) Lattice problem and is intended to be used for general encryption. It replaces Quantum vulnerable algorithms such as Elliptic Curve Diffie-Hellman (ECDH), i.e., any which use a public/private key pair to share a key that can then be used for symmetric encryption.

There are three parameter sets defined by the standard:

- Kyber-512, offering security equivalent to AES-128
- Kyber-768, offering security equivalent to AES-192
- Kyber-1024, offering security equivalent to AES-256

### CRYSTALS-Dilithium

Renamed by NIST as Module Lattice-based Digital Signature Algorithm (ML-DSA), this is a digital signature intended to offer a Quantum-secure replacement for ECDSA and RSA, i.e., any use case which involves using a public/private key pair to authenticate data.

There are three parameter sets defined by the standard:

- ML-DSA-44, offering security equivalent to SHA3-256
- ML-DSA-65, offering security equivalent to AES-192
- ML-DSA-87, offering security equivalent to AES-256

### SPHINCS+

Renamed by NIST as Stateless Hash-based Digital Signature Algorithm (SLH-DSA). Unlike all the other algorithms, this is the only non-Lattice-based solution and is instead a Hash-based approach.

There are twelve parameter sets defined by the standard. These are based on using either SHA2 or SHAKE as the hash algorithm and 128, 192, or 256 bits of security, eg SLH-DSA-SHA2-128s uses the SHA2 hash algorithm and offers security equivalent to AES-128.

### FALCON

This is a Lattice-based solution but is still to receive a draft standard. This is taking longer due to the difficulty of implementing it, but it is due later this year (2024).

Three additional algorithms are still under consideration: BIKE, Classic McEliece, and HQC, all code-based cryptography. The popular SIKE (Supersingular Isogeny Diffie–Hellman Key Exchange) was originally in this list but was found to be classically broken by a group of Belgian researchers, who were able to recover a key within 62 minutes running on an [Intel Xeon computer](https://eprint.iacr.org/2022/975.pdf). NIST unsurprisingly decided not to standardize SIKE. This was built around the Supersingular Isogenies Problem, which seems to have been enough to dissuade further development around this particular problem.

## Conclusion

Hopefully, you’re all a little clearer by now on why this is important and also why it has taken a long time to get here. Taking the joke from the start of this post as a warning, the U.S. is aiming to transition its cryptographic systems to Quantum-resistant algorithms by 2035, and recently, both Apple iMessage and Signal have upgraded their protocols to incorporate the CRYSTALS-Kyber algorithm and become Quantum-resistant. So, while this is a complex area and there are too few people around who understand it, the progress made is promising, and the joke is slowly becoming a reality.

### References

- [NIST: PQC Standardization Overview](https://csrc.nist.gov/projects/post-quantum-cryptography)
- [NIST: PQC Standardization Call for Proposals](https://csrc.nist.gov/CSRC/media/Projects/Post-Quantum-Cryptography/documents/call-for-proposals-final-dec-2016.pdf)
- [Wikipedia: Hidden Subgroup Problem](https://en.wikipedia.org/wiki/Hidden_subgroup_problem)
- [CACM: NIST Post-Quantum Cryptography Candidate Cracked](https://cacm-preview.acm.org/news/nist-post-quantum-cryptography-candidate-cracked/)

Post-Quantum Cryptography: Preparing for the Future of Security

Verifiable Credentials can be stored on digital devices, and you can use cryptography to verify their data and authorship. Let's learn more about them and why you should care about them.

We often use physical credentials such as our passports or driver's licenses as proof of identity. Until recent years, these types of credentials have usually been used in-person or offline, but nowadays, it's possible to prove your identity through digital credentials on the web in a cryptographically secure, privacy-respecting, and machine-verifiable way. In this blog post, you'll learn about these verifiable credentials, why you should use them, and when. 

## What are Verifiable Credentials?

When you think about a credential, you can often think of a physical credential like a passport, a driver's license, or an employee badge. A credential refers to a [set of one or more claims made by an issuer](https://www.w3.org/TR/vc-data-model/#dfn-credential); in the passport example, the photo, name, or identification number are the claims made by a government to identify a subject. 

When we talk about Verifiable Credentials (VCs), we are referring to a [W3C standard](https://www.w3.org/TR/vc-data-model/) for digital, cryptographically verifiable credentials. These credentials can represent the same information as a physical credential, but they add the use of digital signatures, making them more trustworthy than their physical version. You can store them on your device, which makes them more convenient and available almost everywhere. 

In the verifiable credentials context, there are a few important roles:

- **Holder**: it's the entity that possesses the verifiable credential. Holders could be, for example, students, employees, and customers. 
- **Issuer**: the entity that asserts claims about the subject, creates and transmits the verifiable credential to the holder. For example, governments, corporations, and non-profit organizations can be issuers. 
- **Subject**: the entity about which claims are made. For example, human beings, animals, and things. 
  - Often, the holder of a verifiable credential and subject can be the same, but only sometimes. For example, a parent can be the holder of the verifiable credential of their child (subject)
- **Verifier**: the entity that receives and processes verifiable credentials, such as employers, security personnel, and websites.   
- **Verifiable Data Registry**: the system that creates and verifies verifiable credentials schemas. For example, government ID databases and trusted databases. 

![VCs Roles](https://images.ctfassets.net/23aumh6u8s0i/4Gc0xRKUsczAlJ2w7JEh1/22f16ee9cfe9924b4a23f46638646649/vcs.png)

The image above shows how each entity interacts with each other. The issuer issues credentials to the holder as well as identifies and verifies the verifiable credentials. The holder acquires, stores, and presents VCs to the verifier. The verifier verifies VCs against the Verifiable Data Registry, which maintains identifiers and schemas. 

If we think of an example, let's say you are a citizen of the Asgard country. Asgard's government can issue a verifiable credential so you can prove your identity. 

![Asgard country issue VC](https://images.ctfassets.net/23aumh6u8s0i/35vmzFohdAtzKYw0drPXZ7/4a369f5669ef1133b750a9502fe3e8c5/holder-issuer.png)

In this example, the **holder** of the verifiable credential would be you because you are the owner of it and Asgard's government would be the **issuer**. This would be one of those scenarios where the **subject** would be the same as the holder because Asgard's government created claims for you, such as full name, identification number, and so on. 

Later on, let's say the Asgard police stop you and ask you for your ID. You decide to use your VC, and you have it in your wallet, so you **present** it to them. In this case they'd act as the **verifier** and check against Asgard's government database (the **Verifiable Data Registry**) that the VC is legit. 

![Present VC Asgard](https://images.ctfassets.net/23aumh6u8s0i/1SLhpBZvsGcEuJDQypUuqt/ff34ca49671651f75d9b23af70d18885/holder-presenter.png)

## Verifiable Credentials Are Necessary 

Verifiable Credentials have many use cases in our day-to-day life, and as we move more into an online world, [we need to be able to disclose our identity without issuers knowing](https://auth0.com/blog/our-take-on-verifiable-credentials/#The-Reason-We-Believe-VCs-Will-Happen). Because VCs are available in your wallet, you can use them "offline", meaning the issuer doesn't know when and how often you use them. This is what makes VCs so powerful: they are convenient, and having them available in your wallet removes a lot of friction from a user's life. So, let's go ahead and explore some use cases. 

### Legal Identity 

It's essential that you're able to prove your identity in a way that can be quickly verified, and governments are in the position to provide such identification in a verifiable digital form. Some examples are:

- Digital Driver's License
  - You get stopped over a traffic violation; with a digital driver's license, you always have access to it, and you can use it to prove to the officers both your identity and that you can drive. 
- Digital passports 
  - The electronic passport can contain a list of all the places you've visited and visas, so immigration officers can quickly and easily evaluate your suitability when visiting a new country. 
- Proof of Birth
  - Imagine asking for refuge in a country in such desperate conditions that you don't have your physical credentials. Still, you were issued a [self-sovereign](https://en.wikipedia.org/wiki/Self-sovereign_identity) proof of birth, and attached to this is the proof of birth and marriage of your parents; since it's verifiable, you can show this at the border controls of the country you're seeking refuge.

### Finance 

In finance, we can think of banking, brokerage, insurance, etc. Some example use cases are: 

- Money transfers
  - Let's say you want to send money to your family abroad; you can share your identity profile as well as your family member's with the money transfer service. This allows them to verify the source and destination of funds automatically.
- Opening or closing bank accounts 
  - If you want to open an account, you can use your government-issued certificate to prove your identity. Later on, when you want to close the account, the bank needs to revoke the "account owner" claim as part of the closing account process. 

### Healthcare

In the healthcare industry, privacy is extremely important, and with VCs, we can guarantee that the holder of the credential can disclose only the information they need. Let's understand some use cases in this area: 

- Prescribed medicine
  - A pharmacy can receive a prescription for medication for a patient. The pharmacy can automatically verify the doctor's ability to write prescriptions and the patient's insurance coverage. 
- Proving Legal Disability Status 
  - You can have government-issued disability credentials without having to disclose your specific disability to the service or entity you're providing. Issuers can issue verifiable credentials that support [selective disclosure](https://www.w3.org/TR/vc-data-model/#dfn-selective-disclosure) so holders can present proof of claims without revealing the entire verifiable credential. 

### Professional Credentials 

You may need a prove that an entity is who they say they are, and they can do what they say. This allows you to trust universities, doctors, companies, etc. 

- Doctors 
  - Health providers could provide information about the doctors they have on staff, including verifiable credentials about their education, board certification, etc. 
- University Degrees 
  - You could verify someone's obtained degree from a university that has a digital certificate to issue verifiable credentials. 
- Companies 
  - You can have an electronic badge that proves your identity to your company. 


## How Does a VC Look Like?

Let's take a look at what a verifiable credential looks like. Let's think of someone's ID card: 

```json
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1"
  ],
  "type": ["VerifiableCredential", "IDCard"],
  "id": "urn:credential:34502108-4540",
  "issuer": "did:web:asgard-state.auth0lab.com",
  "issuanceDate": "2020-07-20T13:58:53Z",
  "credentialSubject": {
    "id": "urn:id-card:personal:1",
    "personalIdentifier": "34502108",
    "name": "Hanna Herwitz",
    "dateOfBirth": "1984-09-17",
    "placeOfBirth": "Asgard City",
    "currentAddress": "24th Street 210, Asgard City, 1023",
    "gender": "Female"
  },
  "credentialStatus": {
    "id": "https://asgard-state.auth0lab.com/vcs/credential/status/14",
    "type": "CredentialStatusList2017"
  }
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2020-07-20T13:58:53Z",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "https://asgard-state.auth0lab.com/keys/1",
    "proofValue": "z2ty8BNvrKCvAXGqJVXF8aZ1jK5o5uXFvhXJksUXhn61uSwJJmWdcntfqvZTLbWmQHpieyhdcrG43em37Jo8bswvR"
  }
}
```

This JSON represents the digital version of Hanna Herwitz's ID card. Let's take a look at some of the most relevant parts of the VC: 

### Type 
The credential type can be used to determine if a specific credential is appropriate for a particular use case. In the example above, the type value is ` ["VerifiableCredential", "IDCard"]`.

### Issuer 
Represents the issuer of the credential and has to be a URI or an object containing an ID property. The example above is the Asgard government with the value `did:web:asgard-state.auth0lab.com`. Note that the value starts with `did`; this is a [Decentralized Identifier](https://www.w3.org/TR/did-core/), a new identifier enabling verifiable, decentralized digital identity. However, it's not mandatory to use DIDs. 

### Credential Subject 

Refers to the subject of the verifiable credential; it can be a DID or an object containing an id property. In the example above, the subject data is: 

```json
"credentialSubject": {
  "id": "urn:id-card:personal:1",
  "personalIdentifier": "34502108",
  "name": "Hanna Herwitz",
  "dateOfBirth": "1984-09-17",
  "placeOfBirth": "Asgard City",
  "currentAddress": "24th Street 210, Asgard City, 1023",
  "gender": "Female"
}
```

### Cryptographic Proof

It is one of the most essential parts and **what makes this credential verifiable**. Refers to cryptographic proofs (can be an object or an array) that can be used to detect tampering and verify the authorship of a credential or the data derived from the VC. In the example above: 

```json
"proof": {
  "type": "Ed25519Signature2020",
  "created": "2020-07-20T13:58:53Z",
  "proofPurpose": "assertionMethod",
  "verificationMethod": "https://asgard-state.auth0lab.com/keys/1",
  "proofValue": "z2ty8BNvrKCvAXGqJVXF8aZ1jK5o5uXFvhXJksUXhn61uSwJJmWdcntfqvZTLbWmQHpieyhdcrG43em37Jo8bswvR"
}
```

## Verifiable Credentials in Action 

Now that you know what a VC looks like, let's look at them in action. 

We've developed a site, [verifiablecredentials.dev](https://verifiablecredentials.dev), where you can play around and debug verifiable credentials. 


### Issue a VC 

To obtain a new verifiable credential, navigate to [wallet.verifiablecredentials.dev](https://wallet.verifiablecredentials.dev/), where you'll see a demo wallet where you can start by adding your first VC. 

![ID Wallet Add VC](https://images.ctfassets.net/23aumh6u8s0i/5cQaJh6drruR9bx86ZnSAR/3978c6e7e745ac70152a91d00da61f06/Screenshot_2024-01-16_at_13.37.27.png)

Follow the steps, and you'll create your verifiable credential! 🎉

![ID Wallet VC created](https://images.ctfassets.net/23aumh6u8s0i/6S3VrXJpueAeXvqaE3vl05/7042036ccc4d40524cf352a55f224c50/Screenshot_2024-01-17_at_17.30.14.png)

### Present a VC 

You can use the [Presentation Debugger tool](https://verifiablecredentials.dev/presentation) to create a request that defines the characteristics you want a Verifiable Presentation to meet.

You can use ID Wallet to see your verifiable credential data in the Presentation Debugger tool.

![Presentation tool](https://images.ctfassets.net/23aumh6u8s0i/10ykc9VwNiJs2hLDeV6PEI/dfcaac31665344445c3087ff92f7d99b/Screenshot_2024-01-17_at_17.29.27.png) 

## Conclusion 

Verifiable Credentials are digital, cryptographically signed credentials that you can use in many aspects of your life. There are many use cases in healthcare, education, and legal contexts where VCs are extremely useful. 

Users need the means to exercise their identity and disclose their claims without issuers knowing, the same way they do offline. 

If you want to learn more about VCs, go to [verifiablecredentials.dev](https://verifiablecredentials.dev), where you can play around and create and present verifiable credentials.

What are Verifiable Credentials and Why You Should Care About Them

Pradheepa Pullanieswaran

Pradheepa Pullanieswaran is a Developer Advocate at Okta, with a real love for backend and open-source technologies. She has worked in enterprise and web technologies for over a decade and now on the journey of helping developers to better secure their application. She is also an active member of Women Who Code and mentors women to step into the software industry. She loves to read and spends time with her family in her spare time.

Staff Developer Advocate

Web Authentication API (WebAuthn) is a W3C and FIDO specification that allows registration and authentication of users using public key cryptography instead of a password.

## Introduction

WebAuthn (Web Authentication) is an API specification by W3C that facilitates a secure way for users to log in to online services and websites using various authentication methods, such as biometrics (e.g., fingerprint or facial recognition) and hardware-based authenticators (e.g., USB or NFC tokens). 

## Key Features of WebAuthn

### Phishing resistant

WebAuthn uses [public key cryptography](https://auth0.com/blog/how-to-explain-public-key-cryptography-digital-signatures-to-anyone/); the user's private key never leaves their device. Since WebAuthn relies on cryptographic keys, it is resistant to phishing attacks. Assuming that a bad actor tricks the user into entering their credentials on a phishing site, the attacker cannot use those credentials because they are scoped to a specific domain. In short, a credential created for `webauthn.me` cannot be used by a fake website, `webauth.me`. According to [Verizon DBIR 2023](https://www.verizon.com/business/resources/reports/2023-data-breach-investigations-report-dbir.pdf), Phishing is one of the major attacks on a web-based application, as shown in the following image. Using WebAuthn, the web applications could have easily averted these attacks. 
   
#### Action varieties in Social Engineering incidents

![Action varieties in Social Engineering incidents](https://images.ctfassets.net/23aumh6u8s0i/EAHiNaQrRaclMm2OnR1TA/cc50a06eef6af456d6a02f74731d4f6e/Phishing_DBIR.png)
 
### High-Security standards 

WebAuthn leverages industry-standard cryptographic algorithms and protocols to ensure the highest level of security. It utilizes the [authenticators](https://auth0.com/blog/not-all-mfa-is-created-equal/#Factors--Authenticators--and-Assurance) to confirm the user's identity and create highly secure public-private key credentials. There are two types of authenticators: roaming authenticators, like hardware security keys, and platform authenticators, like your laptop or device, that support biometrics, such as fingerprint recognition, facial recognition, and voice recognition, depending on the capabilities of the user's device.

### Seamless user experience

With WebAuthn, users can authenticate with a single gesture or action, providing a convenient and frictionless login experience. While delivering a seamless and convenient authentication experience for users, it also enhances security.

## WebAuthn Roles

**Relying Party** - This is the website or online service the user wants to access. The relying party initiates the WebAuthn authentication process and verifies the user's identity.

**WebAuthn Client Device** -  The user's device (e.g., smartphone, computer) that supports WebAuthn and communicates with the relying party. It is capable of hosting the private keypair in secret storage that a user can access through biometrics or PIN.

**User** -  The individual attempting to access a relying party's website or services.

**Authenticator** - There are two types of authenticators, i.e., Platform Authenticators and Roaming Authenticators. 
  
Platform Authenticators refer to a specific type of authenticator built into the user's device or platform, such as a smartphone, laptop, or desktop computer. For example, a smartphone's fingerprint sensor or a laptop's built-in biometric recognition system can act as a platform authenticator. 
  
Roaming Authenticators are authenticators not tied to any particular platform but can be used to authenticate across multiple devices. They are also sometimes referred to as cross-platform or external authenticators. e.g., hardware security keys like the YubiKey.

<include src="WebAuthnMeCTA" group="A"/>

## How WebAuthn Works

WebAuthn's mode of authentication consists of a Registration Flow and an Authentication Flow. With WebAuthn, there are no longer shared credentials between the user and the relying party. A public-private key pair is generated with the help of the authenticators and is used instead of the password. Let us look into the user journey of the registration and authentication flows.

### Registration flow

#### A User visits a website

The process begins when a user visits a website or a web application that supports WebAuthn for authentication and requests the website to create a new account.

#### Initiating registration

The website, often called the relying party, begins the registration process. It generates a unique and cryptographically random challenge and communicates to the user's browser that it wants to register a new public-private key pair for the user.

#### The User chooses an authenticator to generate a public-private key pair

The user selects their preferred authenticator, a platform authenticator (built into their device, e.g., fingerprint sensor), or an external authenticator (e.g., a hardware security key). The chosen authenticator generates a new public-private key pair for the user and signs the challenge generated by the relying party with those keys. 

#### The Authenticator sends back the user credentials

The private key is securely stored within the authenticator, while the public key is sent back to the website along with the signed challenge and an optional private key ID.

#### The Website stores the user credential

The website stores the user's public key and the private key ID (if sent) and associates it with the user's account for future authentication; 

![WebAuthn Registration Flow](https://images.ctfassets.net/23aumh6u8s0i/6tOAUn8BVSqRrvnoe9fekn/d4614b12e493faeefc6d3cfaf36f3245/WebAuthn_Registration_Flow.png) 

The registration process is completed, and no more shared secrets are exchanged over the network between the user and the server, eventually reducing the risk of stolen credentials.

### Authentication flow

Once the user's registration is complete, the returning user can verify the credentials and log in to the application. Following are the steps that take place in the authentication flow for the user.

#### User returns to the website 
When users return to the website to access the protected resources, the web application prompts the user to authenticate. The user provides the username to the server.

#### Website generates an authentication challenge
The website generates a new challenge and sends it to the user's browser.

#### User requests authenticator to sign the challenge
The user selects the authenticator they used during registration, or the authenticator may be automatically detected and requested to sign the challenge. 

#### Authenticator signs the challenge
The authenticator signs the challenge using the private key stored during the registration flow. The authenticator sends the signed response and the public key back to the website.

#### User verification
The website receives the signed response and the user's public key. It verifies the response by checking the signature against the stored public key. If the verification is successful, the website grants the user access to the requested resources.

![Authentication Flow](https://images.ctfassets.net/23aumh6u8s0i/5gbfSpwf2b3EOAP4gP1elm/ae3db34de58eca086f963d06303c54cb/WebAuthn_Authentication_Flow.png)

The user is authenticated securely without a password and with less friction to the user.

## How to Implement the WebAuthn API

Two methods in the WebAuthn API mediate between the user and the server to create the public-private key pair.

1. `navigator.credentials.create`
2. `navigator.credentials.get`

### Using the "navigator.credentials.create" method

The `navigator.credentials.create` method is used to initiate registering a new credential for a user. This method allows users to create a new credential, such as a public-private key pair, which can be used for secure authentication in the future. Here's how you can use `navigator.credentials.create`.

#### Prepare credential creation options
You need to define the options for the credential creation request. These options specify various credential creation parameters, such as the relying party ID (your website's domain), user information, and allowed authenticator types (e.g., platform authenticator or external security key).

Here's an example of how to create credential creation options:

```
const publicKey = {
  challenge: new Uint8Array(/* Generate a random challenge */),
  rp: {
    name: 'Webauthn Me', // Relying party name
    id: 'webauthn.me',     // Relying on party ID
  },
  user: {
    id: new Uint8Array(/* Generate a unique user ID */),
    name: 'jane.doe@example.com',
    displayName: 'Jane Doe',
  },
  pubKeyCredParams: [
    { type: 'public-key', alg: -7 }, // ES256 algorithm
  ],
  timeout: 60000, // 1-minute timeout
  attestation: 'direct', // Attestation type
};

```

The following section describes each variable in detail.

- `challenge`: A challenge is a random value generated by the server and included in the registration request that helps to prevent replay attacks. The challenge serves as a nonce (number used once), ensuring that each registration request is fresh and not subject to replay. It prevents attackers from intercepting and reusing a valid registration message to gain unauthorized access. The server should validate the response promptly and reject it if the challenge has expired or does not match.
- `rp`: The relying party is the entity that relies on WebAuthn for authentication. For example, it is the domain of the website that implements WebAuthn to enable secure user authentication. Validating the relying party information helps prevent phishing attacks.
- `user`: Information about the user who wants to register.
- `pubKeyCredParams`: It is an array that specifies the acceptable public key algorithms and parameters for the generated credential. The array consists of two properties,
    1. `type`: A string indicating the cryptographic algorithm to be used. Common values include "public-key" for ECDSA (Elliptic Curve Digital Signature Algorithm) or "rsa" for RSA (Rivest–Shamir–Adleman)
    2. `alg`: An integer representing the specific algorithm within the given type. For example,`-7`representing ES256 for ECDSA with SHA-256.
- `timeout`: The time limit for the credential creation process.
- `attestation`: The attestation parameter specifies how the authenticator (e.g., security key, biometric device) should attest to the authenticity of the public key credential it generates during the registration process. The attestation parameter can take different values, each representing a different attestation type. Common values include:
    1. `none`: No attestation is requested. The authenticator generates a credential without any assertion of its authenticity. This is suitable for scenarios where the relying party already has a secure means of verifying the authenticator.
    2. `direct`: The authenticator provides an attestation statement, but the format and content depend on the authenticator type. This is also known as "self-attestation."
    3. `indirect`: The authenticator forwards an attestation statement obtained from a third-party service, typically the manufacturer or a trusted party.

#### Call "navigator.credentials.create"
Use the `navigator.credentials.create` method to initiate the credential creation process.

```
navigator.credentials.create({ publicKey })
  .then((credential) => {
    // Handle the successful credential creation
    // Send the credential information to your server for storage
  })
  .catch((error) => {
    // Handle any errors that occurred during credential creation
  });

```
`publicKey`:  It is the variable defined in the previous step. 

#### Handle the Credential Creation Response
If the user successfully creates a credential, the `navigator.credentials.create` promise will resolve with a credential object. You should send this credential object to your server for storage and associate it with the user's account.

```
// Handle the successful credential creation
// Send the credential information to your server for storage
navigator.credentials.create({ publicKey })
  .then((credential) => {
    // Response object has information about the authenticator data, 
    // public key, transport mechanisms, and more.
    const response = credential.response;

    // Access attestationObject ArrayBuffer
    const attestationObj = response.attestationObject;

    // Access client JSON
    const clientJSON = response.clientDataJSON;

    // Return authenticator data ArrayBuffer
    const authenticatorData = response.getAuthenticatorData();

    // Return public key ArrayBuffer
    const pk = response.getPublicKey();

    // Return public key algorithm identifier
    const pkAlgo = response.getPublicKeyAlgorithm();

    // Return permissible transports array
    const transports = response.getTransports();
    
    // Send the credential information to the server for storage
    return credential;
  })
  .catch((error) => {
    // Handle any errors that occurred during credential creation
    console.log('FAIL', error)
  });


```

If the credential creation fails or if there are errors, the promise will be rejected, and you can handle the errors accordingly.

Remember that the server-side storage and management of user credentials are essential for the WebAuthn authentication process. The server should securely store the user's public key and other relevant information to enable future authentication.

### Using the "navigator.credentials.get" method

The `navigator.credentials.get` method is part of the WebAuthn API and is used to initiate the process of authenticating a user based on the credentials they have previously registered. This method is typically used in conjunction with the `navigator.credentials.create` method for credential registration. Here's how you can use this method.

#### Prepare authentication options
You need to define the options for the authentication request. These options specify the criteria for the user's credentials for authentication. You can include the relying party ID (e.g., your website's domain) and specify the allowed authentication methods.

Here's an example of how to create authentication options:

```
const publicKey = {
  challenge: new Uint8Array(/* Generate a random challenge */),
  rpId: 'webauthn.me', // Relying party ID
  allowCredentials: [
    {
      type: 'public-key',
      id: /* The credential ID of the user's registered credential */,
    },
  ],
  userVerification: 'preferred', // or 'required'
};
```

The following section describes each variable in detail.

- `userVerification:` It specifies the preferred user verification method that the relying party wishes to be performed during the WebAuthn authentication process. The [userVerification parameter](https://developers.yubico.com/WebAuthn/WebAuthn_Developer_Guide/User_Presence_vs_User_Verification.html) can take different values, each representing a different user verification method. Common values include `required`, `preferred`, and `discouraged.`
- `allowCredentials:` It is an array that contains one or more "PublicKeyCredential" objects representing the credentials that the relying party is willing to accept during the authentication process. Each element in the allowCredentials array is an object with the following properties: 
  1. `type`: A string specifying the type of the credential. Commonly, this is set to "public-key".
  2. `id`: A byte array representing the credential ID. This corresponds to a credential that was previously created during the registration process.
- `challenge` and  `rpId` are the same parameters used for the `navigator.credentials.create` method.

#### Call "navigator.credentials.get"

Use the `navigator.credentials.get` method to initiate the authentication process:

```
navigator.credentials.get({ publicKey })
  .then((assertion) => {
    // Handle the successful authentication assertion
  })
  .catch((error) => {
    // Handle any errors that occurred during authentication
  });
```

`publicKey`:  It is the variable defined in the previous step.

#### Handle the authentication response
If the user successfully authenticates, the `navigator.credentials.get` promise will resolve with an authentication assertion containing information about the user's successful authentication. You can then send this assertion to your server for verification.

```
// Handle the successful authentication assertion
// Send the assertion to your server for verification
navigator.credentials.get({ publicKey })
  .then((assertion) => {
    // Handle the successful authentication assertion
    // The assertion response has information about the authenticator data, 
    // signature, and user handle
     const response = assertion.response;

    // Access authenticator data ArrayBuffer
    const authenticatorData = response.authenticatorData;

    // Access client JSON
    const clientJSON = response.clientDataJSON;

    // Access signature ArrayBuffer
    const signature = response.signature;

    // Access userHandle ArrayBuffer
    const userHandle = response.userHandle;

    return assertion;
  }).catch((error) => {
    // Handle any errors that occurred during authentication
    console.log('FAIL', error)
  });
```

If the authentication fails or if there are errors, the promise will be rejected, and you can handle the errors accordingly.

Remember that the server-side verification of the authentication assertion is an essential part of the process. The server should validate the assertion's signature and ensure that it matches a previously registered credential for the user.

These steps provide a high-level overview of how to use `navigator.credentials.create` and `navigator.credentials.get` in the WebAuthn API for user authentication. The actual implementation will vary based on your specific use case and server-side verification requirements.

## Conclusion

WebAuthn offers a passwordless and highly secure alternative to traditional authentication methods. Leveraging public key cryptography, user verification methods like biometrics, and a challenge-response model, WebAuthn effectively mitigates the risks associated with phishing attacks and enhances online security. It's important to note that while WebAuthn is phishing-resistant, it is not immune to all types of attacks. Therefore, proper implementation and security best practices on both the client and server sides are crucial to harness the security benefits of WebAuthn fully. [Auth0 supports WebAuthn](https://auth0.com/blog/mfa-with-webauthn-for-fido-device-biometrics-now-available/) and adheres to industry best practices and security standards, removing the heavy lifting of implementing on your own. It is a simple toggle switch in the configuration to show up in your login box, and all the background processing is taken care of by Auth0.

<include src="SignupCTA" text="Try out WebAuthn with Auth0?" linkText="Get started →" />

WebAuthn - A Short Introduction

arthur-bellore

I’m a tech content creator. I enjoy breaking up seemingly complicated topics into easy-to-understand pieces for people to read. When I’m not in front of a computer, you’ll usually find me reading books.

Cybersec Writer

Arthur Bellore

Transport Layer Security (TLS) is the cryptographic protocol behind pretty much any computer network used today: from web browsing to email, APIs, and VoIP. But how exactly does it work?

## SSL vs. TLS

SSL, or Secure Sockets Layer, is the predecessor to TLS. It was a cryptographic protocol developed by Netscape in 1994, but since it had serious flaws, it was never released to the public. SSL 2.0 was released publicly one year later, in 1995, but it, too, was found to have serious flaws. Finally, SSL 3.0 was rebuilt from the ground up and released in 1996.

Microsoft, who had its own version of the protocol, and Netscape agreed to hand over the project to the Internet Engineering Task Force (IETF) and make it an open standard. As part of the deal, the name was changed to TLS, Transport Layer Security, to signify that it no longer had ties with Netscape.

The first upgrade to SSL 3.0 was published in 1999 in [RFC 2246](https://datatracker.ietf.org/doc/html/rfc2246) as TLS 1.0. Tim Dierks, the editor of RFC 2246, has said [in his blog](https://tim.dierks.org/2014/05/security-standards-and-name-changes-in.html) that TLS 1.0 was really SSL 3.1, but they changed the name “so it wouldn’t look the IETF was just rubberstamping Netscape’s protocol.” Indeed, if you look at RFC 2246, it says:

This document describes TLS Version 1.0, which uses version { 3, 1 }. Version value 3.1 is historical: TLS version 1.0 is a minor modification to the SSL 3.0 protocol, which bears the version value 3.0.

TLS became the standard of encryption and authentication over computer networks, and it’s still being used today. The most recent version of the protocol is TLS 1.3, which was released in August 2018.

### What is the difference between SSL and TLS?

SSL hasn’t been updated since its release in 1996, and it was deprecated in 2015 in [RFC 7568](https://datatracker.ietf.org/doc/html/rfc7568). Most [modern browsers disable it by default](https://en.wikipedia.org/wiki/Version_history_for_TLS/SSL_support_in_web_browsers) or don’t support it outright anymore.

Despite this, because of the association between the two, many people still use the term SSL when they really mean to say TLS. Vendors typically use the same terms their target customers use to facilitate messaging, so their marketing collateral generally contains terms such as “SSL/TLS” or “SSL,” even though SSL is deprecated.

We now know that SSL and TLS are different things, but for the remainder of this article, SSL will be used interchangeably with TLS to match its everyday usage.

## Why SSL/TLS Was Created

For two computers to communicate with each other, they must perform a set of agreed-upon operations in a specific order. A **protocol** is what dictates those operations. The HTTP protocol is the protocol that web servers and clients use to establish a connection and communicate with each other through the Internet.

It works roughly as follows:

1. The server listens for new connections on port 80
2. The client connects to the server, and this starts a chain of operations as set forth by the HTTP protocol
3. The client sends a GET request to the server; the server receives the request, processes it, then sends back a response: headers and index.html, plus other content it might need to serve (CSS files, JavaScript files, cookies, etc.) for the client to render the content correctly.

This works to distribute content between two remote computers, but there is a problem: HTTP was intended to expand the local knowledge management tools throughout the multiple computers at CERN in the late 1980s, so it was designed as a clear text protocol.

Because it’s clear text, a malicious actor could insert themselves between client and server and potentially read sensitive information, such as credit card numbers or passwords, or they could intercept the client’s requests and serve back malicious files pretending to be server.

As the Internet evolved and the number of sensitive information flying around increased exponentially, an encryption layer sitting below HTTP was necessary. However, this is a bit tricky: if a bad actor can “listen in” the conversation between client and server while the connection is unencrypted, how can they exchange encryption keys securely?

One option would be for the two parties to create a public-private key pair and send over the public key pair to the other party, so they can use that to encrypt their packet before sending them over the wire.

The problem with this is that asymmetric (public-key) cryptography is _much slower_ than symmetric cryptography.

The "strength" of asymmetrical cryptography relies on modular arithmetic, mathematical operations that are very hard to do in the opposite direction. The numbers used in these operations need to be big enough to provide the necessary security, but performing arithmetic with very large numbers can be taxing on a CPU.

Symmetric cryptography, on the other hand, works differently and does not suffer from this problem. On top of that, most devices have AES instruction sets integrated into their CPUs to speed up AES operations, making AES encryption have almost zero overhead on modern devices.

The TLS protocol gets around this issue by using asymmetric cryptography to exchange keys at the beginning and then switch to symmetric keys (“sessions keys”) from then on in a process known as the TLS handshake.


## TLS handshakes

The exact steps of the TLS handshake will depend on which TLS version is supported by the client and server, as well as which parameters they are set to use.

Since most modern browsers still support TLS 1.2 and a lot of websites still use TLS 1.2 (according to a [paper published by Syed-Winkler](https://www.grin.com/document/1037281), as of February 2021, TLS 1.3 is supported by 42.9% of surveyed websites, while TLS 1.2 is supported by 99.3%), we will talk about TLS 1.2 first and then discuss how TLS 1.3 differs from 1.2.


### The TLS 1.2 handshake

TLS 1.2 can be configured to use many key exchange algorithms, and among them, the most well-known and widely used is the RSA key exchange algorithm. Let’s go over how the RSA algorithm works in TLS 1.2, then talk about how the process differs in TLS 1.3 with the [Diffie-Hellman](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange) (DH) key exchange algorithm.

The RSA key exchange works roughly as follows in TLS 1.2:

1. **Server listens for new connections on port 443.**
2. **Client connects to port 443 and initiates the handshake process with a ClientHello message to the server.** This message contains the TLS versions and cipher suites the client supports and a 32-byte random number known as Client Random.
3. **Server says “hello” back with a ServerHello message.** The server selects a cipher and the TLS version from the list provided by the client, then generates a different 32-byte random number known as Server Random and sends it all back along with the server’s own SSL certificate.
4. **Client uses the SSL certificate to verify the server’s identity.** SSL certificates contain a public key generated by the server and a digital signature signed with the private key of a trusted third party known as a certificate authority (CA). Most web browsers and operating systems come bundled with public keys from trusted CAs, which are used to verify that the CA issued the certificate.
5. **The client verifies the server has the matching private key to the certificate through ClientKeyExchange.** The client generates the pre-master secret (a 48-byte random number) and encrypts it with the server’s public key obtained from the certificate. If the server is the true owner of the certificate, it must be able to decrypt the message and obtain the original pre-master secret.
6. **Server decrypts the pre-master secret.** Now both the server and client have the pre-master secret, the Server Random, and the Client Random. They can use that to derive the master secret using the previously agreed cipher and arrive at the same (symmetric) key, which will become the session key once both parties verify their keys match.
7. **Client sends a ChangeCipherSpec message.** This indicates that the client is ready to create the session key and start communicating through an encrypted tunnel using that key.
8. **Client proves to server it has the correct keys.** The client hashes all handshake records up to that point, encrypts them with the session key, and sends them to the server. If the server generates the correct key, it will be able to decrypt that message and verify the record hashes (which the server can independently generate).
9. **Server proves to the client that it has the correct keys.** The server does the same thing and sends it to the client.
10. **A secure connection is established.** If both keys match, the TLS handshake is complete.

<br>
#### Problems with TLS 1.2

TLS 1.2 left a lot of its configuration parameters up to the users, which often resulted in bad choices (the old security adage of “among too many options, the worst one will be chosen”).

Additionally, in the name of backward compatibility, TLS 1.2 also allowed old, insecure ciphers to be used. (TLS 1.2 itself was released in 2008.) As time passed, it became more prone to attacks as vulnerabilities in older cipher or versions of TLS were discovered.

On top of all that, the RSA key exchange has a few weaknesses:

* **The same public-private key pair is used both to authenticate the server and to encrypt the pre-master secret (item #5 above).** If an attacker obtains the private key, they will be able to re-generate the session keys and be to decrypt the entire session.
* **There is no Perfect Forward Secrecy (PFS).** Since the server’s private key doesn’t change, an attacker might record and store encrypted data for years, hoping to decrypt it years down the line if the server’s private key is ever leaked or compromised.
* **Performance.** It’s necessary to make two round trips between the client and server until the session key is established.

To address these problems, the IETF began developing TLS 1.3 in 2013 and finally released it to the public in August 2018.

### What changed in TLS 1.3

In practice, the main differences between TLS 1.3 and 1.2 are:

* Shorter handshake
* Only supports key exchange algorithms with perfect forward secrecy (PFS), such as ephemeral Diffie-Hellman
* Support for 0-RTT (Zero Round Trip Time) resumption

This represents a bit of a paradigm change in TLS 1.3: shifting the focus from user configurability and backward compatibility to security by being more opinionated.

This allowed the designers to create a shorter handshake (by restraining DH as the only key exchange algorithm) but also prevented developers from choosing insecure options by restricting the number of options available in the first place.

For example, while it was technically possible to use DH as the key exchange method in TLS 1.2, the participants were responsible for setting the DH parameters. Picking the right parameters is crucial to make sure the DH exchange is secure, as some parameters can be trivially broken.

In 2015, security researchers [published a paper](https://weakdh.org/) describing how the WeakDH attack, which affected 8.4% of the top 1 million domains at the time, could trick servers into using small (insecure) DH parameters, enabling adversaries to decrypt data transmitted between client and server.

TLS 1.3 makes it impossible to use anything but a set of DH parameters that are believed to be secure.

### The TLS 1.3 handshake

Because there are significantly fewer options for the client and server to agree on, the TLS 1.3 handshake is much simpler:

1. **Server listens for new connections on port 443.**
2. **Client connects to port 443 and initiates the handshake process with a ClientHello message to the server.** Since the list of cipher suites was vastly reduced in TLS 1.3 (from 37 to 5), the client assumes the server is going to use one of the five. It proactively calculates a key pair for each of the cipher suites and sends it to the server along with the protocol version.
3. **Server calculates the key session.** With the client’s key share, the server is able to generate the session key.
4. **Server says “hello” back with a ServerHello message.** The server generates its own key share and sends it over to the client, so it also can generate the session key, along with the server’s encrypted SSL certificate (using the session key created on #3).
5. **Client generates master secret and a secure connection is established.** The client receives the server’s key share and calculates the session key. It decrypts and verifies the server’s certificates, and if everything is good, the handshake is complete.

Note that there are two different public-private key pairs on an ephemeral DH exchange: the first is the ephemeral pair, created every time client and server establish a connection, which guarantees forward secrecy. The second pair, embedded on the SSL certificate, is used for authentication and doesn’t change.

Given that a new key is generated for every session, this feature guarantees PFS. If the encryption keys are compromised at a later date, the leaked key will only be able to decrypt the specific session to which it corresponds; all the prior sessions are still safe. As a result, large-scale storage of data transmitted between server and client is rendered worthless.

## How Auth0 Can Help

The temptation to intercept, undermine, and circumvent encryption has never been stronger. Cybercriminals are working to find ways to get around the issues that strong encryption presents due to the volume of valuable information that is sent between computers today.

While this rarely results in direct assaults against cryptographic algorithms or protocols, it frequently prompts attackers to devise novel methods of intercepting or capturing information. With these threats ever present, it is more crucial than ever to focus on maintaining strong and up-to-date implementations of effective encryption protocols.

Some applications are still running TLS versions older than 1.2, and others are still running the original SSL protocol. If yours is one of them, you should consider upgrading it immediately. Auth0 [supports both TLS 1.2 and TLS 1.3](https://auth0.com/docs/customize/custom-domains/self-managed-certificates/tls-ssl) and can help you keep your applications secure.

The TLS Handshake Explained

Uploaded from NSCAM A Primer on Cryptography - AIDA

Aïda is particularly interested in privacy-preserving cryptographic schemes and has introduced some of them at various cryptography conferences. Aïda is part of the Core Services Crypto team at Auth0, a team that is working to secure sensitive data by using cryptographic best practices, making it simple so that developers can invest their time elsewhere.

Software Engineer, IAM Crypto

Aïda Diop

Learn why you need a secure, personalized, and modern cryptographic system

A Primer on Cryptography

joey devilla headshot 900px

I’m a Senior Developer Advocate at Auth0, and I like to work on various technologies. I’ve developed software for all sorts of platforms, from CD-ROM and the PalmPilot to my current area of focus, mobile phones, IoT devices, and AI. When I’m not looking for strange new platforms to write software for, I’m playing a strange old instrument — the accordion!

Joey deVilla

Here’s an easy-to-understand analogy to help your non-technical friends and customers understand public keys and private keys, and how they relate to cryptography and digital signatures.

**If you work in cybersecurity or any computer-related field, sooner or later, you’ll have to explain public-key cryptography and digital signatures to non-technical people.** With the recent rise of remote work and stories about system breaches, computer security has become a topic of discussion even among laypeople.

After trying to explain public-key cryptography and digital signatures to some clients with varying degrees of success, I wanted to develop an analogy that explained them and was easy to remember. I’ve found that even techies get confused by the formal definitions, and many non-technical explanations just seem unsatisfying.

That’s when I stumbled upon [Panayotis Vryonis’](https://twitter.com/vrypan) article, [*Public-key cryptography for non-geeks*](https://blog.vrypan.net/2013/08/28/public-key-cryptography-for-non-geeks/). It became my go-to analogy until my computer science professor, [Dr. Robin Dawes](http://research.cs.queensu.ca/home/dawes/) pointed out a flaw. I refined it with his help, and a suggestion from Matthew Ernest, and the result is below. I hope you find it helpful when trying to explain these concepts to anyone!


## The Box

Imagine a box with a special lock, as pictured below:

![Photo of a box with a lock. There is a key inserted into the lock. Caption: "The box has a lock with three positions: Locked (at the 9:00 position), unlocked (at the 12:00 position), and locked (at the 3:00 position)."](https://images.ctfassets.net/23aumh6u8s0i/4nm7EvXpqVqMxfOPkjUlXe/bca6b7d8d0a00658045dd4f3fd0a5c7f/the_box_has_a_lock_with_three_positions.png)

The lock has three positions:

1. When the lock is at the “9:00” position, the box is locked, and its contents are inaccessible.
2. When the lock is at the “12:00” position, the box is unlocked, which means you can open it and view its contents.
3. When the lock is at the “3:00” position, the box is locked, and its contents are inaccessible.

In order to avoid wandering into endless “What if...?” tangents, assume that it’s prohibitively costly to pick the lock or break the box.


## The Keys

There are two kinds of keys that work with the box’s lock.

### The private key

The first kind of key belongs to you, and only you. You don’t share it with anyone else, which is why it’s called the **private key**. You might make a backup copy in case of emergencies, but you keep it in a safe place that only you know.

![Photo of a single key. Caption: "You keep the private key to yourself."](https://images.ctfassets.net/23aumh6u8s0i/2PJXCaqzggdgTpN4FSm8Qj/4a1228e2e8a6a46ad103c01ffd197e58/you_keep_the_private_key_to_yourself.png)

The private key fits the lock, but it has a particular limitation: it can only turn *clockwise*.

![Photo of the box with lock and key. An arrow indicates that the key is being turned clockwise. Caption: "The private key only turns clockwise."](https://images.ctfassets.net/23aumh6u8s0i/qqPVi6JTc2HOW4SuE4sEj/8fcd841021e55b659a3c5b92ad9b2da2/the_private_key_only_turns_clockwise.png)

### The public key

You treat the second kind of key very differently. Unlike the first key, you’ve made many, many copies of these keys. You’ve given them to everyone you know, and even people you don’t know. You’ve left them in as many public places as you could reach: restaurants, stores, busy streets, dark alleys, and any place you happened to pass through. You’ve even left them in other towns, and even other countries! Because of the way you treat this key, it’s called the **public key**.

![Photo of hundreds of keys hanging on hooks on a wall. Caption: "You hand out copies of the public key freely."](https://images.ctfassets.net/23aumh6u8s0i/2LTNf9JxfjDuB4rMZyM7K6/4a3a6264b81bf2b90efaffe469d3406c/you_hand_out_copies_of_the_public_key_freely.png)

Like the private key, public keys also fit the lock, and they also have a particular limitation — but in the opposite direction. They can only turn *counterclockwise*.

![Photo of the box with lock and key. An arrow indicates that the key is being turned counterclockwise. Caption: "The public key only turns counterclockwise."](https://images.ctfassets.net/23aumh6u8s0i/6QVsGSSoLuNdRgpfHznh6H/b5f42c68a9d5aa9e322e898cac14aeb3/the_public_key_only_turns_counterclockwise.png)


## How They Work Together

The lock, private key, and public keys work together to produce these interesting outcomes:

* If the box is locked with a public key, only the private key can unlock it.
* If the box is locked with the private key, only a public key can unlock it.

The keys are designed so that you can’t use one key to figure out how to make the other key.

We can use the box and keys to create two useful kinds of secure communication:

1. I can send you a secret message.
2. You can send me a message with proof that you (and not some impostor) sent it and that it wasn’t altered *en route*.

Let’s take a closer look at each of these kinds of secure communication.

## Sending Secret Messages

Suppose I wanted to send you a message that I wanted only you to read. We have enemies in common who’d love nothing more than to know what’s in the messages I send you.

We each have a cadre of minions to deliver our messages. We trust them... to a limited extent. It would be all too easy for our foes to intercept our messages through force or bribery. 

There must be a way to send messages to you secretly, and that’s where the box comes in. I can use the box to send the message so that no one but you can read it. 

You have the only private key. Everyone else has at least one of the public keys because you’ve been giving them away like candy. 

I put my message in the open box. Since it’s open, it’s unlocked, which means the lock is at the “12:00” position. 

I use one of the many copies of the public key that I own to lock it, turning it counterclockwise from the unlocked “12:00” position to the locked “9:00” position.

![Photo of the box with lock and key. An arrow indicates that the key is being turned counterclockwise. Caption: "I lock the message in the box with the public key..."](https://images.ctfassets.net/23aumh6u8s0i/3WnNKlXN7MC0BfDdEU8GyX/2bcc1521f829c80ff548cf7234078bba/i_lock_the_message_with_public_key.png)

The message is now ready for a minion to deliver to you.

I’m not worried that my minion or anyone other than you will be able to read the message while it’s in transit. Even though anyone can easily find the public key, they can’t use it to unlock the box. Only the private key can unlock the box if it’s been locked with the public key.

When you receive the box, you use the private key to unlock it, turning the key clockwise from the “3:00” position to the “12:00” position.

![Photo of the box with lock and key. An arrow indicates that the key is being turned clockwise. Caption: "...and you unlock it with the private key."](https://images.ctfassets.net/23aumh6u8s0i/2kwG5ogtYDYCkDtjC0MqgN/75f2cb365ea0014a0af58a7dbc90c481/you_unlock_it_with_the_private_key.png)

In summary: to send you a secret message, I use a public key to lock the message so nobody can read it, and you use a private key to unlock the message so that you can read it.

This is the general idea behind public-key encryption: **encrypt with the public key, decrypt with the private key.**

## Signing Messages

The “secret messages” use case for the box and private and public keys is intuitive: anyone with a public key can lock a message, but only the holder of the private key can unlock it.

There’s another way to use the box and keys: you can lock a message with the private key, which anyone with the public key can unlock. What could a possible use case there be for a system where anyone can unlock the box?

Suppose one of our common enemies has been trying to break up our alliance and that I’ve been receiving very hurtful messages that appear to have come from you. (I’ll leave the content of those messages to your imagination.)

That enemy has either been sending fake messages or has been intercepting and altering your real ones. There has to be a way to package a message in order to prove that it’s actually from you!

There *is* a way: the box!

In this scenario, you put your message in the open box. Since it’s open, it’s unlocked, which means the lock is at the “12:00” position. 

Using the private key, you “sign” the message by locking it, turning the key counterclockwise from the “12:00” position to the “9:00” position.

![Photo of the box with lock and key. An arrow indicates that the key is being turned clockwise. Caption: "You 'sign' the message with the private key..."](https://images.ctfassets.net/23aumh6u8s0i/1U2aOr7mKgMtGdZM8lPLWT/82ff89d7160d93b04fff8ac635fd41d7/you_sign_the_message_with_the_private_key.png)

One of your minions delivers the box to me.

Since you locked the box with the private key, anyone can unlock it with any one of the many public keys you have distributed. Our common enemy, knowing that this message is in transit, could intercept it and replace your invitation to tea with a “top ten” list of very cutting insults that would surely dissolve our alliance.

The problem with the enemy’s plan is that it won’t work. Intercepting and altering the message means that they would have to do one of two things before forwarding the box to me.

1. They could leave the box unlocked. Since the box is supposed to arrive locked, this is an obvious sign that the message may have been tampered with.
2. They could lock the box. They would have to do it with a public key, which means that only the private key can unlock it. I wouldn’t be able to unlock the box with the only key I had — the public key — which would lead me to conclude that someone had unlocked the box before I did.

If the box arrives at my doorstep and...

* It’s locked
* I can unlock it with the public key

...then, I can be assured that the message came from you and wasn’t changed *en route*.

![Photo of the box with lock and key. An arrow indicates that the key is being turned counterclockwise. Caption: "...and I verify your 'signature' with the public key."](https://images.ctfassets.net/23aumh6u8s0i/4Fax8BanX5Qts7KJzW7166/b4dc34b169f6eca961c8d8f3c7452af4/i_verify_your_signature_with_the_public_key.png)

In summary: to send me a message with proof that you are the sender, you use the private key to lock the message. You’re the only person with the private key, and only a public key can unlock messages locked with the private key. If one of the public keys can unlock that message, I know that it came from you.

This is the general idea behind digital signatures: **sign with the private key, verify with a public key.**

## How About Sending a Message That’s Both Secret *and* Signed?

You might think that sending a message that is both secret and signed is paranoid. I would answer by saying, “Paranoia is the ***mistaken*** impression that people are out to get you.”

Suppose I wanted to send you a secret signed message. I could do it with two boxes:

1. A smaller box, which I own. It will prove that I sent the message. I have the private key for this box, and you have one of its public keys.
2. A larger box, which you own. It will keep the message secret. You have the private key for this box, and I have one of its public keys.

I would lock the message in my smaller box using my private key and then lock it in your larger box using your public key.

When you receive the delivery, you will unlock your larger box first, using your private key. This would reveal my smaller box inside, which you would unlock with my public key.


## It’s Not Keys and Boxes, but Numbers and Algorithms

Of course, we’re not really dealing with boxes, keys (at least the kind that goes into locks), or minions. Here’s a list of elements in these stories and their real-world equivalents:

* **The message**: Anything that you’d want to send that can you can view or edit with a computer. It could be text, one or more pictures, an audio or video recording, a database, or even an application. As far as the computer is concerned, messages are just a long series of numbers.
* **The private and public keys**: Very large numbers that are used in a lengthy math process to encrypt, decrypt, sign, and verify messages.
* **The box**: An algorithm that takes the message and keys and performs the math process to encrypt, decrypt, sign, and verify messages.
* **Minions**: The way in which the message is sent. This could be the internet but could just as easily be an actual minion, such as an unsuspecting summer intern with a USB key.

In the alternate universe where messages are sent with boxes and keys, everyone would have their own set of boxes with their own private keys, as well as copies of other people’s public keys. In the real world, we run applications that run public-key encryption and digital signature algorithms to secure our messages. We still use public and private keys in the real world; they’re just digital.

How to Explain Public-Key Cryptography and Digital Signatures to Anyone

hunter-jensen

Hunter Jensen is CTO of Permission.io. Having launched his first website in 1998 and his first iOS app in 2008, Hunter has been at the forefront of the software design and development industry for over 20 years. He is a distinguished speaker, author, entrepreneur, and thought leader in the digital world, well-known for leading teams to release best-in-class web & mobile products, including for Samsung, Cisco, Salesforce, Avalara, and many more. Hunter joined Permission as CTO in early 2020 and helped guide the company to a successful launch of multiple digital products.

CTO of Permission.io

Hunter Jensen

Permission.io’s CTO Hunter Jensen on crypto regulation, advice for the crypto-curious, and blockchain

_EDITOR’S NOTE: Crypto (digital currency) is becoming more mainstream with crypto exchange [Coinbase’s IPO splash](https://www.ibtimes.com/whats-next-coinbase-coin-after-blockbuster-ipo-fintech-analysts-weigh-3184496) and the [creation of the cyber yuan](https://www.wsj.com/articles/china-creates-its-own-digital-currency-a-first-for-major-economy-11617634118). Permission.io’s business model uses Auth0 to protect its platform while delivering digital currency in exchange for permission-based advertising. We invited their CTO, Hunter Jensen, to pen a post to share his thoughts on crypto’s future._

Today crypto is highly volatile — investing can be a real roller coaster. But that’s changing. We just saw the first public valuation of a cryptocurrency company, with [Coinbase coming in at $86 billion](https://www.nytimes.com/live/2021/04/14/business/stock-market-today). [Governments are creating digital currency](https://www.barrons.com/articles/central-banks-are-trying-to-muscle-aside-bitcoin-what-investors-need-to-know-51618866586) or at least talking about it. Here’s why I think everyone will eventually be carrying a crypto wallet.

## What Is Cryptocurrency Anyway?

Cryptocurrency is a digital currency issued by blockchain software and regulated by a decentralized set of systems, software, and rules.

Blockchain is really just a decentralized accounting ledger that records transaction after transaction. What makes it interesting is that it's decentralized — in most cases, there's no central authority running it. Blockchain also uses really complex and complicated cryptography and algorithmic mechanisms to be able to verify each one of these transactions. If you believe in the technology, you don't need a bank to be an intermediary to know that the transaction is taking place.

It helps to contrast cryptocurrency with fiat currency, which is issued by a government decree (or fiat) and regulated by a central authority.

Fiat is stable and controlled, which means it works well as a store of value and a unit of account. You can transfer it from one place to another and have it be the same value in both places. If a country prints a lot of money, it risks hyperinflation and depression, but that takes a certain amount of time to happen. Money, as we know it, has been around for thousands of years.

It’s also expensive and time-consuming to do big complicated transactions with fiat currency. If you’ve ever tried to buy a house or send money from the U.S. to a country in Eastern Europe, for example, it can get very tricky and take a long time.

### Crypto pros and cons

Crypto is not without its pros and cons. It's much faster and cheaper and is often anonymous. You don't have to go through a trusted third-party to conduct a transaction. The benefit is that the transactions are generally faster, cheaper, and easier. But the ability to conduct peer-to-peer transactions sometimes relies on that anonymity for illicit purposes. 

Crypto is also extremely volatile. As such, it is not yet stable enough to be a unit of account. It can hold value, but the value will fluctuate dramatically. In the course of the 30 minutes I’ve been working on this post, my crypto portfolio might be down 10%, but it will come back up in another couple of hours. The main difference between crypto and Fiat currency is how it's regulated and how one transacts with it.

Like Fiat currency, cryptos can be listed on an exchange like Coinbase and be bought and sold and exchanged in a similar way to how stocks are bought and sold on the stock exchange. Currently, there are some 4,800 cryptos on CoinMarketCap, and my prediction is that number will keep going up for a while. But you can also issue crypto without listing it on an exchange. Technically it is still a token, but you can’t sell it. This means that it doesn’t have transferable value, only intrinsic value. If you’re getting into crypto, you need to be aware of what you’re really getting. More on that later.

## We Welcome Government Regulation — Really

The first thing that might surprise you about Permission.io and like-minded crypto-based companies is that we welcome government regulation. Right now, it’s the Wild Wild West out here. There’s just not a lot of predictability, which is tough on businesses.

We are seeing major companies like JP Morgan, Visa, PayPal, Tesla, and others with Bitcoin and other cryptos on their balance sheets. But it’s also not clear how a company like [Tesla is going to report Bitcoin on their taxes due to the lack of regulation](https://fortune.com/2021/04/27/tesla-tsla-bitcoin-btc-bet-how-much-has-it-made-elon-musk-profits/#:~:text=Result%3A%20Tesla%20still%20holds%20around%2038%2C300%20Bitcoin%20that%20cost%20%241.329%20billion). (Tesla no longer accepts Bitcoin for purchases, [other car dealers are still accepting the cryptocurrency](https://www.caranddriver.com/news/a36434628/tesla-bitcoin-wont-accept/). In the U.S., in particular, there’s a real patchwork of regulations that can make it hard for companies to comply or even conduct an ordinary business.

But that challenge isn’t making digital currency go away. As I said, the numbers are growing, and governments themselves are getting interested in digital currency. 

The global crypto market’s been estimated at $1.99 trillion according to my latest check of [CoinMarketCap](https://coinmarketcap.com/). China has already created the [cyber yuan](https://www.wsj.com/articles/china-creates-its-own-digital-currency-a-first-for-major-economy-11617634118). The U.K. has formed a task force to explore the creation of [‘Britcoin](https://www.reuters.com/business/finance/uk-launches-taskforce-potential-bank-england-digital-currency-sunak-2021-04-19/).’ In [Latin America](https://www.spglobal.com/marketintelligence/en/news-insights/latest-news-headlines/crypto-s-2020-boom-sparks-interest-from-latam-legacy-banks-61781257), legacy banks are also noting the need for regulation. In the U.S., the Biden administration put former investment banker and crypto professor [Gary Gensler](https://www.investing.com/analysis/secs-gensler-will-spur-next-leg-up-for-cryptocurrencies-market-crisis-ahead-200575268) in charge of the Securities Exchange Commission (SEC). Gensler’s strong opinions on crypto will likely drive clarity through regulation. In the United States, I’m expecting regulation later in 2021 or in 2022.

## Want to Get into Crypto? It’s Not for the Risk-Averse

Think of someone with high-net-worth. If that person has crypto in their portfolio, it’s probably their highest-risk asset unless they’re doing early-stage startup investing. With crypto, only risk something you’re ready to lose. This is not the place to risk your retirement savings. Crypto is extremely unpredictable and volatile. 

But if you’re still crypto-curious, here are some critical pointers:

* **Make sure you’re trading on a well-known and reputable exchange.** There are some dangerous exchanges that might run away with your coin. Make sure you’ve[ researched the exchange](https://www.investopedia.com/best-crypto-exchanges-5071855) for reputation and reliability, and make sure that you can safely trade in your country. Sometimes you might be allowed to buy crypto but then find that you can’t trade it due to your location.
* **Watch out for phishing attacks.** [Phishing](https://auth0.com/blog/phishing-goes-viral-covid-19-themes-in-cybercrime/) relies on tricking users into giving up information that gives malicious actors access to their accounts. While anyone who uses digital systems is a target, crypto can make you a tastier target. Stay up-to-date on the most common exploits. Pausing before you click can protect your coin.
* **Crypto timing is minutes, hours, days, weeks — not years.** When you're trading stocks, you're thinking in terms of days, months, or years. Crypto trading is in minutes or hours — sometimes days or weeks. There are people who are thinking in terms of years, but since crypto hasn’t really been around that long, that’s extremely unpredictable.
* **Trading happens 24/7.** In the U.S., the stock exchange runs Monday through Friday with holidays off. Crypto is 24/7, not a day off — always on. If you’re in the U.S., for example, when you get up in the morning, people in Asia have been trading all night. This can have a big impact on your crypto wallet.
* **Only risk what you’re willing to lose.** Repeating this point because it’s important. This is a highly volatile, under-regulated space. Take care to protect yourself.

## How Secure Is Crypto Really?

Bitcoin itself is incredibly beautiful in terms of how secure it is. Every line of code is wide open, which means that some of the smartest minds in the world have spent years trying to break in and haven’t succeeded yet.

But in the news, you’ve probably seen stories about “the Bitcoin Hack.” Bitcoin didn’t actually get hacked. Companies in the Bitcoin ecosystem got hacked. The [cryptocurrency hardware wallet Ledger](https://www.forbes.com/sites/billybambrough/2020/12/23/massive-hack-exposes-bitcoins-greatest-weakness/?sh=4730b594da7d) exposed data through a vulnerability in their site that exposed their e-commerce and marketing database. So the bad actors got people’s emails, phone numbers, and the last time they visited the site, which made it easy for phishing attacks. 

When you think of everyone using the internet, much of our data is already out there. If bad actors know someone has a crypto wallet, it can make them a focused target of phishing attacks designed to convince folks to give up their private keys.

So while you have a core system — Bitcoin — that is very secure, you still need to secure all the third-party systems that hold information about that data. Securing crypto needs to be like the American banking system — you need to create a strong ecosystem and remain vigilant. It wasn’t that long ago that Americans were dealing with card skimmers when they used their debit cards at the gas station. Banks had to respond by adding chips to cards. Any industry with sensitive data is going to need to remain vigilant.

Like a bank, Permission.io needs to know the true human identity of every single user in our system. We need to be able to transport that identity from system to system and to third-party systems and know that they haven’t been broken into. 

In the traditional banking financial system, you have to go into a branch and show somebody your driver's license and very clearly prove your identity. It's a lot harder to do that in the digital space, but identity management alongside other security measures is completely critical to the infrastructure of the entire cryptocurrency system.

## The Future of Crypto and Blockchain

Three years ago, blockchain was still an experiment for a lot of industries. That’s changed. A supply chain is probably the biggest adopter of blockchain after crypto. We see [Walmart](https://www.computerworld.com/article/3454336/walmart-launches-world-s-largest-blockchain-based-freight-and-payment-network.html) and other companies turn to blockchain to solve challenges. Blockchain’s also in use in the insurance industry, fintech, energy, and medical records. Because blockchain offers an immutable record, I expect we’ll see even greater adoption as the ecosystem of third-party support around blockchain uses continues to expand.

Crypto, like blockchain, is maturing. Recently, [Elon Musk sold off 10% of Tesla’s Bitcoin](https://www.bloomberg.com/news/articles/2021-04-26/musk-tesla-sold-bitcoin-to-prove-liquidity-as-cash-alternative) investment. On Twitter, Musk said he did it “to prove liquidity of Bitcoin as an alternative to holding cash on the balance sheet.” These actions will likely speed regulation. 

Five years from now, I believe we’ll have clear regulation. 

We will see a consolidation of coins. Those that don't have big backing financially and don't have utility will go by the wayside. I believe we will see a lot of national governments issuing their own digital currencies. We’ll have seen a consolidation of coins, and the ones that remain will be a stable way to transact.

In 10 years, I think the average person will start thinking about value in terms of bitcoin. Bitcoin itself will be a unit of account in a store of value.

There are three things that a currency needs to be mature and stable. It needs to be transferable, it needs to be a unit of account, and it needs to be a stable store of value. There’s still a lot of volatility right now, but as crypto matures, I think this is where we’re headed. Crypto will become a bigger part of businesses and governments, and life for average people.

The not-so-hidden bit is that I’m just not so sure that governments are going to be in charge of money for that much longer. The decentralization of economic and financial systems is scary for them. But if governments lean into it, they can make it work. If they fight it, then I believe that it's going to be even more problematic for them for the simple reason that you can’t control a banned currency. Instead, if governments choose to regulate and tax crypto, then the entire system becomes a more stable opportunity for everyone.

For further information, read the complete case study [here](https://auth0.com/case-studies/permission/).

The Future of Crypto

dfea5c5f769cc4a6cce74d3eda20bba3?size=200 avatar

dfea5c5f769cc4a6cce74d3eda20bba3?size=200

Guest Author

Tim McLean

Which libraries are vulnerable to attacks and how to prevent them.



**TL;DR:** If you are using [node-jsonwebtoken](https://github.com/auth0/node-jsonwebtoken), [pyjwt](https://github.com/jpadilla/pyjwt/), [namshi/jose](https://github.com/namshi/jose), [php-jwt](https://github.com/firebase/php-jwt) or [jsjwt](https://github.com/kjur/jsjws) with asymmetric keys (RS256, RS384, RS512, ES256, ES384, ES512) please update to the latest version. See [jwt.io](http://jwt.io) for more information on the vulnerable libraries. *(Updated 2015-04-20)*

> This is a guest post from Tim McLean, who is a member of the [Auth0 Security Researcher Hall of Fame](https://auth0.com/whitehat#hall-of-fame). Tim normally blogs at [www.timmclean.net](https://www.timmclean.net).

Recently, while reviewing the security of various JSON Web Token implementations, I found many libraries with critical vulnerabilities allowing attackers to bypass the verification step.  The same two flaws were found across many implementations and languages, so I thought it would be helpful to write up exactly where the problems occur.  I believe that a change to the standard could help prevent future vulnerabilities.

<include src="TweetQuote" quoteText="I found many libraries with critical vulnerabilities allowing attackers to bypass the verification step."/>

For those who are unfamiliar, [JSON Web Token (JWT)](https://auth0.com/learn/json-web-tokens/) is a standard for creating tokens that assert some number of claims.  For example, a server could generate a token that has the claim "logged in as admin" and provide that to a client. The client could then use that token to prove that they are logged in as admin. The tokens are signed by the server's key, so the server is able to verify that the token is legitimate.

JWTs generally have three parts: a header, a payload, and a signature.

The header identifies which algorithm is used to generate the signature, and looks something like this:

``` javascript  
header = '{"alg":"HS256","typ":"JWT"}'
```

`HS256` indicates that this token is signed using HMAC-SHA256.

The payload contains the claims that we wish to make:

``` javascript  
payload = '{"loggedInAs":"admin","iat":1422779638}'
```

As suggested in the JWT spec, we include a timestamp called `iat`, short for "issued at".

The signature is calculated by base64url encoding the header and payload and concatenating them with a period as a separator:

``` javascript  
key = 'secretkey'
unsignedToken = encodeBase64(header) + '.' + encodeBase64(payload)
signature = HMAC-SHA256(key, unsignedToken)
```

To put it all together, we base64url encode the signature, and join together the three parts using periods:

``` javascript  
token = encodeBase64(header) + '.' + encodeBase64(payload) + '.' + encodeBase64(signature)

# token is now:
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb2dnZWRJbkFzIjoiYWRtaW4iLCJpYXQiOjE0MjI3Nzk2Mzh9.gzSraSYS8EXBxLN_oWnFSRgCzcmJmMjLiuyu5CSpyHI
```

To learn more about JSON Web Tokens, check out our free ebook below.

<include src="ebook-ads/JwtHandbook" />

## Great. So, What's Wrong with That?

Well, let's try to verify a token.

First, we need to determine what algorithm was used to generate the signature. No problem, there's an `alg` field in the header that tells us just that.

But wait, we haven't validated this token yet, which means that we haven't validated the header.  This puts us in an awkward position: in order to validate the token, we have to allow attackers to select which method we use to verify the signature.

This has disastrous implications for some implementations.

## Meet the "None" Algorithm


The `none` algorithm is a curious addition to JWT.  It is intended to be used for situations where the integrity of the token has already been verified. Interestingly enough, it is one of only two algorithms that are mandatory to implement (the other being `HS256`).

Unfortunately, some libraries treated tokens signed with the `none` algorithm as a valid token with a verified signature.  The result?  Anyone can create their own "signed" tokens with whatever payload they want, allowing arbitrary account access on some systems.

Putting together such a token is easy. Modify the above example header to contain `"alg": "none"` instead of `HS256`.  Make any desired changes to the payload.  Use an empty signature (i.e. `signature = ""`).

Most (hopefully all?) implementations now have a basic check to prevent this attack: if a secret key was provided, then token verification will fail for tokens using the `none` algorithm.  This is a good idea, but it doesn't solve the underlying problem: attackers control the choice of algorithm.  Let's keep digging.

## RSA or HMAC?

The JWT spec also defines a number of asymmetric signing algorithms (based on RSA and ECDSA).  With these algorithms, tokens are created and signed using a private key but verified using a corresponding public key.  This is pretty neat: if you publish the public key but keep the private key to yourself, only you can sign tokens, but anyone can check if a given token is correctly signed.

Most of the JWT libraries that I've looked at have an API like this:

``` javascript  
# sometimes called "decode"
verify(string token, string verificationKey)
# returns payload if valid token, else throws an error
```

In systems using HMAC signatures, `verificationKey` will be the server's secret signing key (since HMAC uses the same key for signing and verifying):

``` javascript  
verify(clientToken, serverHMACSecretKey)
```

In systems using an asymmetric algorithm, `verificationKey` will be the public key against which the token should be verified:

``` javascript  
verify(clientToken, serverRSAPublicKey)
```

Unfortunately, an attacker can abuse this.  If a server is expecting a token signed with RSA, but actually receives a token signed with HMAC, **it will think the public key is actually an HMAC secret key**.

How is this a disaster?  HMAC secret keys are supposed to be kept private, while public keys are, well, public.  This means that your typical [ski mask-wearing attacker](https://i.imgur.com/18fM5ja.jpg) has access to the public key, and can use this to forge a token that the server will accept.

Doing so is pretty straightforward.  First, grab your favorite JWT library, and choose a payload for your token.  Then, get the public key used on the server as a verification key (most likely in the text-based PEM format). Finally, sign your token using the PEM-formatted public key as an HMAC key. Essentially:

``` javascript  
forgedToken = sign(tokenPayload, 'HS256', serverRSAPublicKey)
```

The trickiest part is making sure that `serverRSAPublicKey` is identical to the verification key used on the server.  The strings must match exactly for the attack to work -- exact same format, and no extra or missing line breaks.

End result?  Anyone with knowledge of the public key can forge tokens that will pass verification.

## Recommendations for Library Developers

I suggest that JWT libraries add an `algorithm` parameter to their verification function:

``` javascript  
verify(string token, string algorithm, string verificationKey)
```

The server should already know what algorithm it uses to sign tokens, and it's not safe to allow attackers to provide this value.

Some might argue that some servers need to support more than one algorithm for compatibility reasons.  In this case, a separate key can (and should) be used for each supported algorithm.  JWT conveniently provides a "key ID" field (`kid`) for exactly this purpose.  Since servers can use the key ID to look up the key and its corresponding algorithm, attackers are no longer able to
control the manner in which a key is used for verification.  In any case, I don't think JWT libraries should even look at the `alg` field in the header, except maybe to check that it matches what the expected algorithm was.

Anyone using a JWT implementation should make sure that tokens with a different signature type are guaranteed to be rejected.  Some libraries have an optional mechanism for whitelisting or blacklisting algorithms; take advantage of it, or you might end up at risk.  Even better: have a policy of performing security audits on any open source libraries that you use to provide mission-critical functionality.

## Improving the JWT/JWS Standard

I would like to propose deprecating the header's `alg` field.  As we've seen here, its misuse can have a devastating impact on the security of a JWT/JWS implementation.  As far as I can tell, key IDs provide an adequate alternative. This warrants a change to the spec: JWT libraries continue to be written with security flaws due to their dependence on `alg`.

JWT (and JOSE) present the opportunity to have a cross-platform suite of secure cryptography implementations.  With these fixes, hopefully, we're a little bit closer to making that a reality.

<include src="asides/Jwt" />


Critical vulnerabilities in JSON Web Token libraries

eva-sarafianou

Eva is a Product Security Engineer with a special interest in Cryptography that loves building, securing, and breaking software. At Auth0, Eva works on making our identity platform secure and trusted. She spends her spare time playing the piano, taking dance lessons, and doing outdoors activities.

Product Security Engineer

Eva Sarafianou

marius-mogyorosi

As an Application Security Engineer at Auth0, Marius champions security throughout the software development process with practices ranging from threat modeling to operational application security. Off-hours, he enjoys barbecuing and learning about most things.

Application Security Engineer

Marius Mogyorosi

Cryptography has three key properties: confidentiality, integrity, and authenticity. Let’s learn which of these apply to encryption, hashing, encoding, and obfuscation.

"crypto"