Skip to content

Latest commit

 

History

History
118 lines (87 loc) · 4.01 KB

README.md

File metadata and controls

118 lines (87 loc) · 4.01 KB
Raw

SSH Sig

CI

Provides an SSH signature parser and verifier for SSH file signatures.

SSH signatures allow signing arbitrary files and can be used for signing git commits and tags.

All features are implemented using pure TypeScript and the built-in SubtleCrypto.

Since ed25519 public keys are not yet widely deployed, this package allows supplying custom SubtleCrypto implementation, such as webcrypto-ed25519.

Creating SSH signatures

SSH signatures can be created using OpenSSH's ssh-keygen:

ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n file file_to_sign

This will create a detached signature in the file_to_sign.sig file.

Supported algorithms

The following algorithms are supported at this time:

  • RSA
  • ed255191
  • NIST P-256, P-384 and P-5212
  • SSH U2F signatures (ECDSA and ed255191)

This represents almost all available algorithms with the exception of DSA, which is unsupported by WebCrypto and obsolete.

If you encounter a problem verifying signatures with combinations of digests that we do not have in our testing suite, please file an issue attaching both the SSH signature and the file that was signed.

Examples

The following example verifies an ed25519 signature against provided data:

import { assertEquals } from "https://deno.land/std@0.217.0/assert/mod.ts";
import { verify } from "./index.ts";

const signature = `-----BEGIN SSH SIGNATURE-----
U1NIU0lHAAAAAQAAADMAAAALc3NoLWVkMjU1MTkAAAAgscJcEliU8+Su3ZZjI/dJmgzHje
UMEHlAAuMTvrYRCVwAAAAEZmlsZQAAAAAAAAAGc2hhNTEyAAAAUwAAAAtzc2gtZWQyNTUx
OQAAAECQkGDrATymoR1tunbphepkXiLGAMcF+Eca1EL3KpidzNYSTJ/smLYVw2elXq3K/l
dnvxJddvs2Z/x5En43hQIB
-----END SSH SIGNATURE-----`;

const valid = await verify(
  signature, // detached signature
  "this is signed data\n", // signed data
  {
    subtle: crypto.subtle, // bring your own SubtleCrypto
  },
);

assertEquals(valid, true, "signature is valid");

Signatures can also be parsed before verification. As signatures contain public keys it is also possible to export the public key in the SSH format:

import { assertEquals } from "https://deno.land/std@0.217.0/assert/mod.ts";
import { verify } from "./index.ts";
import { parse } from "./sig_parser.ts";

const signature = parse(`-----BEGIN SSH SIGNATURE-----
U1NIU0lHAAAAAQAAADMAAAALc3NoLWVkMjU1MTkAAAAgscJcEliU8+Su3ZZjI/dJmgzHje
UMEHlAAuMTvrYRCVwAAAAEZmlsZQAAAAAAAAAGc2hhNTEyAAAAUwAAAAtzc2gtZWQyNTUx
OQAAAECQkGDrATymoR1tunbphepkXiLGAMcF+Eca1EL3KpidzNYSTJ/smLYVw2elXq3K/l
dnvxJddvs2Z/x5En43hQIB
-----END SSH SIGNATURE-----`);

const valid = await verify(
  signature, // detached signature
  "this is signed data\n", // signed data
  // using "crypto.subtle" by default
);

assertEquals(valid, true, "signature is valid");
assertEquals(
  `${signature.publickey}`,
  "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILHCXBJYlPPkrt2WYyP3SZoMx43lDBB5QALjE762EQlc",
  "signing key",
);

License

This project is licensed under the Apache License, Version 2.0.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.

Footnotes

  1. Requires support for Ed25519 algorithms (experimental in browsers, working in Deno) ↩ ↩2

  2. Requires support for P-521 (not available in Deno, so not tested) ↩