Sovos.com Contact Support

e-invoicing

TrustWeaver

About stored cryptographic keys

A stored cryptographic key is a private key and X.509 certificate belonging to a corroboration party, stored in that party's section in advance of corroboration operations that require it.

Some corroboration operations require the use of a cryptographic key that belongs to one of the corroboration parties. For example, when signing on behalf of a Mexican entity using their own certificate. These keys must be stored in the party's storage section before the corroboration operation is submitted.

After a key is stored, a it is assigned a 32-digit hexadecimal reference. The key can then be selected during corroboration in two ways:

  • Directly, by providing the key reference in the KeyReferences element of a CorroborationSpec.

  • Indirectly, using the section name. TrustWeaver selects an applicable key from the section based on the corroboration policy.

You can associate a key with a branch by including its reference in the CryptoKeyReference field of the branch's BranchInfo. When associated this way, the key is selected automatically from the branch identity during corroboration. To learn more, see the About branches.

Note: Keys are stored at the section level, not the branch level. A key stored in a section can be associated with one or more branches in that section, but it can't be used in operations for a different section.

Manage cryptographic keys

The admin service provides five operations for managing stored cryptographic keys. Each is a single API call to the admin service endpoint. Before storing a key, confirm that the target storage section is registered. To learn more, see Register and enable a section.

StoreCryptoKey operation

Stores a private key and its associated X.509 certificate in a section. Returns a reference that identifies the stored key in the following operations:

Request elements

Request type taa:StoreCryptoKeyRequest extends tac:TrustArchiveRequest

Element Type Cardinality Description
Name xs:string 1 The section name. Maximum 80 characters.
KeyData xs:base64Binary 1 The private key data in binary format. Maximum 100,000 bytes. When Certificate is provided, this must be an encrypted PKCS #8 private key associated with that certificate. When Certificate is omitted, this must be a PKCS #12 container including both the private key and its certificate.
Certificate xs:base64Binary 0..1 The X.509 public key certificate associated with the private key. Maximum 100,000 bytes. May only be omitted when KeyData holds a PKCS #12 container.
KeyPwd xs:string 0..1 Password to decrypt the private key in KeyData. Required when KeyData is included. Maximum 250 characters.
KeyProvider xs:string 0..1 Identifies the provider that issued the certificate and private key material. Valid values are outside the scope of this document.
Request example
CODE 
<StoreCryptoKey xmlns="http://www.trustweaver.com/trustarchive/admin/v1"
                xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1">
  <Request>
    <tac:TransactionId>3580f...</tac:TransactionId>
    <Name>customer1</Name>
    <KeyData>ABCD1234</KeyData>
    <Certificate>ABCD1234</Certificate>
    <KeyPwd>Password</KeyPwd>
  </Request>
</StoreCryptoKey>
Response

Result type: taa:StoreCryptoKeyResult. Returns the 32-digit hexadecimal reference assigned to the stored key:

CODE 
<StoreCryptoKeyResponse
  xmlns="http://www.trustweaver.com/trustarchive/admin/v1">
  <Result>
    <Reference>ABCD1234</Reference>
  </Result>
</StoreCryptoKeyResponse>
Error codes
For error codes returned by this operation, see Admin service error codes.

RemoveCryptoKey operation

Removes a stored key using its reference. A key that is referenced by one or more branches can't be removed until the branch associations are cleared.

Request elements

Request type taa:RemoveCryptoKeyRequest extends tac:TrustArchiveRequest.

Element Type Cardinality Description
Reference xs:string 1 The 32-digit hexadecimal reference to the stored key to remove.
Request example
CODE 
<RemoveCryptoKey xmlns="http://www.trustweaver.com/trustarchive/admin/v1"
                 xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1">
  <Request>
    <tac:TransactionId>3580f...</tac:TransactionId>
    <Reference>ABCD1234.</Reference>
  </Request>
</RemoveCryptoKey>
Response

A successful response contains no sub-elements:

CODE 
<RemoveCryptoKeyResponse
  xmlns="http://www.trustweaver.com/trustarchive/admin/v1"/>
Error codes
For error codes returned by this operation, see Admin service error codes.

ReplaceCryptoKey operation

Replaces the key and certificate of an existing stored key entry, retaining the original reference. Use this operation to rotate a key without updating all references to it.

Request elements

Request type taa:ReplaceCryptoKeyRequest extends tac:TrustArchiveRequest

Element Type Cardinality Description
Reference xs:string 1 The reference to the stored key to replace.
KeyData xs:base64Binary 0..1 Same as KeyData in StoreCryptoKey.
Certificate xs:base64Binary 0..1 Same as Certificate in StoreCryptoKey.
KeyPwd xs:string 0..1 Same as KeyPwd in StoreCryptoKey.
KeyProvider xs:string 0..1 Same as KeyProvider in StoreCryptoKey.
Request example
CODE 
<ReplaceCryptoKey xmlns="http://www.trustweaver.com/trustarchive/admin/v1"
                  xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1">
  <Request>
    <tac:TransactionId>3580f...</tac:TransactionId>
    <Reference>ABCD1234</Reference>
    <KeyData>ABCD1234</KeyData>
    <Certificate>ABCD1234</Certificate>
    <KeyPwd>Password</KeyPwd>
  </Request>
</ReplaceCryptoKey>
Response

A successful response contains no sub-elements:

CODE 
<ReplaceCryptoKeyResponse
  xmlns="http://www.trustweaver.com/trustarchive/admin/v1"/>
Error codes
For error codes returned by this operation, see Admin service error codes.

ListCryptoKeys

Returns the references of all cryptographic keys stored in a section.

Request elements

Request type taa:ListCryptoKeysRequest extends tac:TrustArchiveRequest

Element Type Cardinality Description
Name xs:string 1 The section name. Maximum 80 characters.
Request example
CODE 
<ListCryptoKeys xmlns="http://www.trustweaver.com/trustarchive/admin/v1"
                xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1">
  <Request>
    <tac:TransactionId>e38e7...</tac:TransactionId>
    <Name>section1</Name>
  </Request>
</ListCryptoKeys>
Response

Returns a References collection of 32-digit hexadecimal key references. The collection is empty if no keys are stored in the section.

CODE 
<ListCryptoKeysResponse xmlns="http://www.trustweaver.com/trustarchive/admin/v1"
                        xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1">
  <Result>
    <References>
      <Reference>ABCD1234</Reference>
      <Reference>ABCD1234</Reference>
    </References>
  </Result>
</ListCryptoKeysResponse>
Error codes
For error codes returned by this operation, see Admin service error codes.

GetCryptoKeyInfo

Retrieves certificate information about a stored key using its reference.

Request elements

Request type taa:GetCryptoKeyInfoRequest extends tac:TrustArchiveRequest

Element Type Cardinality Description
Reference xs:string 1 The 32-digit hexadecimal reference to the stored key.
Request example
CODE 
<GetCryptoKeyInfo xmlns="http://www.trustweaver.com/trustarchive/admin/v1"
                  xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1">
  <Request>
    <tac:TransactionId>e270d...</tac:TransactionId>
    <Reference>ABCD1234</Reference>
  </Request>
</GetCryptoKeyInfo>
Response elements

Result type: taa:GetCryptoKeyInfoResponse

Element Type Cardinality Description
Reference xs:string 1 The reference to the stored key
Certificate xs:base64Binary 1 The X.509 public key certificate
Subject xs:string 1 The subject distinguished name from the certificate
NotBefore xs:dateTime 1 The UTC date and time from which the certificate is valid
NotAfter xs:dateTime 1 The UTC date and time after which the certificate is no longer valid
Thumbprint xs:base64Binary 1 The SHA-1 thumbprint of the certificate
CODE 
<GetCryptoKeyInfoResponse
  xmlns="http://www.trustweaver.com/trustarchive/admin/v1">
  <Result>
    <Reference>ABCD1234</Reference>
    <Certificate>ABCD1234</Certificate>
    <Subject>CN=Test, C=SE</Subject>
    <NotBefore>2012-01-05T00:00:00Z</NotBefore>
    <NotAfter>2112-01-04T23:59:59Z</NotAfter>
    <Thumbprint>ABCD1234</Thumbprint>
  </Result>
</GetCryptoKeyInfoResponse>
Error codes
For error codes returned by this operation, see Admin service error codes.
Trustweaver

Last updated: September 30, 2026