c0de/SmartPGP
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Restructure README

Browse Source
This commit is contained in:
c0de 2023-10-04 14:25:34 -05:00
parent e9584d79b8
commit 141cf85eb7
1 changed files with 39 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
README.md
View File

@ -3,82 +3,39 @@
SmartPGP is a free and open source implementation of the [OpenPGP card SmartPGP is a free and open source implementation of the [OpenPGP card
3.4 specification](https://gnupg.org/ftp/specs/OpenPGP-smart-card-application-3.4.pdf) in JavaCard. 3.4 specification](https://gnupg.org/ftp/specs/OpenPGP-smart-card-application-3.4.pdf) in JavaCard.
## Features ## Features
The following features are implemented at the applet level, but some The following features are implemented at the applet level, but some
of them depend on underlying hardware support and available of them depend on underlying hardware support and available
(non-)volatile memory resources: (non-)volatile memory resources:
- RSA (>= 2048 bits modulus, 17 bits exponent) for signature, - RSA (>= 2048 bits modulus, 17 bits exponent) for signature, encryption and authentication
encryption and authentication; - On-board key generation and external private key import
- PIN codes (user, admin and resetting code) up to 127 characters each
- On-board key generation and external private key import; - Certificate up to 1 kB (DER encoded) for each key
- Login, URL, and private DOs up to 256 bytes
- PIN codes (user, admin and resetting code) up to 127 characters; - Command and response chaining
- AES 128/256 bits deciphering primitive
- Certificate up to 1 kB (DER encoded) for each key;
- Login, URL, and private DOs up to 256 bytes;
- Command and response chaining;
- AES 128/256 bits deciphering primitive;
## Default values ## Default values
The SmartPGP applet is configured with the following default values: The SmartPGP applet is configured with the following default values:
- Admin PIN is 12345678; - Admin PIN is 12345678
- User PIN is 123456
- No PUK (a.k.a. resetting code) is defined
- RSA 2048 bits for PGP keys
- User PIN is 123456; These values can be changed by modifying the [Constants](src/dev/c0de/smartpgp/Constants.java) class.
- No PUK (a.k.a. resetting code) is defined; After the applet has been installed, the [smartpgp-cli](bin/smartpgp-cli) utility
will be able to change the above values.
- RSA 2048 bits for PGP keys; _Note: These settings are restored if you factory reset the applet._
These values can be changed by modifying default values in the code __Note: If you change algorithm attributes, the key and corresponding certificate will be erased.__
(see the [Constants](src/fr/anssi/smartpgp/Constants.java)
class).
When the applet is installed, one can use the `smartpgp-cli` utility ## Build and Install instructions
given in the `bin` directory to change these values. Keep in mind that
when you change the algorithm attributes of a PGP key, the key and the
corresponding certificate are
erased. Also note that hard coded default values will be restored upon
a factory reset.
# Application support
Tokens following the OpenPGP card 3.4 specification are not yet fully
supported by most PGP applications.
## GnuPG
OpenPGP card 3.x is supported by [GnuPG](https://www.gnupg.org/)
starting from version 2.1.16.
## OpenKeychain
OpenPGP card 3.x is supported by [OpenKeychain](https://www.openkeychain.org/)
starting from version 4.2.
# Content of the repository
The repository contains several directories:
- `bin` contains a Python library and command line tool called
`smartpgp-cli` to interact with an OpenPGP card 3.x;
- `src` contains the JavaCard source code of the SmartPGP applet;
- `videos` contains sample videos demonstrating smartcard interactions
with OpenKeychain and K9 mail on Android Nexus 5.
## Build and installation instructions
### Prerequisites ### Prerequisites
@ -93,11 +50,9 @@ The repository contains several directories:
### Importing RSA keys above 2048 bits ### Importing RSA keys above 2048 bits
The default internal buffer that stores keys is configured with a default The internal buffer that stores keys is configured with a default value that is only large enough for RSA 2048 bit keys.
value that is only large enough for RSA 2048 bit keys.
if your card is able to handle larger RSA key bit-lengths (3072 or 4096), If your card is able to handle larger RSA key bit-lengths (3072 or 4096), and you want to import those keys, you will need to increase the buffer size.
and you want to import those keys, you will need to increase the buffer size.
This can be accomplished by modifying `Constants.INTERNAL_BUFFER_MAX_LENGTH` in [Constants.java](src/dev/c0de/smartpgp/Constants.java) This can be accomplished by modifying `Constants.INTERNAL_BUFFER_MAX_LENGTH` in [Constants.java](src/dev/c0de/smartpgp/Constants.java)
@ -116,45 +71,46 @@ When produced by OpenPGP, these keys are 1294 Bytes in length.
When produced by OpenPGP, these keys are 1644 Bytes in length. When produced by OpenPGP, these keys are 1644 Bytes in length.
`Constants.INTERNAL_BUFFER_MAX_LENGTH` may not be smaller than `(short)0x66d` (decimal: 1645) `Constants.INTERNAL_BUFFER_MAX_LENGTH` may not be smaller than `(short)0x66d` (decimal: 1645)
## Reducing flash and/or RAM consumption ### Reducing flash and/or RAM consumption
The applet allocates all its data structures to their maximal size When the applet is installed, all data structures will be allocated
at installation to avoid as much as possible runtime errors caused by to their maximum size. This is a standard practice for JavaCard applets
memory allocation failure. If your device does not have enough flash to ensure that there will not be a memory allocation failure at runtime.
and/or RAM available, or if you plan not to use some features
(e.g. stored certificates), you can adjust the applet to reduce its A consequence of this is that, if you configure a large rsa key and
resource consumption by tweaking the following variables: use a small key, that extra space can not be used for anything else.
If your device does not have enough flash memory and/or RAM, or you plan
to not use some features (eg. on-device certificates), you can modify
the following variables in [Constants.java](src/dev/c0de/smartpgp/Constants.java)
- `Constants.INTERNAL_BUFFER_MAX_LENGTH`: the size in bytes of the - `Constants.INTERNAL_BUFFER_MAX_LENGTH`: the size in bytes of the
internal RAM buffer used for input/output chaining. Chaining is internal RAM buffer used for input/output chaining. Chaining is
especially used in case of long commands and responses such as those especially used in case of long commands and responses such as those
involved in private key import and certificate import/export; involved in private key import and certificate import/export;
- `Constants.EXTENDED_CAPABILITIES`, bytes 5 and 6: the maximal size - `Constants.EXTENDED_CAPABILITIES`, bytes 5 and 6: the maximum size
in bytes of a certificate associated to a key. Following the OpenPGP in bytes of a certificate associated to a key. The default is 1152 Bytes.
card specification, a certificate can be stored for each of the A certificate can be stored for each of the three keys.
three keys.
### Building the CAP file
## Building the CAP file
- (Optional) Edit the `build.xml` file and replace the `APPLET_AID` - (Optional) Edit the `build.xml` file and replace the `APPLET_AID`
with your a unique value. Alternatively, set the with your a unique value. Alternatively, set the
right AID instance bytes during applet installation. right AID instance bytes during applet installation.
Generate the AID using [this tool](https://c0de.dev/c0de/SmartPGP-AID-Generator) Generate the AID using [this tool](https://c0de.dev/c0de/SmartPGP-AID-Generator)
- Execute `ant` with no parameter to build `SmartPGPApplet.cap` - Execute `ant` to build `SmartPGPApplet.cap`
## Installing the CAP file ### Installing the CAP file
The CAP file installation depends on your device, so you have to refer The CAP file installation depends on your device, so you have to refer
to the instructions given by your device manufacturer. Most open cards to the instructions given by your device manufacturer. Most open cards
relying on Global Platform with default keys are supported by relying on Global Platform with default keys are supported by
[GlobalPlatformPro](https://github.com/martinpaljak/GlobalPlatformPro). [GlobalPlatformPro](https://github.com/martinpaljak/GlobalPlatformPro).
Be careful to use a valid AID according to the OpenPGP card You must use a valid, unique AID that matches the OpenPGP card specification (see section 4.2.1)
specification (see section 4.2.1) for each card (`-create <AID>` with for each card (`-create <AID>` with GlobalPlatformPro)
GlobalPlatformPro)
Example Installation commands: Example Installation commands: