Skip to content

Commit 006936c

Browse files
pbelevichfacebook-github-bot
pbelevich
authored and
facebook-github-bot
committed
Update README.md for 0.2.0 (#116)
Summary: Pull Request resolved: #116 Test Plan: Imported from OSS Reviewed By: seemethere Differential Revision: D26799392 Pulled By: pbelevich fbshipit-source-id: 05332e1596b700870f0ad48bca5fa857c3c2929a
1 parent 4c02fed commit 006936c

File tree

3 files changed

+585
-25
lines changed

3 files changed

+585
-25
lines changed

‎README.md

Lines changed: 52 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
# PyTorch/CSPRNG
22

3-
torchcsprng is a [PyTorch C++/CUDA extension](https://pytorch.org/tutorials/advanced/cpp_extension.html) that provides [cryptographically secure pseudorandom number generators](https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator) for PyTorch.
4-
53
[![CircleCI](https://circleci.com/gh/pytorch/csprng.svg?style=shield&circle-token=64701692dd7f13f31019612289f0200fdb661dc2)](https://circleci.com/gh/pytorch/csprng)
64

5+
torchcsprng is a [PyTorch C++/CUDA extension](https://pytorch.org/tutorials/advanced/cpp_extension.html) that provides:
6+
7+
- [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) 128-bit encryption/decryption in two modes: [ECB](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Electronic_codebook_(ECB)) and [CTR](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_(CTR)) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/pytorch/csprng/blob/master/examples/encrypt_decrypt.ipynb)
8+
- [cryptographically secure pseudorandom number generators](https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator) for PyTorch. [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/pytorch/csprng/blob/master/examples/csprng.ipynb)
9+
710
## Design
811

912
torchcsprng generates a random 128-bit key on CPU using one of its generators and runs
@@ -22,6 +25,24 @@ Advantages:
2225

2326
## Features
2427

28+
torchcsprng 0.2.0 exposes new API for tensor encryption/decryption. Tensor encryption/decryption API is dtype agnostic, so a tensor of any dtype can be encrypted and the result can be stored to a tensor of any dtype. An encryption key also can be a tensor of any dtype. Currently torchcsprng supports [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) cipher with 128-bit key in two modes: [ECB](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Electronic_codebook_(ECB)) and [CTR](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_(CTR)).
29+
30+
* `torchcsprng.encrypt(input: Tensor, output: Tensor, key: Tensor, cipher: string, mode: string)`
31+
32+
> - `input` tensor can be any CPU or CUDA tensor of any dtype and size in bytes(zero-padding is used to make its size in bytes divisible by block size in bytes)
33+
> - `output` tensor can have any dtype and the same device as `input` tensor and the size in bytes rounded up to the block size in bytes(16 bytes for AES 128)
34+
> - `key` tensor can have any dtype and the same device as `input` tensor and size in bytes equal to 16 for AES 128
35+
> - `cipher` currently can be only one supported value `"aes128"`
36+
> - `mode` currently can be either [`"ecb"`](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Electronic_codebook_(ECB)) or [`"ctr"`](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_(CTR))
37+
38+
* `torchcsprng.decrypt(input: Tensor, output: Tensor, key: Tensor, cipher: string, mode: string)`
39+
40+
> - `input` tensor can be any CPU or CUDA tensor of any dtype with size in bytes divisible by the block size in bytes(16 bytes for AES 128)
41+
> - `output` tensor can have any dtype but the same device as `input` tensor and the same size in bytes as `input` tensor
42+
> - `key` tensor can have any dtype and the same device as `input` tensor and size in bytes equal to 16 for AES 128
43+
> - `cipher` currently can be only one supported value `"aes128"`
44+
> - `mode` currently can be either [`"ecb"`](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Electronic_codebook_(ECB)) or [`"ctr"`](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_(CTR))
45+
2546
torchcsprng exposes two methods to create crypto-secure and non-crypto-secure PRNGs:
2647

2748
| Method to create PRNG | Is crypto-secure? | Has seed? | Underlying implementation |
@@ -48,52 +69,58 @@ The following list of methods supports all forementioned PRNGs:
4869

4970
## Installation
5071

51-
CSPRNG works with Python 3.6/3.7/3.8 on the following operating systems and can be used with PyTorch tensors on the following devices:
72+
CSPRNG works with Python 3.6-3.9 on the following operating systems and can be used with PyTorch tensors on the following devices:
5273

5374
| Tensor Device Type | Linux | macOS | MS Window |
5475
|--------------------|-----------|---------------|----------------|
5576
| CPU | Supported | Supported | Supported |
56-
| CUDA | Supported | Not Supported | Coming |
77+
| CUDA | Supported | Not Supported | Supported since 0.2.0 |
78+
79+
The following is the corresponding CSPRNG versions and supported Python versions.
80+
81+
| PyTorch | CSPRNG | Python | CUDA |
82+
|---------|--------|----------|------------------|
83+
| 1.8.0 | 0.2.0 | 3.7-3.9 | 10.1, 10.2, 11.1 |
84+
| 1.7.1 | 0.1.4 | 3.6-3.8 | 9.2, 10.1, 10.2 |
85+
| 1.7.0 | 0.1.3 | 3.6-3.8 | 9.2, 10.1, 10.2 |
86+
| 1.6.0 | 0.1.2 | 3.6-3.8 | 9.2, 10.1, 10.2 |
87+
5788

5889
### Binary Installation
5990

6091
Anaconda:
6192

62-
| OS | CUDA | |
63-
|---------|-----------------------------------------------|----------------------------------------------|
64-
| Linux | 9.2<br/><br/>10.1<br/><br/>10.2<br/><br/>None | conda install torchcsprng cudatoolkit=9.2 -c pytorch<br/><br/>conda install torchcsprng cudatoolkit=10.1 -c pytorch<br/><br/>conda install torchcsprng cudatoolkit=10.2 -c pytorch<br/><br/>conda install torchcsprng cpuonly -c pytorch |
65-
| macOS | None | conda install torchcsprng cpuonly -c pytorch |
66-
| Windows | None | conda install torchcsprng cpuonly -c pytorch |
93+
| OS | CUDA | |
94+
|---------------|------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
95+
| Linux/Windows | 10.1<br/><br/>10.2<br/><br/>11.1<br/><br/>None | conda install torchcsprng cudatoolkit=10.1 -c pytorch -c conda-forge<br/><br/>conda install torchcsprng cudatoolkit=10.2 -c pytorch -c conda-forge<br/><br/>conda install torchcsprng cudatoolkit=11.1 -c pytorch -c conda-forge<br/><br/>conda install torchcsprng cpuonly -c pytorch -c conda-forge |
96+
| macOS | None | conda install torchcsprng -c pytorch |
6797

6898
pip:
6999

70-
| OS | CUDA | |
71-
|---------|-----------------------------------------------|-------------------------------------------------------------------------------------|
72-
| Linux | 9.2<br/><br/>10.1<br/><br/>10.2<br/><br/>None | pip install torchcsprng==0.1.2+cu92 torch==1.6.0+cu92 -f https://download.pytorch.org/whl/torch_stable.html <br/><br/>pip install torchcsprng==0.1.2+cu101 torch==1.6.0+cu101 -f https://download.pytorch.org/whl/torch_stable.html <br/><br/>pip install torchcsprng torch<br/><br/>pip install torchcsprng==0.1.2+cpu torch==1.6.0+cpu -f https://download.pytorch.org/whl/torch_stable.html |
73-
| macOS | None | pip install torchcsprng torch |
74-
| Windows | None | pip install torchcsprng torch -f https://download.pytorch.org/whl/torch_stable.html |
100+
| OS | CUDA | |
101+
|---------------|------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
102+
| Linux/Windows | 10.1<br/><br/>10.2<br/><br/>11.1<br/><br/>None | pip install torchcsprng==0.2.0+cu101 torch==1.8.0+cu101 -f https://download.pytorch.org/whl/cu101/torch_stable.html <br/><br/>pip install torchcsprng==0.2.0 torch==1.8.0 -f https://download.pytorch.org/whl/cu102/torch_stable.html <br/><br/>pip install torchcsprng==0.2.0+cu111 torch==1.8.0+cu111 -f https://download.pytorch.org/whl/cu111/torch_stable.html <br/><br/>pip install torchcsprng==0.2.0+cpu torch==1.8.0+cpu -f https://download.pytorch.org/whl/cpu/torch_stable.html |
103+
| macOS | None | pip install torchcsprng torch |
75104

76105
### Nightly builds:
77106

78107
Anaconda:
79108

80-
| OS | CUDA | |
81-
|---------|-----------------------------------------------|------------------------------------------------------|
82-
| Linux | 9.2<br/><br/>10.1<br/><br/>10.2<br/><br/>None | conda install torchcsprng cudatoolkit=9.2 -c pytorch-nightly<br/><br/>conda install torchcsprng cudatoolkit=10.1 -c pytorch-nightly<br/><br/>conda install torchcsprng cudatoolkit=10.2 -c pytorch-nightly<br/><br/>conda install torchcsprng cpuonly -c pytorch-nightly |
83-
| macOS | None | conda install torchcsprng cpuonly -c pytorch-nightly |
84-
| Windows | None | conda install torchcsprng cpuonly -c pytorch-nightly |
109+
| OS | CUDA | |
110+
|---------------|------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
111+
| Linux/Windows | 10.1<br/><br/>10.2<br/><br/>11.1<br/><br/>None | conda install torchcsprng cudatoolkit=10.1 -c pytorch-nightly -c conda-forge<br/><br/>conda install torchcsprng cudatoolkit=10.2 -c pytorch-nightly -c conda-forge<br/><br/>conda install torchcsprng cudatoolkit=11.1 -c pytorch-nightly -c conda-forge<br/><br/>conda install torchcsprng cpuonly -c pytorch-nightly -c conda-forge |
112+
| macOS | None | conda install torchcsprng -c pytorch-nightly |
85113

86114
pip:
87115

88-
| OS | CUDA | |
89-
|---------|-----------------------------------------------|----------------------------------------------------------------------------------------------------|
90-
| Linux | 9.2<br/><br/>10.1<br/><br/>10.2<br/><br/>None | pip install --pre torchcsprng -f https://download.pytorch.org/whl/nightly/cu92/torch_nightly.html <br/><br/> pip install --pre torchcsprng -f https://download.pytorch.org/whl/nightly/cu101/torch_nightly.html <br/><br/> pip install --pre torchcsprng -f https://download.pytorch.org/whl/nightly/cu102/torch_nightly.html <br/><br/> pip install --pre torchcsprng -f https://download.pytorch.org/whl/nightly/cpu/torch_nightly.html |
91-
| macOS | None | pip install --pre torchcsprng -f https://download.pytorch.org/whl/nightly/cpu/torch_nightly.html |
92-
| Windows | None | pip install --pre torchcsprng -f https://download.pytorch.org/whl/nightly/cpu/torch_nightly.html |
116+
| OS | CUDA | |
117+
|---------------|------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
118+
| Linux/Windows | 10.1<br/><br/>10.2<br/><br/>11.1<br/><br/>None | pip install --pre torchcsprng -f https://download.pytorch.org/whl/nightly/cu101/torch_nightly.html <br/><br/> pip install --pre torchcsprng -f https://download.pytorch.org/whl/nightly/cu102/torch_nightly.html <br/><br/> pip install --pre torchcsprng -f https://download.pytorch.org/whl/nightly/cu111/torch_nightly.html <br/><br/> pip install --pre torchcsprng -f https://download.pytorch.org/whl/nightly/cpu/torch_nightly.html |
119+
| macOS | None | pip install --pre torchcsprng -f https://download.pytorch.org/whl/nightly/cpu/torch_nightly.html |
93120

94121
### From Source
95122

96-
torchcsprng is a Python C++/CUDA extension that depends on PyTorch. In order to build CSPRNG from source it is required to have Python(>=3.6) with PyTorch(>=1.6.0) installed and C++ compiler(gcc/clang for Linux, XCode for macOS, Visual Studio for MS Windows).
123+
torchcsprng is a Python C++/CUDA extension that depends on PyTorch. In order to build CSPRNG from source it is required to have Python(>=3.7) with PyTorch(>=1.8.0) installed and C++ compiler(gcc/clang for Linux, XCode for macOS, Visual Studio for MS Windows).
97124
To build torchcsprng you can run the following:
98125
```console
99126
python setup.py install

0 commit comments

Comments
 (0)