Class SSHAgentParams

Static ReadonlyINDEX

salt

• get salt(): Salt

  Returns the salt.

  Returns Salt

id

• get id(): string

  Returns the SSH key identity: the comment of the agent identity; lock sets it from the secret.

  Returns string

Staticfrom

• from(__namedParameters?: { id?: string; salt?: Salt }): SSHAgentParams

  Parameters with a fresh random salt unless one is given, and an empty id unless one is given.

  Parameters

  • __namedParameters: { id?: string; salt?: Salt } = {}

  Returns SSHAgentParams

index

• index(): number

  Returns the method index for CBOR encoding.

  Returns number

lock

• lock(contentKey: SymmetricKey, secret: Uint8Array): EncryptedMessage

  Derive a key with an SSH agent and encrypt the content key, the reference's lock.

  Without options there is no agent to ask, and the call throws SshAgent. With options.agent:

  1. secret is the id: the comment of the identity to use, as UTF-8 (SSH Agent secret must be a valid UTF-8 string otherwise).
  2. The agent's identities are listed and reduced to the Ed25519 ones (No Ed25519 identities available in SSH agent when there is none).
  3. An empty id takes the only identity (Multiple identities available in SSH agent, but no ID provided when there are several); a non-empty id takes the identity with that comment (No matching identity found).
  4. The agent signs the salt (SSH agent refused to sign on any failure).
  5. The encryption key is HKDF-SHA256 of the signature with the salt.
  6. id is stored in these parameters, which are then the additional authenticated data; the content key is encrypted with options.nonce or a random nonce.

  Parameters

  • contentKey: SymmetricKey
  • secret: Uint8Array

  Returns EncryptedMessage

  Throws

  SshAgent as listed above.

• lock(
      contentKey: SymmetricKey,
      secret: Uint8Array,
      options: SshAgentLockOptions,
  ): Promise<EncryptedMessage>

  Derive a key with an SSH agent and encrypt the content key, the reference's lock.

  Without options there is no agent to ask, and the call throws SshAgent. With options.agent:

  1. secret is the id: the comment of the identity to use, as UTF-8 (SSH Agent secret must be a valid UTF-8 string otherwise).
  2. The agent's identities are listed and reduced to the Ed25519 ones (No Ed25519 identities available in SSH agent when there is none).
  3. An empty id takes the only identity (Multiple identities available in SSH agent, but no ID provided when there are several); a non-empty id takes the identity with that comment (No matching identity found).
  4. The agent signs the salt (SSH agent refused to sign on any failure).
  5. The encryption key is HKDF-SHA256 of the signature with the salt.
  6. id is stored in these parameters, which are then the additional authenticated data; the content key is encrypted with options.nonce or a random nonce.

  Parameters

  • contentKey: SymmetricKey
  • secret: Uint8Array
  • options: SshAgentLockOptions

  Returns Promise<EncryptedMessage>

  Throws

  SshAgent as listed above.

unlock

• unlock(encryptedMessage: EncryptedMessage, secret: Uint8Array): SymmetricKey

  Derive a key with an SSH agent and decrypt the content key, the reference's unlock.

  Without options there is no agent to ask, and the call throws SshAgent. With options.agent the identity is chosen, among the agent's Ed25519 identities, by the first of these that applies: the secret's id when non-empty, the stored id when non-empty (each by comment, No matching identity found otherwise), else the first identity. The agent signs the stored salt, the key is derived as in lock, and the message is decrypted.

  Parameters

  • encryptedMessage: EncryptedMessage
  • secret: Uint8Array

  Returns SymmetricKey

  Throws

  SshAgent for the secret, identity and signing failures of lock; Crypto Failed to decrypt the encrypted key: <reason> when the message does not decrypt (a wrong identity, tampered data), and Crypto Failed to convert decrypted key to SymmetricKey: <reason> when the plaintext is not a symmetric key.

• unlock(
      encryptedMessage: EncryptedMessage,
      secret: Uint8Array,
      options: SshAgentUnlockOptions,
  ): Promise<SymmetricKey>

  Derive a key with an SSH agent and decrypt the content key, the reference's unlock.

  Without options there is no agent to ask, and the call throws SshAgent. With options.agent the identity is chosen, among the agent's Ed25519 identities, by the first of these that applies: the secret's id when non-empty, the stored id when non-empty (each by comment, No matching identity found otherwise), else the first identity. The agent signs the stored salt, the key is derived as in lock, and the message is decrypted.

  Parameters

  • encryptedMessage: EncryptedMessage
  • secret: Uint8Array
  • options: SshAgentUnlockOptions

  Returns Promise<SymmetricKey>

  Throws

  SshAgent for the secret, identity and signing failures of lock; Crypto Failed to decrypt the encrypted key: <reason> when the message does not decrypt (a wrong identity, tampered data), and Crypto Failed to convert decrypted key to SymmetricKey: <reason> when the plaintext is not a symmetric key.

toString

• toString(): string

  Get string representation.

  Returns string

equals

• equals(other: SSHAgentParams): boolean

  Check equality with another SSHAgentParams.

  Parameters

  • other: SSHAgentParams

  Returns boolean

toCbor

• toCbor(): Cbor

  Convert to CBOR. Format: [4, Salt, id: tstr] (Salt is encoded as a tagged value — #6.40018(bytes))

  Returns Cbor

toCborData

• toCborData(): Uint8Array

  Convert to CBOR binary data.

  Returns Uint8Array

StaticfromCbor

• fromCbor(cborValue: Cbor): SSHAgentParams

  From the CBOR array, as the reference's TryFrom<CBOR> (a dcbor error): every failure is Cbor with the bare message. The index element is read as a usize (with dcbor's negative wrap) and its value ignored; the fixed-width fields wrap the same way.

  Parameters

  • cborValue: Cbor

  Returns SSHAgentParams