Updating documentation.

NOKEYCHECK=True
PiperOrigin-RevId: 278352044
GitOrigin-RevId: 941c9bc63eac1ada29f92e035f69e1b36007eb48
This commit is contained in:
bleichen
2019-11-04 04:43:32 -08:00
committed by Tink Team
parent 68482d5d8d
commit 70e9c3d98f
2 changed files with 144 additions and 67 deletions
+52 -31
View File
@@ -238,7 +238,7 @@ Type of the test vectors\: [SignatureTestVector](types.md#SignatureTestVector)
**name** | **tests** | **validity** | **algorithm** {.sortable}
--------------- | --------- | ------------ | -------------
ed448_test.json | 86 | 17, 0, 69 | EDDSA
eddsa_test.json | 112 | 51, 0, 61 | EDDSA
eddsa_test.json | 145 | 84, 0, 61 | EDDSA
## HkdfTest {#HkdfTest}
@@ -255,9 +255,9 @@ Type of the test vectors\: [HkdfTestVector](types.md#HkdfTestVector)
**name** | **tests** | **validity** | **algorithm** {.sortable}
--------------------- | --------- | ------------ | -------------
hkdf_sha1_test.json | 61 | 61, 0, 0 | HKDF-SHA-1
hkdf_sha256_test.json | 60 | 60, 0, 0 | HKDF-SHA-256
hkdf_sha512_test.json | 57 | 57, 0, 0 | HKDF-SHA-512
hkdf_sha1_test.json | 100 | 100, 0, 0 | HKDF-SHA-1
hkdf_sha256_test.json | 99 | 99, 0, 0 | HKDF-SHA-256
hkdf_sha512_test.json | 96 | 96, 0, 0 | HKDF-SHA-512
## IndCpaTest {#IndCpaTest}
@@ -336,6 +336,20 @@ gmac_test.json | 449 | 102, 0, 347 | AES-GMAC
vmac_128_test.json | 764 | 424, 0, 340 | VMAC-AES
vmac_64_test.json | 764 | 508, 0, 256 | VMAC-AES
## PrimalityTest {#PrimalityTest}
Test vector of type PrimalityTest are intended for testing primality tests.
JSON schema\: primality_test_schema.json
Type of the test group\: [PrimalityTestGroup](types.md#PrimalityTestGroup)
Type of the test vectors\: [PrimalityTestVector](types.md#PrimalityTestVector)
**name** | **tests** | **validity** | **algorithm** {.sortable}
------------------- | --------- | ------------ | -------------
primality_test.json | 280 | 66, 8, 206 | PrimalityTest
## RsaesOaepDecrypt {#RsaesOaepDecrypt}
Test vectors of type RsaOeapDecrypt are intended to check the decryption of RSA
@@ -431,24 +445,29 @@ Type of the test group\: [RsassaPkcs1TestGroup](types.md#RsassaPkcs1TestGroup)
Type of the test vectors\: [SignatureTestVector](types.md#SignatureTestVector)
**name** | **tests** | **validity** | **algorithm** {.sortable}
------------------------------------- | --------- | ------------ | -------------
rsa_signature_2048_sha224_test.json | 241 | 7, 1, 233 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha256_test.json | 240 | 7, 3, 230 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha3_224_test.json | 249 | 7, 1, 241 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha3_256_test.json | 248 | 7, 1, 240 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha3_384_test.json | 249 | 7, 1, 241 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha3_512_test.json | 249 | 7, 1, 241 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha512_test.json | 240 | 7, 2, 231 | RSASSA-PKCS1-v1_5
rsa_signature_3072_sha256_test.json | 239 | 7, 2, 230 | RSASSA-PKCS1-v1_5
rsa_signature_3072_sha384_test.json | 239 | 7, 1, 231 | RSASSA-PKCS1-v1_5
rsa_signature_3072_sha3_256_test.json | 248 | 7, 1, 240 | RSASSA-PKCS1-v1_5
rsa_signature_3072_sha3_384_test.json | 249 | 7, 1, 241 | RSASSA-PKCS1-v1_5
rsa_signature_3072_sha3_512_test.json | 249 | 7, 1, 241 | RSASSA-PKCS1-v1_5
rsa_signature_3072_sha512_test.json | 240 | 7, 2, 231 | RSASSA-PKCS1-v1_5
rsa_signature_4096_sha384_test.json | 239 | 7, 1, 231 | RSASSA-PKCS1-v1_5
rsa_signature_4096_sha512_test.json | 239 | 7, 1, 231 | RSASSA-PKCS1-v1_5
rsa_signature_test.json | 377 | 84, 63, 230 | RSASSA-PKCS1-v1_5
**name** | **tests** | **validity** | **algorithm** {.sortable}
--------------------------------------- | --------- | ------------ | -------------
rsa_signature_2048_sha224_test.json | 241 | 7, 1, 233 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha256_test.json | 240 | 7, 3, 230 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha384_test.json | 252 | 7, 1, 244 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha3_224_test.json | 249 | 7, 1, 241 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha3_256_test.json | 248 | 7, 1, 240 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha3_384_test.json | 249 | 7, 1, 241 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha3_512_test.json | 249 | 7, 1, 241 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha512_224_test.json | 252 | 7, 1, 244 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha512_256_test.json | 251 | 7, 1, 243 | RSASSA-PKCS1-v1_5
rsa_signature_2048_sha512_test.json | 240 | 7, 2, 231 | RSASSA-PKCS1-v1_5
rsa_signature_3072_sha256_test.json | 239 | 7, 2, 230 | RSASSA-PKCS1-v1_5
rsa_signature_3072_sha384_test.json | 239 | 7, 1, 231 | RSASSA-PKCS1-v1_5
rsa_signature_3072_sha3_256_test.json | 248 | 7, 1, 240 | RSASSA-PKCS1-v1_5
rsa_signature_3072_sha3_384_test.json | 249 | 7, 1, 241 | RSASSA-PKCS1-v1_5
rsa_signature_3072_sha3_512_test.json | 249 | 7, 1, 241 | RSASSA-PKCS1-v1_5
rsa_signature_3072_sha512_256_test.json | 251 | 7, 1, 243 | RSASSA-PKCS1-v1_5
rsa_signature_3072_sha512_test.json | 240 | 7, 2, 231 | RSASSA-PKCS1-v1_5
rsa_signature_4096_sha384_test.json | 239 | 7, 1, 231 | RSASSA-PKCS1-v1_5
rsa_signature_4096_sha512_256_test.json | 251 | 7, 1, 243 | RSASSA-PKCS1-v1_5
rsa_signature_4096_sha512_test.json | 239 | 7, 1, 231 | RSASSA-PKCS1-v1_5
rsa_signature_test.json | 377 | 84, 63, 230 | RSASSA-PKCS1-v1_5
## RsassaPssVerify {#RsassaPssVerify}
@@ -465,15 +484,17 @@ Type of the test group\: [RsassaPssTestGroup](types.md#RsassaPssTestGroup)
Type of the test vectors\: [RsassaPssTestVector](types.md#RsassaPssTestVector)
**name** | **tests** | **validity** | **algorithm** {.sortable}
------------------------------------- | --------- | ------------ | -------------
rsa_pss_2048_sha1_mgf1_20_test.json | 82 | 0, 42, 40 | RSASSA-PSS
rsa_pss_2048_sha256_mgf1_0_test.json | 100 | 61, 0, 39 | RSASSA-PSS
rsa_pss_2048_sha256_mgf1_32_test.json | 103 | 63, 0, 40 | RSASSA-PSS
rsa_pss_3072_sha256_mgf1_32_test.json | 103 | 63, 0, 40 | RSASSA-PSS
rsa_pss_4096_sha256_mgf1_32_test.json | 103 | 63, 0, 40 | RSASSA-PSS
rsa_pss_4096_sha512_mgf1_32_test.json | 171 | 132, 0, 39 | RSASSA-PSS
rsa_pss_misc_test.json | 150 | 120, 30, 0 | RSASSA-PSS
**name** | **tests** | **validity** | **algorithm** {.sortable}
----------------------------------------- | --------- | ------------ | -------------
rsa_pss_2048_sha1_mgf1_20_test.json | 82 | 0, 42, 40 | RSASSA-PSS
rsa_pss_2048_sha256_mgf1_0_test.json | 100 | 61, 0, 39 | RSASSA-PSS
rsa_pss_2048_sha256_mgf1_32_test.json | 103 | 63, 0, 40 | RSASSA-PSS
rsa_pss_2048_sha512_256_mgf1_28_test.json | 50 | 9, 0, 41 | RSASSA-PSS
rsa_pss_2048_sha512_256_mgf1_32_test.json | 49 | 9, 0, 40 | RSASSA-PSS
rsa_pss_3072_sha256_mgf1_32_test.json | 103 | 63, 0, 40 | RSASSA-PSS
rsa_pss_4096_sha256_mgf1_32_test.json | 103 | 63, 0, 40 | RSASSA-PSS
rsa_pss_4096_sha512_mgf1_32_test.json | 171 | 132, 0, 39 | RSASSA-PSS
rsa_pss_misc_test.json | 150 | 120, 30, 0 | RSASSA-PSS
## XdhAsnComp {#XdhAsnComp}
+92 -36
View File
@@ -2,7 +2,7 @@
# Test vector types
Version\: 0.8rc15
Version\: 0.8rc17
[TOC]
@@ -156,14 +156,14 @@ An EC public key. The EC public key can specify the underlying curve parameters
in two ways. (1) as a named curve (2) as a structure containing the curve
parameters generator, order and cofactor.
**name** | **type** | **desc** | **enum**
------------ | -------------------------------------------------------------- | --------------------------------------------------- | --------
curve | typing.Union[ec_groups.EcUnnamedGroup, ec_groups.EcNamedGroup] | the EC group used by this public key |
keySize | int | the key size in bits |
type | str | the key type | 'EcPublicKey'
uncompressed | [HexBytes](formats.md#DataTypes) | X509 encoded public key point in hexadecimal format |
wx | [BigInt](formats.md#DataTypes) | the x-coordinate of the public key point |
wy | [BigInt](formats.md#DataTypes) | the y-coordinate of the public key point |
**name** | **type** | **desc** | **enum**
------------ | -------------------------------- | --------------------------------------------------- | --------
curve | (EcUnnamedGroup or EcNamedGroup) | the EC group used by this public key |
keySize | int | the key size in bits |
type | str | the key type | 'EcPublicKey'
uncompressed | [HexBytes](formats.md#DataTypes) | X509 encoded public key point in hexadecimal format |
wx | [BigInt](formats.md#DataTypes) | the x-coordinate of the public key point |
wy | [BigInt](formats.md#DataTypes) | the y-coordinate of the public key point |
## EcPublicKeyOnNamedCurve {#EcPublicKeyOnNamedCurve}
@@ -516,6 +516,36 @@ kid | str | the key identifier |
kty | str | the key type | 'OKP'
x | [Base64Url](formats.md#DataTypes) | the public key value |
## KdfTestGroup {#KdfTestGroup}
A test group for key derivation functions that take 2 arguments (seed, size) as
input.
Fields in KdfTestGroup are\:
**name** | **type** | **desc** | **enum**
-------- | ----------------------------------------------- | ---------------------------- | --------
keySize | int | the size of the seed in bits |
type | str | the type of the test | '[KdfTest](files.md#KdfTest)'
tests | List of [KdfTestVector](types.md#KdfTestVector) | a list of test vectors |
## KdfTestVector {#KdfTestVector}
A test vector for key derivation functions. I.e., these are deterministic
functions that take a seed and a size as input and generate a pseudorandom
output depending on the seed. (The size may simply determine the length of the
pseudorandom output or may change the pseudorandom stream).
Fields additional to the fields in TestVector are\:
**name** | **type** | **desc**
-------- | -------------------------------- | --------
seed | [HexBytes](formats.md#DataTypes) | the seed
size | int | the size of the output in bytes
okm | [HexBytes](formats.md#DataTypes) | the generated bytes (output key material)
Used in [KdfTestGroup](#KdfTestGroup).
## KeywrapTestGroup {#KeywrapTestGroup}
Fields in KeywrapTestGroup are\:
@@ -596,23 +626,49 @@ tag | [HexBytes](formats.md#DataTypes) | the authentication tag
Used in [MacWithIvTestGroup](#MacWithIvTestGroup).
## PrimalityTestGroup {#PrimalityTestGroup}
A test group for primality tests.
Fields in PrimalityTestGroup are\:
**name** | **type** | **desc** | **enum**
-------- | ----------------------------------------------------------- | ---------------------- | --------
type | str | the type of the test | '[PrimalityTest](files.md#PrimalityTest)'
tests | List of [PrimalityTestVector](types.md#PrimalityTestVector) | a list of test vectors |
## PrimalityTestVector {#PrimalityTestVector}
A test vector for a primality test. The result is valid if value is prime and
invalid if it is 0, 1, -1 or composite. The status of the negative of a prime is
somewhat unlclear. Some libraries accept them as primes. Because of this the
negative of a prime has result "acceptable".
Fields additional to the fields in TestVector are\:
**name** | **type** | **desc**
-------- | ------------------------------ | -------------------
value | [BigInt](formats.md#DataTypes) | the integer to test
Used in [PrimalityTestGroup](#PrimalityTestGroup).
## RsaPrivateKey {#RsaPrivateKey}
Describes an RSA private key. The data type is based on the RSAPrivateKey type
defined in Section A.1.2 of RFC 8017.
**name** | **type** | **desc** | **enum**
--------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | --------
coefficient | [BigInt](formats.md#DataTypes) | the CRT value q^(-1) % p |
exponent1 | [BigInt](formats.md#DataTypes) | the value d % (p-1) |
exponent2 | [BigInt](formats.md#DataTypes) | the value d % (q-1) |
modulus | [BigInt](formats.md#DataTypes) | the modulus of the key |
otherPrimeInfos | List | list of triples [prime, exponent, coefficient] |
prime1 | [BigInt](formats.md#DataTypes) | p: a prime factor of the modulus |
prime2 | [BigInt](formats.md#DataTypes) | q: a prime factor of the modulus |
privateExponent | [BigInt](formats.md#DataTypes) | the private exponent |
publicExponent | [BigInt](formats.md#DataTypes) | the public exponent |
version | int | The version of the private key. This is 0 for keys with no otherPrimeInfos and 1 for keys with otherPrimeInfos, i.e. multiprime keys. | 0, 1
**name** | **type** | **desc** | **enum**
--------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------
coefficient | [BigInt](formats.md#DataTypes) | the CRT value q^(-1) % p |
exponent1 | [BigInt](formats.md#DataTypes) | the value d % (p-1) |
exponent2 | [BigInt](formats.md#DataTypes) | the value d % (q-1) |
modulus | [BigInt](formats.md#DataTypes) | the modulus of the key |
otherPrimeInfos | list of list of [BigInt](formats.md#DataTypes) | list of triples [prime, exponent, coefficient] |
prime1 | [BigInt](formats.md#DataTypes) | p: a prime factor of the modulus |
prime2 | [BigInt](formats.md#DataTypes) | q: a prime factor of the modulus |
privateExponent | [BigInt](formats.md#DataTypes) | the private exponent |
publicExponent | [BigInt](formats.md#DataTypes) | the public exponent |
version | int | The version of the private key. This is 0 for keys with no otherPrimeInfos and 1 for keys with otherPrimeInfos, i.e. multiprime keys. | 0, 1
## RsaPublicKey {#RsaPublicKey}
@@ -819,15 +875,15 @@ The root type of each JSON file with tests. Each file contains one ore more test
groups. Each test group contains one ore more test vectors. All test vectors in
the same file have the same type and test the same cryptographic primitive.
**name** | **type** | **desc** | **since**
---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------
algorithm | str | The primitive tested in the test file. This is mainly a brief description of the algorithm used. So far there is no formal definition of this field and its description may change. |
generatorVersion | str | The version of the test vectors. The version number has the format major.minor (or major.minor[release candidate]). The plan is to change the format of the test vectors in major versions only, once version 1.0 has been reached. Conversely, version 1.0 will be published once we think the format for the test vectors are sufficiently stable. |
header | List | additional documentation |
notes | JSON | A description of the labels used in the test vectors. Some test vectors contain labels that formally describe the test vector. It can be helpful to make test more precise. For example libraries differ in whether they accept ASN encodings different from DER. Hence many of the test vectors with alternative BER encoding are rated as acceptable. Labels allow to decide whether tests with alternatve BER encoding should be rejected or accepted when testing a particular library. |
numberOfTests | int | The number of test vectors in this test. Each test vector has a unique tcId in the range 1 .. tcId. |
schema | str | The filename of the JSON schema that defines the format of the test vectors in this file. If the format of the test vectors changes then a new schema will be generate, so that comparing the name of the schema with an expected name can be used to check for compatibility between test vectors and test code. | 0.7
testGroups | List | a list of test groups |
**name** | **type** | **desc** | **since**
---------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------
algorithm | str | The primitive tested in the test file. This is mainly a brief description of the algorithm used. So far there is no formal definition of this field and its description may change. |
generatorVersion | str | The version of the test vectors. The version number has the format major.minor (or major.minor[release candidate]). The plan is to change the format of the test vectors in major versions only, once version 1.0 has been reached. Conversely, version 1.0 will be published once we think the format for the test vectors are sufficiently stable. |
header | list of str | additional documentation |
notes | JSON | A description of the labels used in the test vectors. Some test vectors contain labels that formally describe the test vector. It can be helpful to make test more precise. For example libraries differ in whether they accept ASN encodings different from DER. Hence many of the test vectors with alternative BER encoding are rated as acceptable. Labels allow to decide whether tests with alternatve BER encoding should be rejected or accepted when testing a particular library. |
numberOfTests | int | The number of test vectors in this test. Each test vector has a unique tcId in the range 1 .. tcId. |
schema | str | The filename of the JSON schema that defines the format of the test vectors in this file. If the format of the test vectors changes then a new schema will be generate, so that comparing the name of the schema with an expected name can be used to check for compatibility between test vectors and test code. | 0.7
testGroups | list of JSON | a list of test groups |
## TestGroup {#TestGroup}
@@ -850,12 +906,12 @@ type | str | the type of the test
## TestVector {#TestVector}
**name** | **type** | **desc** | **enum**
-------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------
comment | str | A brief description of the test case |
flags | List | A list of flags for a test case. Flags are described in the header of the test file. |
result | str | The test result. The value determines whether the test case is valid, invalid or undefined. The value "acceptable" is typically used for legacy cases, weak parameters (such as key sizes not reaching 112-bit security) or BER encoding that are frequent. Eventually, all test vectors with "result" : "acceptable" will have flags describing the reason and allowing testers to decide how to treat these test vectors. | 'valid', 'invalid', 'acceptable'
tcId | int | A unique identifier of the test case in a test file. The identifiers are continuous integers. The identifiers of test vectors change between versions of the test file. Hence, the triple (filename, version, tcId) uniquely identifies a test vector. |
**name** | **type** | **desc** | **enum**
-------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------
comment | str | A brief description of the test case |
flags | list of str | A list of flags for a test case. Flags are described in the header of the test file. |
result | str | The test result. The value determines whether the test case is valid, invalid or undefined. The value "acceptable" is typically used for legacy cases, weak parameters (such as key sizes not reaching 112-bit security) or BER encoding that are frequent. Eventually, all test vectors with "result" : "acceptable" will have flags describing the reason and allowing testers to decide how to treat these test vectors. | 'valid', 'invalid', 'acceptable'
tcId | int | A unique identifier of the test case in a test file. The identifiers are continuous integers. The identifiers of test vectors change between versions of the test file. Hence, the triple (filename, version, tcId) uniquely identifies a test vector. |
## XdhAsnTestGroup {#XdhAsnTestGroup}