Security Considerations#
Security Considerations
HTTPS and TLS 1.2 or greater SHALL be used in order to enforce a secure communication method.
Authentication
A JSON Web Token (JWT) SHALL be created by the server upon successful client authentication and returned to the client to use as an authorization mechanism for accessing the server resources - see JSON Web Token (JWT) below for more information. Since AMVP is targeted for validation authorities only, it SHALL use TLS mutual certificate authentication.
The client SHALL return the token to the server via the Authorization Bearer header in all subsequent HTTP requests.
The server MAY provide a JWT that includes additional claims. The claims will link the user to a set of data created by the user. If the user wishes to interact with that data, the user SHALL use the JWT with the claims.
JSON Web Token (JWT)
JSON Web Token is described in RFC 7519 and is used as an authorization mechanism for gaining access to different resources.
{
"alg" : "none"
}
{
"iss" : "nist.gov",
"nbf": 1598293915,
"exp": 1598295715,
"iat": 1598293915,
"pkey" : "cc74f56acdba635079383a03941d68db55c7b3c2f (truncated)"
}
{
}The JWT can be secured if desired using the header encryption "alg" value defined to HS256(HMAC-SHA256) or one of the other secure values. Key agreement would follow RFC7518.
{
"alg": "HS256",
"typ": "JWT"
}
{
"iss" : "nist.gov",
"nbf": 1598293915,
"exp": 1598295715,
"iat": 1598293915,
"pkey" : "cc74f56acdba635079383a03941d68db55c7b3c2f (truncated)"
}
{
"{signature}"
}where "{signature}" is made up of:
HMACSHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)
and where "HMACSHA256" is the algorithm specified in the JWT header.
The first four claims are required, however "pkey" is an optional private claim used to pass the key used for encrypting the database at the server. Enabling this option is discussed further in the Messaging section.
Authorization flows with JWT
JSON Web Token is described in RFC 7519 and is used as an authorization mechanism for gaining access to different resources.
In order to access any resource which requires authorization a client must supply the JWT as an Authorization header value as a Bearer token. An example header value is:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5c (truncated)"
Workflow authorization flows. All exchanges shown are over HTTP.
+--------+---------------------------------+------+--------+
| Client | |Server| Notes |
+--------+---------------------------------+------+--------+
| |POST to /login or similar with | | |
| |appropriate credentials | | |
| |-------------------------------->| | |
| | | | |
| |receive the access token | | |
| |<- - - - - - - - - - - | | |
| | | | |
POST: [{"passcode":"66008332"}]
200 OK: [{"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....}]
JWT Expiration/Renewal
The JWT access tokens received from either the /login server endpoint SHALL be set to expire after a pre-defined period. The specific length of the expiration period is out of scope for this specification. However, the expiration period length impacts both the security and protocol overhead. Longer expiration periods reduce the overhead but increase the window for attacks. Attempting to access a service with an expired JWT SHALL result in a "401 Unauthorized" HTTP status code.
A client may renew an expired JWT access token using the mechanism shown in [RenewalFlows] below.
JWT access token renewal flows. All exchanges shown are over HTTP.
+--------+---------------------------------+------+--------+
| Client | |Server| Notes |
+--------+---------------------------------+------+--------+
| |POST to /login or similar with | | |
| |appropriate credentials | | |
| |and expired JWT access token | | |
| |-------------------------------->| |session |
| | | |or |
| | | |login |
| | | |JWT |
| |receive the renewed access token | | |
| |<- - - - - - - - - - - | | |
Server returns 401
POST: [[{"passcode":"47682787","accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....}]]
200 OK: [{"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.....}]