- Tools
- addkey - add a new key to a JWKS
- newkey - create a new JWK key
- listkeys - list the key ids for all keys in a JWKS
- findkey - find a kid in a JWKS
- rmkey - remove a kid from a JWKS
- thumbprint - generate the thumbprint for a key
- info - return basic information about a JWT without processing it
- info - runs a selected hashing algorithm on the provided data.
- sign - creates and signs a JWS for a given payload
- verify - verifies a JWS and return the payload
- encrypt - encrypt a payload into a JWE
- decrypt - decrypts a JWE and returns the payload
- Examples
- Creating new keys
- Adding a key to a key store
- Add a remote key store locally
- Merging two key stores
- List the key ids in a key store
- Remove a key from a key store
- Create a new key and add it to a key store
- Create multiple keys
- Find a key for a key id
- Wrap a RFC7800 confirmation key
- Create a JWS token
- Verify a JWS token
- Encrypt a payload using RSA-OAEP and AES126GCM
- Encrypt a string using the dir algorithm
- Decrypt a JWE for you
- Create a wrapped JWT using RSA-OAEP and AES126GCM
- Unwrap a JWE and verify an included JWS
> jose newkey -t RSA -s 2048
> jose newkey -t oct -s 256
> 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
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.
> 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
> jose listkeys -b -j example.jwks
This will print one key id per line, so the result will be:
[
"foobar",
"barfoo",
"foorsa"
]
> 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
> 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
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
> 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
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"
}
}
> 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.
> 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
> echo PAYLOADSTRING | jose encrypt -j example.jwks -k foorsa -l RSA-OAEP -e A126GCM -p
> jose encrypt -j example.jwks -k foobar -l dir "hello world"
> echo JWETOKENSTRING | jose decrypt -j example-priv.jwks
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
> echo TOKENSTRING | jose decrypt -j example-priv.jwks | jose verify -j example.jwks -a audience -i issuer