| .. |
| Copyright 2019,2020 NXP |
| |
| SPDX-License-Identifier: Apache-2.0 |
| |
| .. _apis-sss_key-format: |
| |
| ====================================================================== |
| SSS api key format (asymmetric keys) |
| ====================================================================== |
| |
| |
| NIST-P, NIST-K and BRAINPOOL ECC Keys |
| ====================================================================== |
| |
| When passing the key pair / public key, the key should be passed DER encoded using PKCS #8 or traditional openssl format. |
| When passing the private key alone, do not include the key header. |
| |
| When retrieving the key pair as data argument from the sss_key_store_get api, the full key pair cannot be retrieved. Instead the public key value is returned in ANSI X9.62 uncompressed format. |
| |
| .. note:: Keys, signature and shared secret key generated all follow the big endian convention. |
| |
| |
| EDWARD and MONTGOMERY ECC keys |
| ====================================================================== |
| |
| When passing the key pair / public key, the key should be passed DER encoded using the format specified in RFC 8410. |
| When passing the private key alone, do not include the key header. |
| |
| When retrieving the key pair as data argument from the sss_key_store_get api, the full key pair cannot be retrieved. Instead the public key value is returned in ANSI X9.62 uncompressed format. |
| |
| .. note:: Keys, signature and shared secret key generated all follow the little endian convention. |
| |
| A set of examples of a X25519 keypair encoded according to RFC 8410:: |
| |
| $ dumpasn1 X25519_keypair.der |
| 0 81: SEQUENCE { |
| 2 1: INTEGER 1 |
| 5 5: SEQUENCE { |
| 7 3: OBJECT IDENTIFIER curveX25519 (1 3 101 110) |
| : } |
| 12 34: OCTET STRING, encapsulates { |
| 14 32: OCTET STRING |
| : 58 5D B1 E3 50 0B 71 24 F6 B1 E1 41 83 54 93 12 |
| : F4 4B 0C A3 44 F7 52 A1 8A 12 2F E7 DA D9 CE 52 |
| : } |
| 48 33: [1] |
| : 00 A2 8E 04 FF 1C DC 1C 3D 60 91 0F BC 98 EF 01 |
| : BF 9F 0F 69 C0 B7 EF 70 61 35 34 62 F3 06 28 C7 |
| : 29 |
| : } |
| |
| $ dumpasn1 X25519_priv.pem |
| 0 46: SEQUENCE { |
| 2 1: INTEGER 0 |
| 5 5: SEQUENCE { |
| 7 3: OBJECT IDENTIFIER curveX25519 (1 3 101 110) |
| : } |
| 12 34: OCTET STRING, encapsulates { |
| 14 32: OCTET STRING |
| : 58 5D B1 E3 50 0B 71 24 F6 B1 E1 41 83 54 93 12 |
| : F4 4B 0C A3 44 F7 52 A1 8A 12 2F E7 DA D9 CE 52 |
| : } |
| : } |
| |
| $ dumpasn1 X25519_pub.pem |
| 0 42: SEQUENCE { |
| 2 5: SEQUENCE { |
| 4 3: OBJECT IDENTIFIER curveX25519 (1 3 101 110) |
| : } |
| 9 33: BIT STRING |
| : A2 8E 04 FF 1C DC 1C 3D 60 91 0F BC 98 EF 01 BF |
| : 9F 0F 69 C0 B7 EF 70 61 35 34 62 F3 06 28 C7 29 |
| : } |
| |
| |
| The X25519 keypair from the example above can be created with the asn1parse OpenSSL tool. |
| The command line invocation is as follows:: |
| |
| openssl asn1parse -genconf key_config.txt -out X25519_keypair.der |
| |
| The file **key_config.txt** contains the different ASN.1 components and values of the keypair to create. |
| The resulting DER representation of the keypair is stored in the file **X25519_keypair.der**. |
| The contents of the **key_config.txt** file is as follows:: |
| |
| asn1 = SEQUENCE:seq_section |
| |
| [seq_section] |
| |
| field1 = INTEGER:1 |
| field2 = SEQUENCE:seq_section_oid |
| field3 = OCTWRAP,FORMAT:HEX,OCT:585DB1E3500B7124F6B1E14183549312F44B0CA344F752A18A122FE7DAD9CE52 |
| field4 = IMP:1C,INT:0x00A28E04FF1CDC1C3D60910FBC98EF01BF9F0F69C0B7EF7061353462F30628C729 |
| |
| [seq_section_oid] |
| |
| field1 = OID:X25519 |
| |
| .. note:: Additional information on the *asn1parse* command and the key configuration format is available under the manpages of respectively *asn1parse* and *ASN1_generate_nconf* |
| |
| BN Curve ECC keys |
| ====================================================================== |
| When passing key pair, private key or public key do not include key header. |
| When retrieving the key from the sss_key_store_get api, the public key value is returned without any header. |
| |
| |
| RSA keys |
| ====================================================================== |
| |
| When passing the key pair / public key, the key should be passed DER encoded using PKCS #8 or traditional openssl format. |
| When passing the private key alone, do not include the key header. |
| |
| When retrieving the key pair as data argument from the sss_key_store_get API, the full key pair cannot be retrieved. Instead the public key value is returned in ANSI X9.62 uncompressed format. |