Skip to content

Latest commit

 

History

History
321 lines (235 loc) · 8.16 KB

00_INDEX.md

File metadata and controls

321 lines (235 loc) · 8.16 KB

node-jose-tools Documentation

Contents

Examples

Creating new keys

> jose newkey -t RSA -s 2048
> jose newkey -t oct -s 256

Adding a key to a keystore

> jose addkey -j mykeystore.jwks privatekey.PEM

This will return the extended key store to STDOUT.

For updating the key store use the following variant:

> jose addkey -U -j mykeystore.jwks privatekey.PEM

Add a remote key store locally

This is useful to cache public keys from a server.

> jose addkey -j example.jwks https://your.server.host/certs

This will return the extended local key store.

Use the -U flag to update the local key store.

It is possible to read any supported key-format from a URL.

Merging two keystores

> jose addkey -j example.jwks example-priv.jwks

Note: if the key stores contain the same key ids, then this will result in duplicate key ids in the key store file.

Again, use the -U to store the extended key store into mykeystore.jwks

List the key ids for all keys in a keystore

> jose listkeys -b -j example.jwks

This will print one key id per line, so the result will be:

[
   "foobar",
   "barfoo",
   "foorsa"
]

Remove keys from a keystore

> jose rmkey -b -j example.jwks foorsa

This will output a JWKS without the key "foorsa".

{
    "keys": [
        {
            "kty":"oct",
            "kid":"foobar",
            "k":"QYPTbIwxRbVuCLU0T3lQWYGP05asffZLAuM1KiNyqj4"
        },
        {
            "kty":"oct",
            "kid":"barfoo",
            "k":"-E_-rcOr6iesQ_BKO21DAuKdblhUmwciIx8Q6gUcUuG42Fw0zdPHPQtfZh19upvrh1Epevwz3Yc2a3YMGCJh1w"
        }
    ]
}

If you like to have less spaces in the output, remove the -b flag.

For updating the key store use the -U or --update flag.

> jose rmkey -U -j example.jwks foorsa

Create a new key and add it to a keystore

> jose newkey -t oct -s 256 | jose addkey -U -j mykeystore.jwks

Alternatively, one can write this command:

> jose newkey -t oct -s 256 -U -j mykeystore.jwks

Tip: the -q flag silences the command and it will not prompt any other output than error messages

Create multiple keys

The -K flag tells the newkey tool to return the key store instead of an individual key.

> jose newkey -t oct -s 256 -K |  jose newkey -t ec -s 256 -K |  jose newkey -t rsa -s 2048 -K | jose addkey -U -j mykeystore.jwks

Find the key for a given keyid

> jose findkey -j example.jwks foobar

This will return the private key for the key foobar, if present.

To export the public key, use

> jose findkey -p -b -j example-priv.jwks foorsa

This results in the following output:

{
    "kty":"RSA",
    "kid":"foorsa",
    "e":"AQAB",
    "n":"sFhX2R0ColcUrlU224bzhvCOwngQGGc23BT4btYBtMlM9kEnC_rHpbI45P4LGqGZO-vy8
PK9d9DPtvkdwsc1gxMOe__HoxwSG8aaapEd4NXgMKKXviAJUJbkY7pb9NHvImm6_1ESm6FRT4a
5LdRp5kAJdbfuwkfNRQxzWf-p3wYZoUMxcz3fAdWME55Z7y_YMTIMAI3hbRSw50eaNoY4gggGK
Huz42PrDeclxtQJFI_-nzm7jzEvs_JFIZ0yyTePi4nTOLWNzSFcc43gcfHHOK5okXuiAmZyu-3
voH3rnU85Xb2lkZrQd4Rjxhf6YNYzTzCsmh6Aa2gAloHBqfJU9Q"
}

The -b flag makes the output more readable. If you want a plain JSON string, you can remove this flag

Wrap a RFC7800 confirmation key

To wrap the key into RFC7800 key confirmation use:

> jose findkey -c -b -j example.jwks foobar

This results in:

{
    "cnf":{
        "jwk":{
            "kty":"oct",
            "kid":"foobar",
            "k":"QYPTbIwxRbVuCLU0T3lQWYGP05asffZLAuM1KiNyqj4"
        }
    }
}

To pass a key reference as a RFC7800 key confirmation use:

> jose findkey -b -r -j example.jwks foobar

This results in:

{
    "cnf":{
        "kid":"foobar"
    }
}

Create a JWS token

> jose sign -j example.jwks -a audience -i clientid -l HS256 -k foobar

This results in the following compact JWS (linebreaks are inserted for readability):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImZvb2JhciJ9.eyJleHRyYSI6e30sImlz
cyI6ImNsaWVudGlkIiwiYXVkIjoiYXVkaWVuY2UiLCJzdWIiOiJjbGllbnRpZCIsImlhdCI6MTUxN
DAyMTg5MH0.3n7UkVtMA12ZuQ7fjf0h6FsmPqusTBOrs7N7zNMTcfg

Add some extra payload via STDIN.

> echo '{"payload": "mypayload"}' | jose sign -j example.jwks -a audience -i clientid -l HS256 -k foobar -p

This will result in:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImZvb2JhciJ9.eyJwYXlsb2FkIjoibXlw
YXlsb2FkIiwiaXNzIjoiY2xpZW50aWQiLCJhdWQiOiJhdWRpZW5jZSIsInN1YiI6ImNsaWVudGlkI
iwiaWF0IjoxNTE0MDIyMTA0fQ.gRSQAU8HcoVnkAcXeeBPGyaFI2qdAD5wsR31AbpkBYc

Use the -F flag to request the flattened JWS format:

> jose sign -j example.jwks -a audience -i clientid -l HS256 -k foobar -F

will result in:

{
    "payload":"eyJleHRyYSI6e30sImlzcyI6ImNsaWVudGlkIiwiYXVkIjoiYXVkaWVuY2UiLCJzdWIiOiJjbGllbnRpZCIsImlhdCI6MTUxNDAyMjIxNX0",
    "protected":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImZvb2JhciJ9",
    "signature":"XfsZELWK84ZPiANAls8GbeYk7dg06HDDE94YhPT57EY"
}

Use the -G flag to load get the general JWS format.

Verify a JWS

> jose verify -j example.jwks  -a audience -i issuer token.jwt

You can also pass the token via stdin:

> echo TOKENSTRING | jose verify -j example.jwks -a audience -i issuer

Encrypt a payload using RSA-OAEP and AES126GCM

> echo PAYLOADSTRING | jose encrypt -j example.jwks -k foorsa -l RSA-OAEP -e A126GCM -p

Encrypt a string using the dir algorithm

> jose encrypt -j example.jwks -k foobar -l dir "hello world"

Decrypt a JWE for you

> echo JWETOKENSTRING | jose decrypt -j example-priv.jwks

Create a wrapped JWT (using RSA-OAEP and AES126GCM)

Note that you are free to use any of the other alg/enc combinations if you have the appropriate keys.

> jose sign -j example.jwks -a audience -i myid -l HS256 | jose encrypt -j example.jwks -k foorsa -l RSA-OAEP -e A126GCM -p

Create a confirmation key for a targeted audience in a wrapped JWT:

> jose findkey -k -j example.jwks barfoo | jose sign -j example.jwks -k foobar -a audience -i myid -l HS256 | jose encrypt -j example.jwks -k foorsa -l RSA-OAEP -e A126GCM -p

Unwrap a JWE and verify an included JWS

> echo TOKENSTRING | jose decrypt -j example-priv.jwks | jose verify -j example.jwks -a audience -i issuer