{"schema":"libjg2-1", "vpath":"/git/", "avatar":"/git/avatar/", "alang":"", "gen_ut":1731654381, "reponame":"libwebsockets", "desc":"libwebsockets lightweight C networking library", "owner": { "name": "Andy Green", "email": "andy@warmcat.com", "md5": "c50933ca2aa61e0fe2c43d46bb6b59cb" },"url":"https://libwebsockets.org/repo/libwebsockets", "f":3, "items": [ {"schema":"libjg2-1", "cid":"7b01aa9e206151394e67b6fedae3ebe6", "oid":{ "oid": "6328231f2aa628632344d96a58e25c3b194af506", "alias": [ "refs/heads/main"]},"blobname": "READMEs/README.crypto-apis.md", "blob": "# Lws Crypto Apis\n\n## Overview\n\n\n\nLws provides a \u0022generic\u0022 crypto layer on top of both OpenSSL and\ncompatible tls library, and mbedtls. Using this layer, your code\ncan work without any changes on both types of tls library crypto\nbackends... it's as simple as rebuilding lws with `-DLWS_WITH_MBEDTLS\u003d0`\nor `\u003d1` at cmake.\n\nThe generic layer can be used directly (as in, eg, the sshd plugin),\nor via another layer on top, which processes JOSE JSON objects using\nJWS (JSON Web Signatures), JWK (JSON Web Keys), and JWE (JSON Web\nEncryption).\n\nThe `JW` apis use the generic apis (`lws_genrsa_`, etc) to get the crypto tasks\ndone, so anything they can do you can also get done using the generic apis.\nThe main difference is that with the generic apis, you must instantiate the\ncorrect types and use type-specfic apis. With the `JW` apis, there is only\none interface for all operations, with the details hidden in the api and\ncontrolled by the JSON objects.\n\nBecause of this, the `JW` apis are often preferred because they give you\n\u0022crypto agility\u0022 cheaply... to change your crypto to another supported algorithm\nonce it's working, you literally just change your JSON defining the keys and\nJWE or JWS algorithm. (It's up to you to define your policy for which\ncombinations are acceptable by querying the parsed JW structs).\n\n## Crypto supported in generic layer\n\n### Generic Hash\n\n - SHA1\n - SHA256\n - SHA384\n - SHA512\n\n### Generic HMAC\n\n - SHA256\n - SHA384\n - SHA512\n\n### Generic AES\n\n - CBC\n - CFB128\n - CFB8\n - CTR\n - ECB\n - OFB\n - XTS\n - GCM\n - KW (Key Wrap)\n\n### Generic RSA\n\n - PKCS 1.5\n - OAEP / PSS\n\n### Generic EC\n\n - ECDH\n - ECDSA\n - P256 / P384 / P521 (sic) curves\n\n## Using the generic layer\n\nAll the necessary includes are part of `libwebsockets.h`.\n\nEnable `-DLWS_WITH_GENCRYPTO\u003d1` at cmake.\n\n|api|header|Functionality|\n|---|---|---|\n|genhash|[./include/libwebsockets/lws-genhash.h](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-genhash.h)|Provides SHA1 + SHA2 hashes and hmac|\n|genrsa|[./include/libwebsockets/lws-genrsa.h](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-genrsa.h)|Provides RSA encryption, decryption, signing, verification, key generation and creation|\n|genaes|[./include/libwebsockets/lws-genaes.h](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-genaes.h)|Provides AES in all common variants for encryption and decryption|\n|genec|[./include/libwebsockets/lws-genec.h](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-genec.h)|Provides Elliptic Curve for encryption, decryption, signing, verification, key generation and creation|\n|x509|[./include/libwebsockets/lws-x509.h](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-x509.h)|Apis for X.509 Certificate loading, parsing, and stack verification, plus JWK key extraction from PEM X.509 certificate / private key|\n\nUnit tests for these apis, which serve as usage examples, can be found in [./minimal-examples/api-tests/api-test-gencrypto](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/api-tests/api-test-gencrypto)\n\n### Keys in the generic layer\n\nThe necessary types and defines are brought in by `libwebsockets.h`.\n\nKeys are represented only by an array of `struct lws_jwk_elements`... the\nlength of the array is defined by the cipher... it's one of\n\n|key elements count|definition|\n|---|---|\n|`LWS_COUNT_OCT_KEY_ELEMENTS`|1|\n|`LWS_COUNT_RSA_KEY_ELEMENTS`|8|\n|`LWS_COUNT_EC_KEY_ELEMENTS`|4|\n|`LWS_COUNT_AES_KEY_ELEMENTS`|1|\n\n`struct lws_jwk_elements` is a simple pointer / length combination used to\nstore arbitrary octets that make up the key element's binary representation.\n\n## Using the JOSE layer\n\nThe JOSE (JWK / JWS / JWE) stuff is a crypto-agile JSON-based layer\nthat uses the gencrypto support underneath.\n\n\u0022Crypto Agility\u0022 means the JSON structs include information about the\nalgorithms and ciphers used in that particular object, making it easy to\nupgrade system crypto strength or cycle keys over time while supporting a\ntransitional period where the old and new keys or algorithms + ciphers\nare also valid.\n\nUniquely lws generic support means the JOSE stuff also has \u0022tls library\nagility\u0022, code written to the lws generic or JOSE apis is completely unchanged\neven if the underlying tls library changes between OpenSSL and mbedtls, meaning\nsharing code between server and client sides is painless.\n\nAll the necessary includes are part of `libwebsockets.h`.\n\nEnable `-DLWS_WITH_JOSE\u003d1` at CMake.\n\n|api|header|Functionality|\n|---|---|---|\n|JOSE|[./include/libwebsockets/lws-jose.h](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-jose.h)|Provides crypto agility for JWS / JWE|\n|JWE|[./include/libwebsockets/lws-jwe.h](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-jwe.h)|Provides Encryption and Decryption services for RFC7516 JWE JSON|\n|JWS|[./include/libwebsockets/lws-jws.h](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-jws.h)|Provides signature and verifcation services for RFC7515 JWS JSON|\n|JWK|[./include/libwebsockets/lws-jwk.h](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-jwk.h)|Provides signature and verifcation services for RFC7517 JWK JSON, both \u0022keys\u0022 arrays and singletons|\n\nMinimal examples are provided in the form of commandline tools for JWK / JWS / JWE / x509 handling:\n\n - [JWK minimal example](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/crypto/minimal-crypto-jwk)\n - [JWS minimal example](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/crypto/minimal-crypto-jws)\n - [JWE minimal example](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/crypto/minimal-crypto-jwe)\n - [X509 minimal example](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/crypto/minimal-crypto-x509)\n\nUnit tests for these apis, which serve as usage examples, can be found in [./minimal-examples/api-tests/api-test-jose](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/api-tests/api-test-jose)\n\n## Crypto supported in the JOSE layer\n\nThe JOSE RFCs define specific short names for different algorithms\n\n### JWS\n\n|JSOE name|Hash|Signature|\n---|---|---\n|RS256, RS384, RS512|SHA256/384/512|RSA\n|ES256, ES384, ES521|SHA256/384/512|EC\n\n### JWE\n\n|Key Encryption|Payload authentication + crypt|\n|---|---|\n|`RSAES-PKCS1-v1.5` 2048b \u0026 4096b|`AES_128_CBC_HMAC_SHA_256`|\n|`RSAES-PKCS1-v1.5` 2048b|`AES_192_CBC_HMAC_SHA_384`|\n|`RSAES-PKCS1-v1.5` 2048b|`AES_256_CBC_HMAC_SHA_512`|\n|`RSAES-OAEP`|`AES_256_GCM`|\n|`AES128KW`, `AES192KW`, `AES256KW`|`AES_128_CBC_HMAC_SHA_256`|\n|`AES128KW`, `AES192KW`, `AES256KW`|`AES_192_CBC_HMAC_SHA_384`|\n|`AES128KW`, `AES192KW`, `AES256KW`|`AES_256_CBC_HMAC_SHA_512`|\n|`ECDH-ES` (P-256/384/521 key)|`AES_128/192/256_GCM`|\n|`ECDH-ES+A128/192/256KW` (P-256/384/521 key)|`AES_128/192/256_GCM`|\n\n### Keys in the JOSE layer\n\nKeys in the JOSE layer use a `struct lws_jwk`, this contains two arrays of\n`struct lws_jwk_elements` sized for the worst case (currently RSA). One\narray contains the key elements as described for the generic case, and the\nother contains various nonencrypted key metadata taken from JWK JSON.\n\n|metadata index|function|\n|---|---|\n|`JWK_META_KTY`|Key type, eg, \u0022EC\u0022|\n|`JWK_META_KID`|Arbitrary ID string|\n|`JWK_META_USE`|What the public key may be used to validate, \u0022enc\u0022 or \u0022sig\u0022|\n|`JWK_META_KEY_OPS`|Which operations the key is authorized for, eg, \u0022encrypt\u0022|\n|`JWK_META_X5C`|Optional X.509 cert version of the key|\n|`JWK_META_ALG`|Optional overall crypto algorithm the key is intended for use with|\n\n`lws_jwk_destroy()` should be called when the jwk is going out of scope... this\ntakes care to zero down any key element data in the jwk.\n\n","s":{"c":1731598537,"u": 376}} ],"g": 1474,"chitpc": 0,"ehitpc": 0,"indexed":0 , "ab": 0, "si": 0, "db":0, "di":0, "sat":0, "lfc": "7d0a"}