diff --git a/README.md b/README.md index 07173f33..c4f2095c 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,9 @@ This module is available as [@scion/toolkit][link-toolkit-download] in the NPM r - [**BeanManager**][link-tool-bean-manager]\ Provides a registry for looking up singleton objects. +- [**Crypto**][link-tool-crypto]\ + Provides cryptographic functions. + - [**Observable**][link-tool-observable]\ Provides RxJS Observables for observing the size or DOM mutations of an HTML element. @@ -81,6 +84,7 @@ This module is available as [@scion/components][link-components-download] in the [link-tool-uuid]: /docs/site/tools/uuid.md [link-tool-web-storage]: /docs/site/tools/web-storage.md [link-tool-bean-manager]: /docs/site/tools/bean-manager.md +[link-tool-crypto]: /docs/site/tools/crypto.md [link-scion-microfrontend-platform]: https://github.com/SchweizerischeBundesbahnen/scion-microfrontend-platform/blob/master/README.md [link-scion-workbench]: https://github.com/SchweizerischeBundesbahnen/scion-workbench/blob/master/README.md diff --git a/docs/site/tools/crypto.md b/docs/site/tools/crypto.md new file mode 100644 index 00000000..0300c30c --- /dev/null +++ b/docs/site/tools/crypto.md @@ -0,0 +1,37 @@ +SCION Toolkit + +| SCION Toolkit | [Projects Overview][menu-projects-overview] | [Changelog][menu-changelog] | [Contributing][menu-contributing] | [Sponsoring][menu-sponsoring] | +| --- | --- | --- | --- | --- | + +## [SCION Toolkit][menu-home] > Crypto + +The NPM sub-module `@scion/toolkit/crypto` provides cryptographic functions. + +To use the crypto module, install the NPM module `@scion/toolkit` as following: + +``` +npm install @scion/toolkit --save +``` + +
+ Crypto.digest + +Generates a digest of the given data using the specified algorithm (or SHA-256 by default) and converts it to a hex string. + +```typescript +import { Crypto } from '@scion/toolkit/crypto'; + +const hash: string = await Crypto.digest('some-data'); +``` +
+ + +[menu-home]: /README.md + +[menu-projects-overview]: /docs/site/projects-overview.md + +[menu-changelog]: /docs/site/changelog.md + +[menu-contributing]: /CONTRIBUTING.md + +[menu-sponsoring]: /docs/site/sponsoring.md diff --git a/projects/scion/toolkit/README.md b/projects/scion/toolkit/README.md index d36a37d9..bb0f9a9c 100644 --- a/projects/scion/toolkit/README.md +++ b/projects/scion/toolkit/README.md @@ -22,6 +22,9 @@ This library is written in plain TypeScript and has no dependency on any other l - [**BeanManager**][link-tool-bean-manager]\ Provides a registry for looking up singleton objects. +- [**Crypto**][link-tool-crypto]\ + Provides cryptographic functions. + - [**WebStorage**][link-tool-web-storage]\ Allows observing items contained in local or session storage. @@ -41,3 +44,4 @@ License: EPL-2.0 [link-tool-uuid]: https://github.com/SchweizerischeBundesbahnen/scion-toolkit/blob/master/docs/site/tools/uuid.md [link-tool-web-storage]: https://github.com/SchweizerischeBundesbahnen/scion-toolkit/blob/master/docs/site/tools/web-storage.md [link-tool-bean-manager]: https://github.com/SchweizerischeBundesbahnen/scion-toolkit/blob/master/docs/site/tools/bean-manager.md +[link-tool-crypto]: https://github.com/SchweizerischeBundesbahnen/scion-toolkit/blob/master/docs/site/tools/crypto.md diff --git a/projects/scion/toolkit/crypto/ng-package.json b/projects/scion/toolkit/crypto/ng-package.json new file mode 100644 index 00000000..0967ef42 --- /dev/null +++ b/projects/scion/toolkit/crypto/ng-package.json @@ -0,0 +1 @@ +{} diff --git a/projects/scion/toolkit/crypto/src/crypto.util.spec.ts b/projects/scion/toolkit/crypto/src/crypto.util.spec.ts new file mode 100644 index 00000000..d5c47980 --- /dev/null +++ b/projects/scion/toolkit/crypto/src/crypto.util.spec.ts @@ -0,0 +1,19 @@ +/* + * Copyright (c) 2018-2022 Swiss Federal Railways + * + * This program and the accompanying materials are made + * available under the terms of the Eclipse Public License 2.0 + * which is available at https://www.eclipse.org/legal/epl-2.0/ + * + * SPDX-License-Identifier: EPL-2.0 + */ + +import {Crypto} from './crypto.util'; + +describe('Crypto', () => { + + it('should hash data', async () => { + const hash = await Crypto.digest('A'); + expect(hash).toEqual('559aead08264d5795d3909718cdd05abd49572e84fe55590eef31a88a08fdffd'); + }); +}); diff --git a/projects/scion/toolkit/crypto/src/crypto.util.ts b/projects/scion/toolkit/crypto/src/crypto.util.ts new file mode 100644 index 00000000..ea91af7f --- /dev/null +++ b/projects/scion/toolkit/crypto/src/crypto.util.ts @@ -0,0 +1,35 @@ +/* + * Copyright (c) 2018-2022 Swiss Federal Railways + * + * This program and the accompanying materials are made + * available under the terms of the Eclipse Public License 2.0 + * which is available at https://www.eclipse.org/legal/epl-2.0/ + * + * SPDX-License-Identifier: EPL-2.0 + */ + +/** + * Provides cryptographic functions. + */ +export namespace Crypto { + + /** + * Generates a digest of the given data using the specified algorithm (or SHA-256 by default) and converts it to a hex string. + * + * Can only be used in secure contexts (HTTPS) or on localhost. For more information, refer to https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts. + * + * Credits: https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest + */ + export async function digest(data: string | BufferSource, options?: {algorithm?: 'SHA-256' | 'SHA-384' | 'SHA-512'}): Promise { + if (!isSecureContext) { + throw Error('Function "digest" of @scion/toolkit/crypto is available only in secure contexts (HTTPS) or on localhost. For more information, refer to https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts.'); + } + data = typeof data === 'string' ? new TextEncoder().encode(data) : data; + // Hash the data. + const hashBuffer = await crypto.subtle.digest(options?.algorithm ?? 'SHA-256', data); + // Convert buffer to byte array. + const hashArray = Array.from(new Uint8Array(hashBuffer)); + // Convert bytes to hex string. + return hashArray.map(b => b.toString(16).padStart(2, '0')).join(''); + } +} diff --git a/projects/scion/toolkit/crypto/src/public_api.ts b/projects/scion/toolkit/crypto/src/public_api.ts new file mode 100644 index 00000000..54f948c0 --- /dev/null +++ b/projects/scion/toolkit/crypto/src/public_api.ts @@ -0,0 +1,17 @@ +/* + * Copyright (c) 2018-2022 Swiss Federal Railways + * + * This program and the accompanying materials are made + * available under the terms of the Eclipse Public License 2.0 + * which is available at https://www.eclipse.org/legal/epl-2.0/ + * + * SPDX-License-Identifier: EPL-2.0 + */ + +/* + * Secondary entrypoint: '@scion/toolkit/crypto' + * This module does not depend on Angular. + * + * @see https://github.com/ng-packagr/ng-packagr/blob/master/docs/secondary-entrypoints.md + */ +export {Crypto} from './crypto.util'; diff --git a/tsconfig.json b/tsconfig.json index 918d3b18..f9189120 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -61,6 +61,9 @@ // "@scion/toolkit/bean-manager": [ // "projects/scion/toolkit/bean-manager/src/public_api" // ], + // "@scion/toolkit/crypto": [ + // "projects/scion/toolkit/crypto/src/public_api" + // ], // "@scion/toolkit/observable": [ // "projects/scion/toolkit/observable/src/public_api" // ],